diff options
author | Sean Silva <silvas@purdue.edu> | 2012-12-13 01:10:46 +0000 |
---|---|---|
committer | Sean Silva <silvas@purdue.edu> | 2012-12-13 01:10:46 +0000 |
commit | bf9b4cd59679fa07b463c585ccf0c898be0481d8 (patch) | |
tree | 4d4421dfd47617760c168d07c80b9aff507eeee9 /clang/docs/JSONCompilationDatabase.rst | |
parent | 29b513871ae23341ec6f9de805b67d48d78c38ac (diff) | |
download | bcm5719-llvm-bf9b4cd59679fa07b463c585ccf0c898be0481d8.tar.gz bcm5719-llvm-bf9b4cd59679fa07b463c585ccf0c898be0481d8.zip |
docs: More reST conversion.
Sorry for the large commit, but it is much faster to convert in batches.
llvm-svn: 170067
Diffstat (limited to 'clang/docs/JSONCompilationDatabase.rst')
-rw-r--r-- | clang/docs/JSONCompilationDatabase.rst | 85 |
1 files changed, 85 insertions, 0 deletions
diff --git a/clang/docs/JSONCompilationDatabase.rst b/clang/docs/JSONCompilationDatabase.rst new file mode 100644 index 00000000000..502557b50af --- /dev/null +++ b/clang/docs/JSONCompilationDatabase.rst @@ -0,0 +1,85 @@ +============================================== +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. + +Clang's tooling interface supports reading compilation databases; see +the `LibTooling documentation <LibTooling.html>`_. 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 and quotes.\"' -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. + +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. |