Author: Sam McCall Date: 2022-01-17T09:51:55+01:00 New Revision: 16949762dc6a670d2f3a1f5043262ec31e09c556
URL: https://github.com/llvm/llvm-project/commit/16949762dc6a670d2f3a1f5043262ec31e09c556 DIFF: https://github.com/llvm/llvm-project/commit/16949762dc6a670d2f3a1f5043262ec31e09c556.diff LOG: [docs] Clarify & update JSONCompilationDatabase docs - prefer `arguments` over `command`, and add example - clarify that there's no shell-unescaping of `arguments` Fixes https://github.com/llvm/llvm-project/issues/53143 Differential Revision: https://reviews.llvm.org/D117428 Added: Modified: clang/docs/JSONCompilationDatabase.rst Removed: ################################################################################ diff --git a/clang/docs/JSONCompilationDatabase.rst b/clang/docs/JSONCompilationDatabase.rst index fd822c78d1fe..3595cf452f4c 100644 --- a/clang/docs/JSONCompilationDatabase.rst +++ b/clang/docs/JSONCompilationDatabase.rst @@ -63,8 +63,13 @@ Example: [ { "directory": "/home/user/llvm/build", - "command": "/usr/bin/clang++ -Irelative -DSOMEDEF=\"With spaces, quotes and \\-es.\" -c -o file.o file.cc", + "arguments": ["/usr/bin/clang++", "-Irelative", "-DSOMEDEF=With spaces, quotes and \\-es.", "-c", "-o", "file.o", "file.cc"], "file": "file.cc" }, + + { "directory": "/home/user/llvm/build", + "command": "/usr/bin/clang++ -Irelative -DSOMEDEF=\"With spaces, quotes and \\-es.\" -c -o file.o file.cc", + "file": "file2.cc" }, + ... ] @@ -78,14 +83,17 @@ The contracts for each field in the command object are: compilation database. There can be multiple command objects for the same file, for example if the same source file is compiled with diff erent configurations. -- **command:** The compile command executed. After JSON unescaping, - this must be a valid command to rerun the exact compilation step for - the translation unit in the environment the build system uses. - Parameters use shell quoting and shell escaping of quotes, with '``"``' - and '``\``' being the only special characters. Shell expansion is not - supported. -- **arguments:** The compile command executed as list of strings. - Either **arguments** or **command** is required. +- **arguments:** The compile command argv as list of strings. + This should run the compilation step for the translation unit ``file``. + ``arguments[0]`` should be the executable name, such as ``clang++``. + Arguments should not be escaped, but ready to pass to ``execvp()``. +- **command:** The compile command as a single shell-escaped string. + Arguments may be shell quoted and escaped following platform conventions, + with '``"``' and '``\``' being the only special characters. Shell expansion + is not supported. + + Either **arguments** or **command** is required. **arguments** is preferred, + as shell (un)escaping is a possible source of errors. - **output:** The name of the output created by this compilation step. This field is optional. It can be used to distinguish diff erent processing modes of the same input file. _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
