[PATCH] D117428: [docs] Clarify & update JSONCompilationDatabase docs

Sam McCall via Phabricator via cfe-commits cfe-commits at lists.llvm.org
Mon Jan 17 00:52:15 PST 2022

This revision was landed with ongoing or failed builds.
This revision was automatically updated to reflect the committed changes.
Closed by commit rG16949762dc6a: [docs] Clarify & update JSONCompilationDatabase docs (authored by sammccall).

  rG LLVM Github Monorepo




Index: clang/docs/JSONCompilationDatabase.rst
--- clang/docs/JSONCompilationDatabase.rst
+++ clang/docs/JSONCompilationDatabase.rst
@@ -63,8 +63,13 @@
       { "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 @@
    compilation database. There can be multiple command objects for the
    same file, for example if the same source file is compiled with
    different 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 different processing
    modes of the same input file.

-------------- next part --------------
A non-text attachment was scrubbed...
Name: D117428.400462.patch
Type: text/x-patch
Size: 2325 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20220117/fc6c21f4/attachment.bin>

More information about the cfe-commits mailing list