<html>
<head>
<base href="https://bugs.llvm.org/">
</head>
<body><table border="1" cellspacing="0" cellpadding="8">
<tr>
<th>Bug ID</th>
<td><a class="bz_bug_link
bz_status_NEW "
title="NEW - JSON Compilation Database docs unclear on meaning of "arguments""
href="https://bugs.llvm.org/show_bug.cgi?id=47489">47489</a>
</td>
</tr>
<tr>
<th>Summary</th>
<td>JSON Compilation Database docs unclear on meaning of "arguments"
</td>
</tr>
<tr>
<th>Product</th>
<td>Documentation
</td>
</tr>
<tr>
<th>Version</th>
<td>trunk
</td>
</tr>
<tr>
<th>Hardware</th>
<td>PC
</td>
</tr>
<tr>
<th>OS</th>
<td>Linux
</td>
</tr>
<tr>
<th>Status</th>
<td>NEW
</td>
</tr>
<tr>
<th>Severity</th>
<td>enhancement
</td>
</tr>
<tr>
<th>Priority</th>
<td>P
</td>
</tr>
<tr>
<th>Component</th>
<td>General docs
</td>
</tr>
<tr>
<th>Assignee</th>
<td>unassignedbugs@nondot.org
</td>
</tr>
<tr>
<th>Reporter</th>
<td>matthijs@stdin.nl
</td>
</tr>
<tr>
<th>CC</th>
<td>llvm-bugs@lists.llvm.org
</td>
</tr></table>
<p>
<div>
<pre>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]: <a href="https://clang.llvm.org/docs/JSONCompilationDatabase.html">https://clang.llvm.org/docs/JSONCompilationDatabase.html</a>
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).
<span class="quote">> 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" },
> ...
> ]</span >
<span class="quote">> - 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.</span >
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
<a class="bz_bug_link
bz_status_NEW "
title="NEW - Quoting in the compilation database example is wrong"
href="show_bug.cgi?id=21505">https://bugs.llvm.org/show_bug.cgi?id=21505</a> so I just left the example
as-is here.</pre>
</div>
</p>
<hr>
<span>You are receiving this mail because:</span>
<ul>
<li>You are on the CC list for the bug.</li>
</ul>
</body>
</html>