/usr/share/doc/clang-3.5-doc/html/JSONCompilationDatabase.html is in clang-3.5-doc 1:3.5~svn201651-1ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>JSON Compilation Database Format Specification — Clang 3.5 documentation</title>
<link rel="stylesheet" href="_static/haiku.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '3.5',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<link rel="top" title="Clang 3.5 documentation" href="index.html" />
<link rel="next" title="Overview" href="ClangTools.html" />
<link rel="prev" title="How To Setup Clang Tooling For LLVM" href="HowToSetupToolingForLLVM.html" />
</head>
<body>
<div class="header"><h1 class="heading"><a href="index.html">
<span>Clang 3.5 documentation</span></a></h1>
<h2 class="heading"><span>JSON Compilation Database Format Specification</span></h2>
</div>
<div class="topnav">
<p>
«  <a href="HowToSetupToolingForLLVM.html">How To Setup Clang Tooling For LLVM</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="ClangTools.html">Overview</a>  »
</p>
</div>
<div class="content">
<div class="section" id="json-compilation-database-format-specification">
<h1>JSON Compilation Database Format Specification<a class="headerlink" href="#json-compilation-database-format-specification" title="Permalink to this headline">¶</a></h1>
<p>This document describes a format for specifying how to replay single
compilations independently of the build system.</p>
<div class="section" id="background">
<h2>Background<a class="headerlink" href="#background" title="Permalink to this headline">¶</a></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:</p>
<ul class="simple">
<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>
</div>
<div class="section" id="supported-systems">
<h2>Supported Systems<a class="headerlink" href="#supported-systems" title="Permalink to this headline">¶</a></h2>
<p>Currently <a class="reference external" 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 <tt class="docutils literal"><span class="pre">CMAKE_EXPORT_COMPILE_COMMANDS</span></tt>.</p>
<p>For projects on Linux, there is an alternative to intercept compiler
calls with a tool called <a class="reference external" href="https://github.com/rizsotto/Bear">Bear</a>.</p>
<p>Clang’s tooling interface supports reading compilation databases; see
the <a class="reference internal" href="LibTooling.html"><em>LibTooling documentation</em></a>. libclang and its
python bindings also support this (since clang 3.2); see
<a class="reference external" href="/doxygen/group__COMPILATIONDB.html">CXCompilationDatabase.h</a>.</p>
</div>
<div class="section" id="format">
<h2>Format<a class="headerlink" href="#format" title="Permalink to this headline">¶</a></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:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">[</span>
<span class="p">{</span> <span class="s">"directory"</span><span class="p">:</span> <span class="s">"/home/user/llvm/build"</span><span class="p">,</span>
<span class="s">"command"</span><span class="p">:</span> <span class="s">"/usr/bin/clang++ -Irelative -DSOMEDEF=</span><span class="se">\"</span><span class="s">With spaces, quotes and </span><span class="se">\\</span><span class="s">-es.</span><span class="se">\"</span><span class="s"> -c -o file.o file.cc"</span><span class="p">,</span>
<span class="s">"file"</span><span class="p">:</span> <span class="s">"file.cc"</span> <span class="p">},</span>
<span class="o">...</span>
<span class="p">]</span>
</pre></div>
</div>
<p>The contracts for each field in the command object are:</p>
<ul class="simple">
<li><strong>directory:</strong> The working directory of the compilation. All paths
specified in the <strong>command</strong> or <strong>file</strong> fields must be either
absolute or relative to this directory.</li>
<li><strong>file:</strong> 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><strong>command:</strong> 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 ‘<tt class="docutils literal"><span class="pre">"</span></tt>‘
and ‘<tt class="docutils literal"><span class="pre">\</span></tt>‘ being the only special characters. Shell expansion is not
supported.</li>
</ul>
</div>
<div class="section" id="build-system-integration">
<h2>Build System Integration<a class="headerlink" href="#build-system-integration" title="Permalink to this headline">¶</a></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>
</div>
</div>
<div class="bottomnav">
<p>
«  <a href="HowToSetupToolingForLLVM.html">How To Setup Clang Tooling For LLVM</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="ClangTools.html">Overview</a>  »
</p>
</div>
<div class="footer">
© Copyright 2007-2014, The Clang Team.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
</div>
</body>
</html>
|