129 lines · plain
1==============================================2JSON Compilation Database Format Specification3==============================================4 5This document describes a format for specifying how to replay single6compilations independently of the build system.7 8Background9==========10 11Tools based on the C++ Abstract Syntax Tree need full information how to12parse a translation unit. Usually this information is implicitly13available in the build system, but running tools as part of the build14system is not necessarily the best solution:15 16- Build systems are inherently change driven, so running multiple tools17 over the same code base without changing the code does not fit into18 the architecture of many build systems.19- Figuring out whether things have changed is often an IO bound20 process; this makes it hard to build low latency end user tools based21 on the build system.22- Build systems are inherently sequential in the build graph, for23 example due to generated source code. While tools that run24 independently of the build still need the generated source code to25 exist, running tools multiple times over unchanging source does not26 require serialization of the runs according to the build dependency27 graph.28 29Supported Systems30=================31 32Clang has the ability to generate compilation database fragments via33``-MJ argument <clang -MJ\<arg>>``. You can concatenate those34fragments together between ``[`` and ``]`` to create a compilation database.35 36Currently `CMake <https://cmake.org>`_ (since 2.8.5) supports generation37of compilation databases for Unix Makefile builds (Ninja builds in the38works) with the option ``CMAKE_EXPORT_COMPILE_COMMANDS``.39 40For projects on Linux, there is an alternative to intercept compiler41calls with a tool called `Bear <https://github.com/rizsotto/Bear>`_.42 43`Bazel <https://bazel.build>`_ can export a compilation database via44`this extractor extension45<https://github.com/hedronvision/bazel-compile-commands-extractor>`_.46Bazel is otherwise resistant to Bear and other compiler-intercept47techniques.48 49Clang's tooling interface supports reading compilation databases; see50the :doc:`LibTooling documentation <LibTooling>`. libclang and its51Python bindings also support this (since clang 3.2); see52`CXCompilationDatabase.h </doxygen/group__COMPILATIONDB.html>`_.53 54Format55======56 57A compilation database is a JSON file, which consists of an array of58"command objects", where each command object specifies one way a59translation unit is compiled in the project.60 61Each command object contains the translation unit's main file, the62working directory of the compile run and the actual compile command.63 64Example:65 66::67 68 [69 { "directory": "/home/user/llvm/build",70 "arguments": ["/usr/bin/clang++", "-Irelative", "-DSOMEDEF=With spaces, quotes and \\-es.", "-c", "-o", "file.o", "file.cc"],71 "file": "file.cc" },72 73 { "directory": "/home/user/llvm/build",74 "command": "/usr/bin/clang++ -Irelative -DSOMEDEF=\"With spaces, quotes and \\-es.\" -c -o file.o file.cc",75 "file": "file2.cc" },76 77 ...78 ]79 80The contracts for each field in the command object are:81 82- **directory:** The working directory of the compilation. All paths83 specified in the **command** or **file** fields must be either84 absolute or relative to this directory.85- **file:** The main translation unit source processed by this86 compilation step. This is used by tools as the key into the87 compilation database. There can be multiple command objects for the88 same file, for example if the same source file is compiled with89 different configurations.90- **arguments:** The compile command argv as list of strings.91 This should run the compilation step for the translation unit ``file``.92 ``arguments[0]`` should be the executable name, such as ``clang++``.93 Arguments should not be escaped, but ready to pass to ``execvp()``.94- **command:** The compile command as a single shell-escaped string.95 Arguments may be shell quoted and escaped following platform conventions,96 with '``"``' and '``\``' being the only special characters. Shell expansion97 is not supported.98 99 Either **arguments** or **command** is required. **arguments** is preferred,100 as shell (un)escaping is a possible source of errors.101- **output:** The name of the output created by this compilation step.102 This field is optional. It can be used to distinguish different processing103 modes of the same input file.104 105Build System Integration106========================107 108The convention is to name the file compile\_commands.json and put it at109the top of the build directory. Clang tools are pointed to the top of110the build directory to detect the file and use the compilation database111to parse C++ code in the source tree.112 113Alternatives114============115For simple projects, Clang tools also recognize a ``compile_flags.txt`` file.116This should contain one argument per line. The same flags will be used to117compile any file.118 119Example:120 121::122 123 -xc++124 -I125 libwidget/include/126 127Here ``-I libwidget/include`` is two arguments, and so becomes two lines.128Paths are relative to the directory containing ``compile_flags.txt``.129