forked from OSchip/llvm-project
88 lines
3.6 KiB
HTML
88 lines
3.6 KiB
HTML
<!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 for specifying how to replay
|
|
single compilations independently of the build system.</p>
|
|
|
|
<h2>Background</h2>
|
|
<p>Tools based on the C++ Abstract Syntax Tree 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> (since 2.8.5) supports 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>. libclang and its
|
|
python bindings also support this (since clang 3.2); see
|
|
<a href="/doxygen/group__COMPILATIONDB.html">CXCompilationDatabase.h</a>.</p>
|
|
|
|
<h2>Format</h2>
|
|
<p>A compilation database is a JSON file, which consist of an array of
|
|
"command objects", where each command object specifies one way a translation unit
|
|
is compiled in the project.</p>
|
|
<p>Each command 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
|
|
command objects for the same file, for example if the same source file 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>
|
|
|