diff options
Diffstat (limited to 'docs/JSONCompilationDatabase.html')
| -rw-r--r-- | docs/JSONCompilationDatabase.html | 89 |
1 files changed, 0 insertions, 89 deletions
diff --git a/docs/JSONCompilationDatabase.html b/docs/JSONCompilationDatabase.html deleted file mode 100644 index 2907194..0000000 --- a/docs/JSONCompilationDatabase.html +++ /dev/null @@ -1,89 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" - "http://www.w3.org/TR/html4/strict.dtd"> -<html> -<head> -<title>JSON Compilation Database Format Specification</title> -<link type="text/css" rel="stylesheet" href="../menu.css"> -<link type="text/css" rel="stylesheet" href="../content.css"> -</head> -<body> - -<!--#include virtual="../menu.html.incl"--> - -<div id="content"> - -<h1>JSON Compilation Database Format Specification</h1> -<p>This document describes a format for specifying how to replay -single compilations independently of the build system.</p> - -<h2>Background</h2> -<p>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: -<ul> -<li>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.</li> -<li>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.</li> -<li>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.</li> -</ul> -</p> - -<h2>Supported Systems</h2> -<p>Currently <a href="http://cmake.org">CMake</a> (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.</p> -<p>Clang's tooling interface supports reading compilation databases; see -the <a href="LibTooling.html">LibTooling documentation</a>. libclang and its -python bindings also support this (since clang 3.2); see -<a href="/doxygen/group__COMPILATIONDB.html">CXCompilationDatabase.h</a>.</p> - -<h2>Format</h2> -<p>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.</p> -<p>Each command object contains the translation unit's main file, the working -directory of the compile run and the actual compile command.</p> -<p>Example: -<pre> -[ - { "directory": "/home/user/llvm/build", - "command": "/usr/bin/clang++ -Irelative -DSOMEDEF='\"With spaces and quotes.\"' -c -o file.o file.cc", - "file": "file.cc" }, - ... -] -</pre> -The contracts for each field in the command object are: -<ul> -<li><b>directory:</b> The working directory of the compilation. All paths specified -in the <b>command</b> or <b>file</b> fields must be either absolute or relative to -this directory.</li> -<li><b>file:</b> 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.</li> -<li><b>command:</b> 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.</li> -</ul> -</p> - -<h2>Build System Integration</h2> -<p>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.</p> - -</div> -</body> -</html> - |
