| 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> |
| 16 | <p>This document describes a format to specify how to replay |
| 17 | single compilations independently of the build system.</p> |
| 18 | |
| 19 | <h2>Background</h2> |
| 20 | <p>Tools based on the C++ AST need full information how to |
| 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> |
| 40 | <p>Currently <a href="http://cmake.org">CMake</a> support generation of compilation |
| 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 |
| 44 | the <a href="LibTooling.html">LibTooling documentation</a>. Support for libclang |
| 45 | is in the works.</p> |
| 46 | |
| 47 | <h2>Format</h2> |
| 48 | <p>A compilation database is a JSON file, which consist of an array of |
| 49 | objects, where each object specifies one way a translation unit |
| 50 | is compiled in the project.</p> |
| 51 | <p>Each object contains the translation unit's main file, the working |
| 52 | directory of the compile run and the actual compile command.</p> |
| 53 | <p>Example: |
| 54 | <pre> |
| 55 | [ |
| 56 | { "directory": "/home/user/llvm/build", |
| 57 | "command": "/usr/bin/clang++ -Irelative -DSOMEDEF='\"With spaces and quotes.\"' -c -o file.o file.cc", |
| 58 | "file": "file.cc" }, |
| 59 | ... |
| 60 | ] |
| 61 | </pre> |
| 62 | The contracts for each field in the command object are: |
| 63 | <ul> |
| 64 | <li><b>directory:</b> The working directory of the compilation. All paths specified |
| 65 | in the <b>command</b> or <b>file</b> fields must be either absolute or relative to |
| 66 | this directory.</li> |
| 67 | <li><b>file:</b> The main translation unit source processed by this compilation step. |
| 68 | This is used by tools as the key into the compilation database. There can be multiple |
| 69 | compile objects for the same file, for example if the same translation unit is |
| 70 | compiled with different configurations.</li> |
| 71 | <li><b>command:</b> The compile command executed. After JSON unescaping, this must |
| 72 | be a valid command to rerun the exact compilation step for the translation unit in |
| 73 | the environment the build system uses.</li> |
| 74 | </ul> |
| 75 | </p> |
| 76 | |
| 77 | <h2>Build System Integration</h2> |
| 78 | <p>The convention is to name the file compile_commands.json and put it at the top |
| 79 | of the build directory. Clang tools are pointed to the top of the build directory |
| 80 | to detect the file and use the compilation database to parse C++ code in the source |
| 81 | tree.</p> |
| 82 | |
| 83 | </div> |
| 84 | </body> |
| 85 | </html> |
| 86 | |