Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 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 <http://cmake.org>`_ (since 2.8.5) supports generation |
| 33 | of compilation databases for Unix Makefile builds (Ninja builds in the |
Dmitri Gribenko | 97555a1 | 2012-12-15 21:10:51 +0000 | [diff] [blame] | 34 | works) with the option ``CMAKE_EXPORT_COMPILE_COMMANDS``. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 35 | |
Dmitri Gribenko | d96d949 | 2013-01-30 17:58:14 +0000 | [diff] [blame] | 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 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 39 | Clang's tooling interface supports reading compilation databases; see |
Sean Silva | 159cc9e | 2013-01-02 13:07:47 +0000 | [diff] [blame] | 40 | the :doc:`LibTooling documentation <LibTooling>`. libclang and its |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 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", |
Dmitri Gribenko | 7414959 | 2013-01-30 17:58:39 +0000 | [diff] [blame] | 60 | "command": "/usr/bin/clang++ -Irelative -DSOMEDEF=\"With spaces, quotes and \\-es.\" -c -o file.o file.cc", |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 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. |
Dmitri Gribenko | 97555a1 | 2012-12-15 21:10:51 +0000 | [diff] [blame] | 78 | Parameters use shell quoting and shell escaping of quotes, with '``"``' |
| 79 | and '``\``' being the only special characters. Shell expansion is not |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 80 | supported. |
| 81 | |
| 82 | Build System Integration |
| 83 | ======================== |
| 84 | |
| 85 | The convention is to name the file compile\_commands.json and put it at |
| 86 | the top of the build directory. Clang tools are pointed to the top of |
| 87 | the build directory to detect the file and use the compilation database |
| 88 | to parse C++ code in the source tree. |