1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 2 "http://www.w3.org/TR/html4/strict.dtd"> 3<html> 4<head> 5<title>JSON Compilation Database Format Specification</title> 6<link type="text/css" rel="stylesheet" href="../menu.css"> 7<link type="text/css" rel="stylesheet" href="../content.css"> 8</head> 9<body> 10 11<!--#include virtual="../menu.html.incl"--> 12 13<div id="content"> 14 15<h1>JSON Compilation Database Format Specification</h1> 16<p>This document describes a format for specifying how to replay 17single compilations independently of the build system.</p> 18 19<h2>Background</h2> 20<p>Tools based on the C++ Abstract Syntax Tree need full information how to 21parse a translation unit. Usually this information is implicitly 22available in the build system, but running tools as part of 23the build system is not necessarily the best solution: 24<ul> 25<li>Build systems are inherently change driven, so running multiple 26tools over the same code base without changing the code does not fit 27into the architecture of many build systems.</li> 28<li>Figuring out whether things have changed is often an IO bound 29process; this makes it hard to build low latency end user tools based 30on the build system.</li> 31<li>Build systems are inherently sequential in the build graph, for example 32due to generated source code. While tools that run independently of the 33build still need the generated source code to exist, running tools multiple 34times over unchanging source does not require serialization of the runs 35according to the build dependency graph.</li> 36</ul> 37</p> 38 39<h2>Supported Systems</h2> 40<p>Currently <a href="http://cmake.org">CMake</a> (since 2.8.5) supports generation of compilation 41databases for Unix Makefile builds (Ninja builds in the works) with the option 42CMAKE_EXPORT_COMPILE_COMMANDS.</p> 43<p>Clang's tooling interface supports reading compilation databases; see 44the <a href="LibTooling.html">LibTooling documentation</a>. libclang and its 45python bindings also support this (since clang 3.2); see 46<a href="/doxygen/group__COMPILATIONDB.html">CXCompilationDatabase.h</a>.</p> 47 48<h2>Format</h2> 49<p>A compilation database is a JSON file, which consist of an array of 50"command objects", where each command object specifies one way a translation unit 51is compiled in the project.</p> 52<p>Each command object contains the translation unit's main file, the working 53directory of the compile run and the actual compile command.</p> 54<p>Example: 55<pre> 56[ 57 { "directory": "/home/user/llvm/build", 58 "command": "/usr/bin/clang++ -Irelative -DSOMEDEF='\"With spaces and quotes.\"' -c -o file.o file.cc", 59 "file": "file.cc" }, 60 ... 61] 62</pre> 63The contracts for each field in the command object are: 64<ul> 65<li><b>directory:</b> The working directory of the compilation. All paths specified 66in the <b>command</b> or <b>file</b> fields must be either absolute or relative to 67this directory.</li> 68<li><b>file:</b> The main translation unit source processed by this compilation step. 69This is used by tools as the key into the compilation database. There can be multiple 70command objects for the same file, for example if the same source file is 71compiled with different configurations.</li> 72<li><b>command:</b> The compile command executed. After JSON unescaping, this must 73be a valid command to rerun the exact compilation step for the translation unit in 74the environment the build system uses. Parameters use shell quoting and shell escaping 75of quotes, with '"' and '\' being the only special characters. Shell expansion is 76not supported.</li> 77</ul> 78</p> 79 80<h2>Build System Integration</h2> 81<p>The convention is to name the file compile_commands.json and put it at the top 82of the build directory. Clang tools are pointed to the top of the build directory 83to detect the file and use the compilation database to parse C++ code in the source 84tree.</p> 85 86</div> 87</body> 88</html> 89 90