使用Clang作为库 —— JSON Compilation Database Format Specification

本文为译文，点击 此处查看原文。

本文档描述了一种格式，用于指定如何独立于构建系统重播单个编译。

1. 背景

基于 C++ 抽象语法树的工具需要如何解析翻译单元的完整信息。通常这些信息在构建系统中是隐式可用的，但将工具作为构建系统的一部分运行并不一定是最佳解决方案：

• 构建系统本质上是由更改驱动的，因此在相同的代码基础上运行多个工具而不更改代码并不适合许多构建系统的体系结构。
• 弄清楚事情是否发生了变化通常是一个IO绑定过程；这使得基于构建系统构建低延迟的最终用户工具变得困难。
• 构建系统在构建图中天生是顺序的，例如由于生成的源代码。虽然独立于构建运行的工具仍然需要生成的源代码，但是在不变的源代码上多次运行工具并不需要根据构建依赖关系图对运行进行序列化。

2. 支持系统

目前，CMake(从2.8.5开始)支持使用CMAKE_EXPORT_COMPILE_COMMANDS选项为Unix Makefile构建(Ninja 构建正在进行)生成编译数据库(compilation databases)。
对于Linux上的项目，可以使用一个名为Bear的工具来拦截编译器调用。
Clang Tooling接口支持读取编译数据库；请参阅 LibTooling文档。libclang及其python绑定也支持这一点(clang 3.2以后)；请参阅 CXCompilationDatabase.h。

3. 格式

编译数据库是一个JSON文件，它由一个“命令对象(command objects)”数组组成，其中每个命令对象指定在项目中编译翻译单元的一种方式。每个命令对象包含翻译单元的主文件、编译运行的工作目录和实际的编译命令。
例子：

[
  { "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" },
  ...
]

命令对象中每个字段的契约是：

• directory：编译的工作目录。command或file字段中指定的所有路径必须是绝对路径或相对于此目录的路径。
• file：此编译步骤处理的主要翻译单元源文件。这被工具用作编译数据库的键(key)。对于同一个文件可以有多个命令对象，例如，如果用不同的配置编译同一个源文件。
• command：执行编译命令。在JSON取消转义之后，这必须是一个有效的命令，以便在构建系统使用的环境中重新运行翻译单元的准确编译步骤。参数使用shell引号和shell转义引号，‘"’ 和 ‘\’ 是惟一的特殊字符。不支持Shell扩展。
• arguments：编译命令作为字符串列表执行。需要arguments或command。
• output：此编译步骤创建的输出的名称。这个字段是可选的。它可以用来区分同一输入文件的不同处理模式。

4. 构建系统集成

惯例是将文件命名为compile_commands.json，并将其放在build目录的顶部。Clang 工具指向build目录的顶部，用于检测这个文件并使用编译数据库解析源文件树中的 C++ 代码。

5. 可供选择的

对于简单的项目，Clang 工具还可以识别一个compile_flags.txt文件。每一行应该包含一个标志。编译任何文件都将使用相同的标志。