diff options
| author | 2020-08-03 15:06:44 +0000 | |
|---|---|---|
| committer | 2020-08-03 15:06:44 +0000 | |
| commit | b64793999546ed8adebaeebd9d8345d18db8927d (patch) | |
| tree | 4357c27b561d73b0e089727c6ed659f2ceff5f47 /gnu/llvm/tools/clang/docs/JSONCompilationDatabase.rst | |
| parent | Add support for UTF-8 DISPLAY-HINTs with octet length. For now only (diff) | |
| download | wireguard-openbsd-b64793999546ed8adebaeebd9d8345d18db8927d.tar.xz wireguard-openbsd-b64793999546ed8adebaeebd9d8345d18db8927d.zip | |
Remove LLVM 8.0.1 files.
Diffstat (limited to 'gnu/llvm/tools/clang/docs/JSONCompilationDatabase.rst')
| -rw-r--r-- | gnu/llvm/tools/clang/docs/JSONCompilationDatabase.rst | 99 |
1 files changed, 0 insertions, 99 deletions
diff --git a/gnu/llvm/tools/clang/docs/JSONCompilationDatabase.rst b/gnu/llvm/tools/clang/docs/JSONCompilationDatabase.rst deleted file mode 100644 index 1f3441b033d..00000000000 --- a/gnu/llvm/tools/clang/docs/JSONCompilationDatabase.rst +++ /dev/null @@ -1,99 +0,0 @@ -============================================== -JSON Compilation Database Format Specification -============================================== - -This document describes a format for specifying how to replay single -compilations independently of the build system. - -Background -========== - -Tools based on the C++ Abstract Syntax Tree need full information how to -parse a translation unit. Usually this information is implicitly -available in the build system, but running tools as part of the build -system is not necessarily the best solution: - -- Build systems are inherently change driven, so running multiple tools - over the same code base without changing the code does not fit into - the architecture of many build systems. -- Figuring out whether things have changed is often an IO bound - process; this makes it hard to build low latency end user tools based - on the build system. -- Build systems are inherently sequential in the build graph, for - example due to generated source code. While tools that run - independently of the build still need the generated source code to - exist, running tools multiple times over unchanging source does not - require serialization of the runs according to the build dependency - graph. - -Supported Systems -================= - -Currently `CMake <http://cmake.org>`_ (since 2.8.5) supports generation -of compilation databases for Unix Makefile builds (Ninja builds in the -works) with the option ``CMAKE_EXPORT_COMPILE_COMMANDS``. - -For projects on Linux, there is an alternative to intercept compiler -calls with a tool called `Bear <https://github.com/rizsotto/Bear>`_. - -Clang's tooling interface supports reading compilation databases; see -the :doc:`LibTooling documentation <LibTooling>`. libclang and its -python bindings also support this (since clang 3.2); see -`CXCompilationDatabase.h </doxygen/group__COMPILATIONDB.html>`_. - -Format -====== - -A compilation database is a JSON file, which consist of an array of -"command objects", where each command object specifies one way a -translation unit is compiled in the project. - -Each command object contains the translation unit's main file, the -working directory of the compile run and the actual compile command. - -Example: - -:: - - [ - { "directory": "/home/user/llvm/build", - "command": "/usr/bin/clang++ -Irelative -DSOMEDEF=\"With spaces, quotes and \\-es.\" -c -o file.o file.cc", - "file": "file.cc" }, - ... - ] - -The contracts for each field in the command object are: - -- **directory:** The working directory of the compilation. All paths - specified in the **command** or **file** fields must be either - absolute or relative to this directory. -- **file:** The main translation unit source processed by this - compilation step. This is used by tools as the key into the - compilation database. There can be multiple command objects for the - same file, for example if the same source file is compiled with - different configurations. -- **command:** The compile command executed. After JSON unescaping, - this must be a valid command to rerun the exact compilation step for - the translation unit in the environment the build system uses. - Parameters use shell quoting and shell escaping of quotes, with '``"``' - and '``\``' being the only special characters. Shell expansion is not - supported. -- **arguments:** The compile command executed as list of strings. - Either **arguments** or **command** is required. -- **output:** The name of the output created by this compilation step. - This field is optional. It can be used to distinguish different processing - modes of the same input file. - -Build System Integration -======================== - -The convention is to name the file compile\_commands.json and put it at -the top of the build directory. Clang tools are pointed to the top of -the build directory to detect the file and use the compilation database -to parse C++ code in the source tree. - -Alternatives -============ -For simple projects, Clang tools also recognize a compile_flags.txt file. -This should contain one flag per line. The same flags will be used to compile -any file. |
