| Manuel Klimek | 8c24675 | 2012-06-12 17:51:04 +0000 | [diff] [blame] | 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> |
| Manuel Klimek | 1156afd | 2012-06-13 19:40:46 +0000 | [diff] [blame] | 16 | <p>This document describes a format for specifying how to replay |
| Manuel Klimek | 8c24675 | 2012-06-12 17:51:04 +0000 | [diff] [blame] | 17 | single compilations independently of the build system.</p> |
| 18 | |
| 19 | <h2>Background</h2> |
| Manuel Klimek | 1156afd | 2012-06-13 19:40:46 +0000 | [diff] [blame] | 20 | <p>Tools based on the C++ Abstract Syntax Tree need full information how to |
| Manuel Klimek | 8c24675 | 2012-06-12 17:51:04 +0000 | [diff] [blame] | 21 | parse a translation unit. Usually this information is implicitly |
| 22 | available in the build system, but running tools as part of |
| 23 | the build system is not necessarily the best solution: |
| 24 | <ul> |
| 25 | <li>Build systems are inherently change driven, so running multiple |
| 26 | tools over the same code base without changing the code does not fit |
| 27 | into the architecture of many build systems.</li> |
| 28 | <li>Figuring out whether things have changed is often an IO bound |
| 29 | process; this makes it hard to build low latency end user tools based |
| 30 | on the build system.</li> |
| 31 | <li>Build systems are inherently sequential in the build graph, for example |
| 32 | due to generated source code. While tools that run independently of the |
| 33 | build still need the generated source code to exist, running tools multiple |
| 34 | times over unchanging source does not require serialization of the runs |
| 35 | according to the build dependency graph.</li> |
| 36 | </ul> |
| 37 | </p> |
| 38 | |
| 39 | <h2>Supported Systems</h2> |
| Manuel Klimek | 1156afd | 2012-06-13 19:40:46 +0000 | [diff] [blame] | 40 | <p>Currently <a href="http://cmake.org">CMake</a> (since 2.8.5) supports generation of compilation |
| Manuel Klimek | 8c24675 | 2012-06-12 17:51:04 +0000 | [diff] [blame] | 41 | databases for Unix Makefile builds (Ninja builds in the works) with the option |
| 42 | CMAKE_EXPORT_COMPILE_COMMANDS.</p> |
| 43 | <p>Clang's tooling interface supports reading compilation databases; see |
| Manuel Klimek | ef0ebee | 2012-07-09 05:17:45 +0000 | [diff] [blame] | 44 | the <a href="LibTooling.html">LibTooling documentation</a>. libclang and its |
| 45 | python bindings also support this (since clang 3.2); see |
| 46 | <a href="/doxygen/group__COMPILATIONDB.html">CXCompilationDatabase.h</a>.</p> |
| Manuel Klimek | 8c24675 | 2012-06-12 17:51:04 +0000 | [diff] [blame] | 47 | |
| 48 | <h2>Format</h2> |
| 49 | <p>A compilation database is a JSON file, which consist of an array of |
| Manuel Klimek | 1156afd | 2012-06-13 19:40:46 +0000 | [diff] [blame] | 50 | "command objects", where each command object specifies one way a translation unit |
| Manuel Klimek | 8c24675 | 2012-06-12 17:51:04 +0000 | [diff] [blame] | 51 | is compiled in the project.</p> |
| Manuel Klimek | 1156afd | 2012-06-13 19:40:46 +0000 | [diff] [blame] | 52 | <p>Each command object contains the translation unit's main file, the working |
| Manuel Klimek | 8c24675 | 2012-06-12 17:51:04 +0000 | [diff] [blame] | 53 | directory 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> |
| 63 | The 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 |
| 66 | in the <b>command</b> or <b>file</b> fields must be either absolute or relative to |
| 67 | this directory.</li> |
| 68 | <li><b>file:</b> The main translation unit source processed by this compilation step. |
| 69 | This is used by tools as the key into the compilation database. There can be multiple |
| Manuel Klimek | 1156afd | 2012-06-13 19:40:46 +0000 | [diff] [blame] | 70 | command objects for the same file, for example if the same source file is |
| Manuel Klimek | 8c24675 | 2012-06-12 17:51:04 +0000 | [diff] [blame] | 71 | compiled with different configurations.</li> |
| 72 | <li><b>command:</b> The compile command executed. After JSON unescaping, this must |
| 73 | be a valid command to rerun the exact compilation step for the translation unit in |
| Manuel Klimek | 3f6d513 | 2012-07-10 08:05:54 +0000 | [diff] [blame] | 74 | the environment the build system uses. Parameters use shell quoting and shell escaping |
| 75 | of quotes, with '"' and '\' being the only special characters. Shell expansion is |
| 76 | not supported.</li> |
| Manuel Klimek | 8c24675 | 2012-06-12 17:51:04 +0000 | [diff] [blame] | 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 |
| 82 | of the build directory. Clang tools are pointed to the top of the build directory |
| 83 | to detect the file and use the compilation database to parse C++ code in the source |
| 84 | tree.</p> |
| 85 | |
| 86 | </div> |
| 87 | </body> |
| 88 | </html> |
| 89 | |