clang/docs/JSONCompilationDatabase.rst

   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 Clang has the ability to generate compilation database fragments via
  33 ``-MJ argument <clang -MJ\<arg>>``. You can concatenate those
  34 fragments together between ``[`` and ``]`` to create a compilation database.
  35
  36 Currently `CMake <https://cmake.org>`_ (since 2.8.5) supports generation
  37 of compilation databases for Unix Makefile builds (Ninja builds in the
  38 works) with the option ``CMAKE_EXPORT_COMPILE_COMMANDS``.
  39
  40 For projects on Linux, there is an alternative to intercept compiler
  41 calls with a tool called `Bear <https://github.com/rizsotto/Bear>`_.
  42
  43 `Bazel <https://bazel.build>`_ can export a compilation database via
  44 `this extractor extension
  45 <https://github.com/hedronvision/bazel-compile-commands-extractor>`_.
  46 Bazel is otherwise resistant to Bear and other compiler-intercept
  47 techniques.
  48
  49 Clang's tooling interface supports reading compilation databases; see
  50 the :doc:`LibTooling documentation <LibTooling>`. libclang and its
  51 python bindings also support this (since clang 3.2); see
  52 `CXCompilationDatabase.h </doxygen/group__COMPILATIONDB.html>`_.
  53
  54 Format
  55 ======
  56
  57 A compilation database is a JSON file, which consist of an array of
  58 "command objects", where each command object specifies one way a
  59 translation unit is compiled in the project.
  60
  61 Each command object contains the translation unit's main file, the
  62 working directory of the compile run and the actual compile command.
  63
  64 Example:
  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
  80 The contracts for each field in the command object are:
  81
  82 -  **directory:** The working directory of the compilation. All paths
  83    specified in the **command** or **file** fields must be either
  84    absolute or relative to this directory.
  85 -  **file:** The main translation unit source processed by this
  86    compilation step. This is used by tools as the key into the
  87    compilation database. There can be multiple command objects for the
  88    same file, for example if the same source file is compiled with
  89    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 expansion
  97    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 processing
 103    modes of the same input file.
 104
 105 Build System Integration
 106 ========================
 107
 108 The convention is to name the file compile\_commands.json and put it at
 109 the top of the build directory. Clang tools are pointed to the top of
 110 the build directory to detect the file and use the compilation database
 111 to parse C++ code in the source tree.
 112
 113 Alternatives
 114 ============
 115 For simple projects, Clang tools also recognize a ``compile_flags.txt`` file.
 116 This should contain one argument per line. The same flags will be used to
 117 compile any file.
 118
 119 Example:
 120
 121 ::
 122
 123     -xc++
 124     -I
 125     libwidget/include/
 126
 127 Here ``-I libwidget/include`` is two arguments, and so becomes two lines.
 128 Paths are relative to the directory containing ``compile_flags.txt``.