diff options
| -rw-r--r-- | clang/docs/JSONCompilationDatabase.html | 86 |
1 files changed, 86 insertions, 0 deletions
diff --git a/clang/docs/JSONCompilationDatabase.html b/clang/docs/JSONCompilationDatabase.html new file mode 100644 index 00000000000..d5c97250628 --- /dev/null +++ b/clang/docs/JSONCompilationDatabase.html @@ -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> + |
