mirror of
https://github.com/intel/llvm.git
synced 2026-01-14 11:57:39 +08:00
5233ad17e7
This doc lists ways of getting compilation databases out of some popular build systems for use with clangd and other tooling. We built such a way for Bazel and just released it after a bunch of requests on GitHub. Thought I should propose that we add a link to help people find it and use clang tooling. (This is my first revision submitted via LLVM Phabricator, so if I've messed something up, I'd really appreciate your help and patience. Asking for a review from Sam McCall, because I've had a great time working with him elsewhere on GitHub before and because I saw him in the Git history for this file.) Reviewed By: sammccall Differential Revision: https://reviews.llvm.org/D114213
118 lines
4.5 KiB
ReStructuredText
118 lines
4.5 KiB
ReStructuredText
==============================================
|
|
JSON Compilation Database Format Specification
|
|
==============================================
|
|
|
|
This document describes a format for specifying how to replay single
|
|
compilations independently of the build system.
|
|
|
|
Background
|
|
==========
|
|
|
|
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:
|
|
|
|
- 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.
|
|
- 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.
|
|
- 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.
|
|
|
|
Supported Systems
|
|
=================
|
|
|
|
Currently `CMake <https://cmake.org>`_ (since 2.8.5) supports generation
|
|
of compilation databases for Unix Makefile builds (Ninja builds in the
|
|
works) with the option ``CMAKE_EXPORT_COMPILE_COMMANDS``.
|
|
|
|
For projects on Linux, there is an alternative to intercept compiler
|
|
calls with a tool called `Bear <https://github.com/rizsotto/Bear>`_.
|
|
|
|
`Bazel <https://bazel.build>`_ can export a compilation database via
|
|
`this extractor extension
|
|
<https://github.com/hedronvision/bazel-compile-commands-extractor>`_.
|
|
Bazel is otherwise resistant to Bear and other compiler-intercept
|
|
techniques.
|
|
|
|
Clang's tooling interface supports reading compilation databases; see
|
|
the :doc:`LibTooling documentation <LibTooling>`. libclang and its
|
|
python bindings also support this (since clang 3.2); see
|
|
`CXCompilationDatabase.h </doxygen/group__COMPILATIONDB.html>`_.
|
|
|
|
Format
|
|
======
|
|
|
|
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.
|
|
|
|
Each command object contains the translation unit's main file, the
|
|
working directory of the compile run and the actual compile command.
|
|
|
|
Example:
|
|
|
|
::
|
|
|
|
[
|
|
{ "directory": "/home/user/llvm/build",
|
|
"command": "/usr/bin/clang++ -Irelative -DSOMEDEF=\"With spaces, quotes and \\-es.\" -c -o file.o file.cc",
|
|
"file": "file.cc" },
|
|
...
|
|
]
|
|
|
|
The contracts for each field in the command object are:
|
|
|
|
- **directory:** The working directory of the compilation. All paths
|
|
specified in the **command** or **file** fields must be either
|
|
absolute or relative to this directory.
|
|
- **file:** 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.
|
|
- **command:** 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 '``"``'
|
|
and '``\``' being the only special characters. Shell expansion is not
|
|
supported.
|
|
- **arguments:** The compile command executed as list of strings.
|
|
Either **arguments** or **command** is required.
|
|
- **output:** The name of the output created by this compilation step.
|
|
This field is optional. It can be used to distinguish different processing
|
|
modes of the same input file.
|
|
|
|
Build System Integration
|
|
========================
|
|
|
|
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.
|
|
|
|
Alternatives
|
|
============
|
|
For simple projects, Clang tools also recognize a ``compile_flags.txt`` file.
|
|
This should contain one argument per line. The same flags will be used to
|
|
compile any file.
|
|
|
|
Example:
|
|
|
|
::
|
|
|
|
-xc++
|
|
-I
|
|
libwidget/include/
|
|
|
|
Here ``-I libwidget/include`` is two arguments, and so becomes two lines.
|
|
Paths are relative to the directory containing ``compile_flags.txt``.
|
|
|