1============================================== 2JSON Compilation Database Format Specification 3============================================== 4 5This document describes a format for specifying how to replay single 6compilations independently of the build system. 7 8Background 9========== 10 11Tools based on the C++ Abstract Syntax Tree need full information how to 12parse a translation unit. Usually this information is implicitly 13available in the build system, but running tools as part of the build 14system is not necessarily the best solution: 15 16- Build systems are inherently change driven, so running multiple tools 17 over the same code base without changing the code does not fit into 18 the architecture of many build systems. 19- Figuring out whether things have changed is often an IO bound 20 process; this makes it hard to build low latency end user tools based 21 on the build system. 22- Build systems are inherently sequential in the build graph, for 23 example due to generated source code. While tools that run 24 independently of the build still need the generated source code to 25 exist, running tools multiple times over unchanging source does not 26 require serialization of the runs according to the build dependency 27 graph. 28 29Supported Systems 30================= 31 32Currently `CMake <http://cmake.org>`_ (since 2.8.5) supports generation 33of compilation databases for Unix Makefile builds (Ninja builds in the 34works) with the option ``CMAKE_EXPORT_COMPILE_COMMANDS``. 35 36For projects on Linux, there is an alternative to intercept compiler 37calls with a tool called `Bear <https://github.com/rizsotto/Bear>`_. 38 39Clang's tooling interface supports reading compilation databases; see 40the :doc:`LibTooling documentation <LibTooling>`. libclang and its 41python bindings also support this (since clang 3.2); see 42`CXCompilationDatabase.h </doxygen/group__COMPILATIONDB.html>`_. 43 44Format 45====== 46 47A compilation database is a JSON file, which consist of an array of 48"command objects", where each command object specifies one way a 49translation unit is compiled in the project. 50 51Each command object contains the translation unit's main file, the 52working directory of the compile run and the actual compile command. 53 54Example: 55 56:: 57 58 [ 59 { "directory": "/home/user/llvm/build", 60 "command": "/usr/bin/clang++ -Irelative -DSOMEDEF=\"With spaces, quotes and \\-es.\" -c -o file.o file.cc", 61 "file": "file.cc" }, 62 ... 63 ] 64 65The contracts for each field in the command object are: 66 67- **directory:** The working directory of the compilation. All paths 68 specified in the **command** or **file** fields must be either 69 absolute or relative to this directory. 70- **file:** The main translation unit source processed by this 71 compilation step. This is used by tools as the key into the 72 compilation database. There can be multiple command objects for the 73 same file, for example if the same source file is compiled with 74 different configurations. 75- **command:** The compile command executed. After JSON unescaping, 76 this must be a valid command to rerun the exact compilation step for 77 the translation unit in the environment the build system uses. 78 Parameters use shell quoting and shell escaping of quotes, with '``"``' 79 and '``\``' being the only special characters. Shell expansion is not 80 supported. 81 82Build System Integration 83======================== 84 85The convention is to name the file compile\_commands.json and put it at 86the top of the build directory. Clang tools are pointed to the top of 87the build directory to detect the file and use the compilation database 88to parse C++ code in the source tree. 89