| 1 | ============================================== |
|---|
| 2 | JSON Compilation Database Format Specification |
|---|
| 3 | ============================================== |
|---|
| 4 | |
|---|
| 5 | This document describes a format for specifying how to replay single |
|---|
| 6 | compilations independently of the build system. |
|---|
| 7 | |
|---|
| 8 | Background |
|---|
| 9 | ========== |
|---|
| 10 | |
|---|
| 11 | Tools based on the C++ Abstract Syntax Tree need full information how to |
|---|
| 12 | parse a translation unit. Usually this information is implicitly |
|---|
| 13 | available in the build system, but running tools as part of the build |
|---|
| 14 | system 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 | |
|---|
| 29 | Supported Systems |
|---|
| 30 | ================= |
|---|
| 31 | |
|---|
| 32 | Currently `CMake <https://cmake.org>`_ (since 2.8.5) supports generation |
|---|
| 33 | of compilation databases for Unix Makefile builds (Ninja builds in the |
|---|
| 34 | works) with the option ``CMAKE_EXPORT_COMPILE_COMMANDS``. |
|---|
| 35 | |
|---|
| 36 | For projects on Linux, there is an alternative to intercept compiler |
|---|
| 37 | calls with a tool called `Bear <https://github.com/rizsotto/Bear>`_. |
|---|
| 38 | |
|---|
| 39 | Clang's tooling interface supports reading compilation databases; see |
|---|
| 40 | the :doc:`LibTooling documentation <LibTooling>`. libclang and its |
|---|
| 41 | python bindings also support this (since clang 3.2); see |
|---|
| 42 | `CXCompilationDatabase.h </doxygen/group__COMPILATIONDB.html>`_. |
|---|
| 43 | |
|---|
| 44 | Format |
|---|
| 45 | ====== |
|---|
| 46 | |
|---|
| 47 | A compilation database is a JSON file, which consist of an array of |
|---|
| 48 | "command objects", where each command object specifies one way a |
|---|
| 49 | translation unit is compiled in the project. |
|---|
| 50 | |
|---|
| 51 | Each command object contains the translation unit's main file, the |
|---|
| 52 | working directory of the compile run and the actual compile command. |
|---|
| 53 | |
|---|
| 54 | Example: |
|---|
| 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 | |
|---|
| 65 | The 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 | - **arguments:** The compile command executed as list of strings. |
|---|
| 82 | Either **arguments** or **command** is required. |
|---|
| 83 | - **output:** The name of the output created by this compilation step. |
|---|
| 84 | This field is optional. It can be used to distinguish different processing |
|---|
| 85 | modes of the same input file. |
|---|
| 86 | |
|---|
| 87 | Build System Integration |
|---|
| 88 | ======================== |
|---|
| 89 | |
|---|
| 90 | The convention is to name the file compile\_commands.json and put it at |
|---|
| 91 | the top of the build directory. Clang tools are pointed to the top of |
|---|
| 92 | the build directory to detect the file and use the compilation database |
|---|
| 93 | to parse C++ code in the source tree. |
|---|
| 94 | |
|---|
| 95 | Alternatives |
|---|
| 96 | ============ |
|---|
| 97 | For simple projects, Clang tools also recognize a compile_flags.txt file. |
|---|
| 98 | This should contain one flag per line. The same flags will be used to compile |
|---|
| 99 | any file. |
|---|
| 100 | |
|---|