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