Appendix 1

Compilation Database

The test examples considered in the book do not require special compilation flags and typically can be compiled without any flags. However, this is not the scenario if you want to employ the material on a real project, such as running a lint check on your code base. In that situation, you will need to furnish special compilation flags for each file to be processed. Clang offers various methods for supplying these flags. We will explore in detail the JSON Compilation Database, which is one of the primary tools for delivering compilation flags to Clang tools such as Clang-Tidy and Clangd.

9.1 Compilation database definition

A compilation database (CDB) is a JSON file that specifies how each source file in a code base should be compiled. This JSON file is typically named compile_commands.json and resides in the root directory of a project. It provides a machine-readable record of all compiler invocations in the build process and is often used by various tools for more accurate analysis, refactoring, and more. Each entry in this JSON file typically contains the following fields:

• directory: The working directory of the compilation.

• command: The actual compile command, including compiler options.

• arguments: Another field that can be used to specify compilation arguments. It contains the list of arguments.

• file: The path to the source file being compiled.

• output: The path to the output created by this compilation step.

As we can see from the fields description, there are two ways to specify compilation flags: using the command or arguments field. Let’s look at a specific...

9.2 CDB creation

The shellcompile˙commands.json file can be generated in various ways. For example, the build system CMake has built-in support for generating a compilation database. Some tools can also generate this file from Makefiles or other build systems. There are even tools such as Bear and intercept-build that can generate a CDB by intercepting the actual compile commands as they are run.

So while the term is commonly associated with Clang and LLVM-based tools, the concept itself is more general and could theoretically be used by any tool that needs to understand the compilation settings for a set of source files. We will start with CDB generation using CMake, one of the most popular build systems.

Generating a CDB with CMake

Generating a CDB with CMake involves a few steps:

1. First, open a terminal or command prompt and navigate to your project’s root directory.

2. Then, run CMake with the -DCMAKE_EXPORT_COMPILE_COMMANDS=ON option, which instructs CMake to create...

9.3 Clang tools and a CDB

The concept of a CDB is not specific to Clang but Clang-based tools make extensive use of it. For instance, the Clang compiler itself can use a compilation database to understand how to compile files in a project. Tools such as Clang-Tidy and Clangd (for language support in IDEs) can also use it to ensure they understand code as it was built, making their analyses and transformations more accurate.

Clang-Tidy Configuration for Large Projects

To use clang-tidy with a CDB, you typically don’t need any additional configuration. Clang-tidy can automatically detect and utilize the compile_commands.json file in your project’s root directory.

On the other hand, Clang Tools provide a special option, -p, defined as follows:

-p <build-path> is used to read a compile command database

You can use this option to run Clang-Tidy on a file from the Clang source code. For example, if you run it from the llvm-project...

9.4 Further reading

• Clang Documentation - JSON Compilation Database Format Specification: https://clang.llvm.org/docs/JSONCompilationDatabase.html

• Clangd documentation - Compile commands: https://clangd.llvm.org/design/compile-commands