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 <https://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
39`Bazel <https://bazel.build>`_ can export a compilation database via
40`this extractor extension
41<https://github.com/hedronvision/bazel-compile-commands-extractor>`_.
42Bazel is otherwise resistant to Bear and other compiler-intercept
43techniques.
44
45Clang's tooling interface supports reading compilation databases; see
46the :doc:`LibTooling documentation <LibTooling>`. libclang and its
47python bindings also support this (since clang 3.2); see
48`CXCompilationDatabase.h </doxygen/group__COMPILATIONDB.html>`_.
49
50Format
51======
52
53A compilation database is a JSON file, which consist of an array of
54"command objects", where each command object specifies one way a
55translation unit is compiled in the project.
56
57Each command object contains the translation unit's main file, the
58working directory of the compile run and the actual compile command.
59
60Example:
61
62::
63
64    [
65      { "directory": "/home/user/llvm/build",
66        "command": "/usr/bin/clang++ -Irelative -DSOMEDEF=\"With spaces, quotes and \\-es.\" -c -o file.o file.cc",
67        "file": "file.cc" },
68      ...
69    ]
70
71The contracts for each field in the command object are:
72
73-  **directory:** The working directory of the compilation. All paths
74   specified in the **command** or **file** fields must be either
75   absolute or relative to this directory.
76-  **file:** The main translation unit source processed by this
77   compilation step. This is used by tools as the key into the
78   compilation database. There can be multiple command objects for the
79   same file, for example if the same source file is compiled with
80   different configurations.
81-  **command:** The compile command executed. After JSON unescaping,
82   this must be a valid command to rerun the exact compilation step for
83   the translation unit in the environment the build system uses.
84   Parameters use shell quoting and shell escaping of quotes, with '``"``'
85   and '``\``' being the only special characters. Shell expansion is not
86   supported.
87-  **arguments:** The compile command executed as list of strings.
88   Either **arguments** or **command** is required.
89-  **output:** The name of the output created by this compilation step.
90   This field is optional. It can be used to distinguish different processing
91   modes of the same input file.
92
93Build System Integration
94========================
95
96The convention is to name the file compile\_commands.json and put it at
97the top of the build directory. Clang tools are pointed to the top of
98the build directory to detect the file and use the compilation database
99to parse C++ code in the source tree.
100
101Alternatives
102============
103For simple projects, Clang tools also recognize a ``compile_flags.txt`` file.
104This should contain one argument per line. The same flags will be used to
105compile any file.
106
107Example:
108
109::
110
111    -xc++
112    -I
113    libwidget/include/
114
115Here ``-I libwidget/include`` is two arguments, and so becomes two lines.
116Paths are relative to the directory containing ``compile_flags.txt``.
117
118