[cfe-commits] r158365 - /cfe/trunk/docs/JSONCompilationDatabase.html

Tue Jun 12 10:51:04 PDT 2012

Author: klimek
Date: Tue Jun 12 12:51:04 2012
New Revision: 158365

URL: http://llvm.org/viewvc/llvm-project?rev=158365&view=rev
Log:
Add documentation for the JSON compilation database format.


Added:
    cfe/trunk/docs/JSONCompilationDatabase.html   (with props)

Added: cfe/trunk/docs/JSONCompilationDatabase.html
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/JSONCompilationDatabase.html?rev=158365&view=auto
==============================================================================

--- cfe/trunk/docs/JSONCompilationDatabase.html (added)
+++ cfe/trunk/docs/JSONCompilationDatabase.html Tue Jun 12 12:51:04 2012
@@ -0,0 +1,86 @@
+<!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 to specify how to replay
+single compilations independently of the build system.</p>
+
+<h2>Background</h2>
+<p>Tools based on the C++ AST 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> support 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>. Support for libclang
+is in the works.</p>
+
+<h2>Format</h2>
+<p>A compilation database is a JSON file, which consist of an array of
+objects, where each object specifies one way a translation unit
+is compiled in the project.</p>
+<p>Each 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
+compile objects for the same file, for example if the same translation unit 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.</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>
+

Propchange: cfe/trunk/docs/JSONCompilationDatabase.html
------------------------------------------------------------------------------
    svn:eol-style = LF

Propchange: cfe/trunk/docs/JSONCompilationDatabase.html
------------------------------------------------------------------------------
    svn:mime-type = text/html



