docs/JSONCompilationDatabase.html - fp2-dev/platform/external/clang - Gitiles

 <!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>
	<!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>