Analysis of C and C++ projects based on JSON Compilation Database

• General information
• Running the analysis and getting the report
• How to generate compile_commands.json
  • CMake project
  • Ninja project
  • QBS project
  • Text Toolkit utility
  • Bear utility (only for Linux and macOS)
  • intercept-build utility (only for Linux and macOS)
  • Compilation Database Generator utility (only for Linux and macOS)
  • Xcode project (macOS only)
  • qmake project
  • SCons project
  • Bazel project

General information

One of the ways to represent the structure of a C++ project is the JSON Compilation Database format. It's a file that contains the compilation parameters necessary to create object files from the source code of a project. Usually, the file has the name compile_commands.json. A compilation database in JSON-format consists of an array of "command objects", where each command object specifies one way a translation unit is compiled in the project.

You can use the compile_commands.json file to compile a project or analyze the project by third-party utilities. The PVS-Studio C and C++ analyzer works with this format as well.

Running the analysis and getting the report

To analyze the project on Linux and macOS, you need to use pvs-studio-analyzer utility. To analyze the project on Windows, use CompilerCommandsAnalyzer.exe utility. The utility is usually located in the C:\Program Files (x86)\PVS-Studio folder. Read more information about CompilerCommandsAnalyzer and pvs-studio-analyzer here.

Important: The project must be successfully compiled and built to be analyzed.

To start the analysis and get the report, you need to run two commands.

The command example for Linux and macOS:

pvs-studio-analyzer analyze -f path_to_compile_commands.json \
                            -o pvs.log -e excludepath -j<N>

plog-converter -a GA:1,2 -t tasklist -o project.tasks pvs.log

The command example for Windows:

CompilerCommandsAnalyzer.exe analyze ^
                             -f path_to_compile_commands.json ^
                             -o pvs.log -e exclude-path -j<N>

PlogConverter.exe -a GA:1,2 -t Plog -o path_to_output_directory ^
    -n analysis_report pvs.log

If you run the analysis from the directory with the compile_commands.json file, you may disable the -f flag.

To exclude directories with third-party libraries and/or tests from the analysis, you can use the -e flag. If there are several paths, it's necessary to write the -e flag for each path:

-e third-party -e tests

The analysis can be parallelized into multiple threads with the help of -j flag.

More detailed instructions for utilities on Linux/macOS and Windows are available here and here.

How to generate compile_commands.json

If by default the project does not contain compile_commands.json, you can choose one of the ways to generate such a file.

CMake project

To generate compile_commands.json, add one flag to the CMake call:

cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=On .

It's possible to create the compile_commands.json file only if the generator supports the JSON format. For example, such generators are Makefile and Ninja:

cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=On -G Ninja .
cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=On -G "NMake Makefiles" .

To use the Ninja generator for Windows, it is often required to execute commands from the Visual Studio developer's command line (e.g., x64 Native Tools Command Prompt for VS, etc.).

Ninja project

If the project is built directly with Ninja and there is a build.ninja file in the project folder, use the following command to generate compile_commands.json:

ninja -t compdb > compile_commands.json

QBS project

To generate compile_commands.json in a project that use Qt Build System, execute the following command:

qbs generate --generator clangdb

Text Toolkit utility

Having trouble getting the compile_commands.json file using GNU make? Try Text Toolkit. You can generate a compilation database either using the Web interface (only for Linux and macOS), or by launching a Python script. To generate a database online, take the following steps:

• run the command make -nwi > output.txt;
• copy the contents of the output.txt file and paste them to the window on the Text Toolkit website;
• click the Generate button to generate the compilation database in JSON format;
• copy the obtained commands to the compile_commands.json file.

To generate the compile_commands.json using Python, you need to clone a repository from GitHub and run the following command:

ninja -nv | python path_to_texttoolkit_dir\cdg.py

Bear utility (only for Linux and macOS)

The Bear (version 2.4 or higher) utility collects compilation parameters by intercepting the compiler calls during project build. To generate compile_commands.json, run the following command

bear -- <build_command>

The build_command can be any build command such as make all or ./build.sh.

intercept-build utility (only for Linux and macOS)

The 'intercept-build' utility in scan-build is similar to the Bear utility. The command to generate compile_commands.json:

intercept-build <build_command>

Compilation Database Generator utility (only for Linux and macOS)

Compile Database Generator (compiledb) is a utility that generates compilation databases for Makefile-based build systems. The example of the compile_commands.json generation:

compiledb -n make

The -n flag means that the build won't happen (dry run).

Xcode project (macOS only)

With the xcpretty utility, you can generate compile_commands.json. To do this, run the following command:

xcodebuild [flags] | xcpretty -r json-compilation-database

qmake project

To generate compile_commands.json in the project that uses qmake, you can use IDE QtCreator version 4.8 or higher. Open the desired project and select Build > Generate Compilation Database for %project_name% in the menu bar:

The generated compile_commands.json file will be in the project's build directory.

Note: this method of obtaining compile_commands.json does not have automation. We recommend to use this method only to evaluate the analyzer.

SCons project

To generate compile_commands.json in a project that uses the SCons build system, add the following lines to the SConstruct file (this is an analog of Makefile for the Make utility) in the project directory:

env = Environment(COMPILATIONDB_USE_ABSPATH=True)
env.Tool('compilation_db')
env.CompilationDatabase()
env.Program('programm_for_build.c')

After that, to create the compile_commands.json file, run the following command in the project directory (where the SConstruct file is located):

scons -Q

For a detailed guide on how to create compile_commands.json in SCons, please consult the relevant section of the SCons documentation.

Bazel project

To generate compile_commands.json in a project that uses the Bazel build system, use the bazel-compile-commands-extractor utility (this is a utility that does not require a full build of the project, and is based on Action Graph Query (aquery)). You can find complete setup instructions here.

There are several other options for creating a compile_commands.json file for a Bazel project besides bazel-compile-commands-extractor:

• github.com/google/kythe: tools/cpp/generate_compilation_database.sh. It uses experimental_action_listener to create a compilation database;
• github.com/grailbio/bazel-compilation-database. It is faster than experimental_action_listener by Kythe, easier to set up and does not require a full build, but is less efficient. This repository has been frozen since March 17, 2024;
• github.com/stackb/bazel-stack-vscode-cc. An extension for VS Code that adds a command to create compile_commands.json for a project.

Was this page helpful?

Message submitted.

Your message has been sent. We will email you at

If you do not see the email in your inbox, please check if it is filtered to one of the following folders:

• Promotion
• Updates
• Spam

If you can’t find an answer to your question, fill in the form below and our developers will contact you

By clicking this button you agree to our Privacy Policy statement