summaryrefslogtreecommitdiffstats
path: root/gnu/llvm/tools/clang/docs/JSONCompilationDatabase.rst
diff options
context:
space:
mode:
authorpatrick <patrick@openbsd.org>2020-08-03 15:06:44 +0000
committerpatrick <patrick@openbsd.org>2020-08-03 15:06:44 +0000
commitb64793999546ed8adebaeebd9d8345d18db8927d (patch)
tree4357c27b561d73b0e089727c6ed659f2ceff5f47 /gnu/llvm/tools/clang/docs/JSONCompilationDatabase.rst
parentAdd support for UTF-8 DISPLAY-HINTs with octet length. For now only (diff)
downloadwireguard-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.rst99
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.