| <!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>. 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 |
| "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> |
| |