Add documentation for the JSON compilation database format.
llvm-svn: 158365
This commit is contained in:
parent
5452aa5f47
commit
6d6baa88f6
|
@ -0,0 +1,86 @@
|
|||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
||||
"http://www.w3.org/TR/html4/strict.dtd">
|
||||
<html>
|
||||
<head>
|
||||
<title>JSON Compilation Database Format Specification</title>
|
||||
<link type="text/css" rel="stylesheet" href="../menu.css">
|
||||
<link type="text/css" rel="stylesheet" href="../content.css">
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<!--#include virtual="../menu.html.incl"-->
|
||||
|
||||
<div id="content">
|
||||
|
||||
<h1>JSON Compilation Database Format Specification</h1>
|
||||
<p>This document describes a format to specify how to replay
|
||||
single compilations independently of the build system.</p>
|
||||
|
||||
<h2>Background</h2>
|
||||
<p>Tools based on the C++ AST need full information how to
|
||||
parse a translation unit. Usually this information is implicitly
|
||||
available in the build system, but running tools as part of
|
||||
the build system is not necessarily the best solution:
|
||||
<ul>
|
||||
<li>Build systems are inherently change driven, so running multiple
|
||||
tools over the same code base without changing the code does not fit
|
||||
into the architecture of many build systems.</li>
|
||||
<li>Figuring out whether things have changed is often an IO bound
|
||||
process; this makes it hard to build low latency end user tools based
|
||||
on the build system.</li>
|
||||
<li>Build systems are inherently sequential in the build graph, for example
|
||||
due to generated source code. While tools that run independently of the
|
||||
build still need the generated source code to exist, running tools multiple
|
||||
times over unchanging source does not require serialization of the runs
|
||||
according to the build dependency graph.</li>
|
||||
</ul>
|
||||
</p>
|
||||
|
||||
<h2>Supported Systems</h2>
|
||||
<p>Currently <a href="http://cmake.org">CMake</a> support generation of compilation
|
||||
databases for Unix Makefile builds (Ninja builds in the works) with the option
|
||||
CMAKE_EXPORT_COMPILE_COMMANDS.</p>
|
||||
<p>Clang's tooling interface supports reading compilation databases; see
|
||||
the <a href="LibTooling.html">LibTooling documentation</a>. Support for libclang
|
||||
is in the works.</p>
|
||||
|
||||
<h2>Format</h2>
|
||||
<p>A compilation database is a JSON file, which consist of an array of
|
||||
objects, where each object specifies one way a translation unit
|
||||
is compiled in the project.</p>
|
||||
<p>Each object contains the translation unit's main file, the working
|
||||
directory of the compile run and the actual compile command.</p>
|
||||
<p>Example:
|
||||
<pre>
|
||||
[
|
||||
{ "directory": "/home/user/llvm/build",
|
||||
"command": "/usr/bin/clang++ -Irelative -DSOMEDEF='\"With spaces and quotes.\"' -c -o file.o file.cc",
|
||||
"file": "file.cc" },
|
||||
...
|
||||
]
|
||||
</pre>
|
||||
The contracts for each field in the command object are:
|
||||
<ul>
|
||||
<li><b>directory:</b> The working directory of the compilation. All paths specified
|
||||
in the <b>command</b> or <b>file</b> fields must be either absolute or relative to
|
||||
this directory.</li>
|
||||
<li><b>file:</b> The main translation unit source processed by this compilation step.
|
||||
This is used by tools as the key into the compilation database. There can be multiple
|
||||
compile objects for the same file, for example if the same translation unit is
|
||||
compiled with different configurations.</li>
|
||||
<li><b>command:</b> 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.</li>
|
||||
</ul>
|
||||
</p>
|
||||
|
||||
<h2>Build System Integration</h2>
|
||||
<p>The convention is to name the file compile_commands.json and put it at the top
|
||||
of the build directory. Clang tools are pointed to the top of the build directory
|
||||
to detect the file and use the compilation database to parse C++ code in the source
|
||||
tree.</p>
|
||||
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
|
Loading…
Reference in New Issue