[llvm-bugs] [Bug 47489] New: JSON Compilation Database docs unclear on meaning of "arguments"

[via llvm-bugs]

https://bugs.llvm.org/show_bug.cgi?id=47489

            Bug ID: 47489
           Summary: JSON Compilation Database docs unclear on meaning of
                    "arguments"
           Product: Documentation
           Version: trunk
          Hardware: PC
                OS: Linux
            Status: NEW
          Severity: enhancement
          Priority: P
         Component: General docs
          Assignee: unassignedbugs at nondot.org
          Reporter: matthijs at stdin.nl
                CC: llvm-bugs at lists.llvm.org

The Clang docs about compilation_commands.json [1] show two alternatives for
specifying the compile command: A single string shell-escaped compiler
commandline, and a pre-split arguments version.

[1]: https://clang.llvm.org/docs/JSONCompilationDatabase.html

However:
 - There is no example for the "arguments" version.
 - It is unclear where the command goes exactly. Should you specify the
   command (ARGV[0]) in "commands" and any arguments (ARGV[1+]) in
   "arguments"? Or should "arguments" contain the entire split
   commandline and should "commands" be omitted? Looking at
   implementations, it seems to be the latter.

I would propose making this more explicit. For example, maybe using the
following text and example (I'm not 100% sure this is correct, so feedback
welcome).

> Same example using arguments:
> [
>   { "directory": "/home/user/llvm/build",
>     "arguments": ["/usr/bin/clang++", "-Irelative", "-DSOMEDEF=With spaces, quotes and \-es.", "-c", "-o", "file.o", "file.cc",
>     "file": "file.cc" },
>   ...
> ]

>  - arguments: The compile command executed as list of strings. This includes
>    the compiler command itself, along with all its arguments. Each element of the
>    array is used as-is, without any further quoting other than the JSON-quoting.

The remark "Either arguments or command is required." should probably be
moved to below the enumeration of fields. Also, maybe it should be
clarified if it is acceptable to specify both (I think it is)? Also, I
think that "arguments" should be preferred (less ambiguity with
quoting), but is there a case for specifying "command" in addition" to
"arguments" for incomplete parsers (i.e. maybe "arguments" was added
later)?

Note that the quoting and backslash in the example does not seem to be
entirely sensible, but that's being discussed in
https://bugs.llvm.org/show_bug.cgi?id=21505 so I just left the example
as-is here.

-- 
You are receiving this mail because:
You are on the CC list for the bug.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-bugs/attachments/20200911/8ce41cae/attachment.html>