1 files changed, 89 insertions, 0 deletions
diff --git a/docs/JSONCompilationDatabase.html b/docs/JSONCompilationDatabase.html
new file mode 100644
index 0000000..2907194
--- /dev/null
+++ b/docs/JSONCompilationDatabase.html
@@ -0,0 +1,89 @@
+<!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>
+