table of contents.
motivation.
Generating a compile_commands.json file for your C++ project might not sound very useful on its own, but it is a means to an exciting end: this file gives you the ability to use the suite of Clang Tools in your C++ project. Clang Tools can help significantly improve the quality and consistency of your C++ code — and that is very exciting, indeed.
I spent the first few years of my software development career writing C++ code without the help of Clang Tools. At the time, I had a feeling I was missing something that could take my C++ skills to the next level, but I didn’t know what that something was or how to find it. I stumbled upon Clang Tools not long after while I was researching more about C++ tooling options. That research initially led me down a rabbit hole of complexity. At first, Clang Tools seemed complicated to set up and configure, and I couldn’t tell if that up-front time cost would be worth the effort. I decided to learn how to do it anyway, and I’m very glad that I did.
Now that I have been using Clang Tools for a few years, I can confidently say that using them has made me a much more efficient C++ developer. The time I spent learning to set up and configure the various Clang Tools I use has repaid itself at least 100 times over, thanks to the productivity boost these tools provide. As a developer who prioritizes safety, quality, and consistency in my C++ code, using Clang Tools gives me confidence that my code is well-written and consistently formatted without me needing to analyze every line of code on my own. Instead, I can focus mainly on the logic I’m trying to implement, which reduces much of the cognitive load. For this reason, I highly recommend that you give Clang Tools a try if you haven’t already. If you are interested, then the endeavor begins by generating a compile_commands.json file.
what is compile_
The compile_commands.json file is a JSON file containing the “compilation database” for your project. This compilation database lists the exact compiler calls used for building all of the translation units of your C++ project. Clang Tools uses this information to give you insights on your code without needing to be directly integrated into your project’s build system. Since the file is in a human-readable format, you could even write the contents by hand if you wanted to — but it’s much faster and easier to have your build system generate it automatically. By convention, compile_commands.json is placed at the top of the build directory, so you are likely to find it there once you have your build system set up to generate it.
To read more about compile_commands.json, please refer to the Clang documentation.
generating compile_
The method used for generating a compile_commands.json file will depend on the build system you are using in your C++ project. The subsections below describe how to generate this file using the build systems that I am familiar with. This is not a comprehensive guide, but it should cover most use cases. Unfortunately, not every build system is able to generate a compile_commands.json file — but more on that below.
generating compile_
CMake provides probably the easiest and most straightforward way of generating a compile_commands.json file for your project: through use of the CMAKE_EXPORT_COMPILE_COMMANDS variable. This variable was added in CMake version 3.5, so your project will need to use that CMake version or higher.
One way to set this variable is by providing it as a command line argument to cmake:
cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON /path/to/src
Alternatively, if you don’t feel like passing this as a command line argument, you can set the CMAKE_EXPORT_COMPILE_COMMANDS variable in the CMakeLists.txt file for your project. For example:
cmake_minimum_required(VERSION 3.10)
option(CMAKE_EXPORT_COMPILE_COMMANDS "Create compile_commands.json" ON)
project(MyCoolProject
DESCRIPTION "my project description"
VERSION 0.0.1
LANGUAGES CXX)
...
If you decide to go this route, please ensure to set the CMAKE_EXPORT_COMPILE_COMMANDS variable before running the project command (as shown in the example above). Otherwise, if you set the variable after calling the project command, then CMAKE_EXPORT_COMPILE_COMMANDS will not actually be turned on. The reason for this is that the project command explicitly disables the CMAKE_EXPORT_COMPILE_COMMANDS variable during invocation and then marks the variable as advanced. By setting the variable beforehand, you override this behaviour.
If you would like to dig into this further, you can run cmake path/to/src --trace to see the debug output from CMake, giving you visibility into the commands and variables that CMake processes from your CMakeLists.txt file.
cmake generator compatibility.
One important thing to note when using CMake for generating your compile_commands.json file is that the CMake Generator used in your project must support the CMAKE_EXPORT_COMPILE_COMMANDS variable in order for the file to be generated. Otherwise, if the CMake Generator you use does not support the CMAKE_EXPORT_COMPILE_COMMANDS variable, then setting it will have no effect and the compile_commands.json file will not be generated.
At the time of writing (CMake version 4.0), only Makefile Generators and Ninja Generators support the CMAKE_EXPORT_COMPILE_COMMANDS variable. Unfortunately, this means other CMake Generators, including the Visual Studio Generators, are currently unable to generate compile_commands.json natively; however, that is not the end of the story. If you are working in a Visual Studio project with a .sln file, please see the section regarding Visual Studio projects for more information about an alternative method for generating compile_commands.json.
If you don’t explicitly set a CMake Generator when building your project (e.g., cmake -G "Ninja" path/to/src), then CMake will choose a default Generator depending on your platform. You can see the default option that CMake has selected by running cmake --help and checking which CMake Generator is marked with an asterisk (*).
generating compile_
One of the easiest ways to generate the compile_commands.json file in a Makefile project is by using the helpful open-source command line tool called Bear. Bear is provided as a package in many different package manager repositories, which makes it easy to install across various flavours of Linux. To install Bear in Ubuntu, you can run the command sudo apt install bear.
To use Bear, simply prefix your make build command with bear --. For example, here is my go-to command for cleaning and building my Makefile project, while simultaneously generating a compile_commands.json file:
make -s clean && bear -- make -s && mv compile_commands.json build
Bear saves the generated compile_commands.json file in the current directory, so the last part of this command moves the generated file to the top of the build directory.
generating compile_
While Visual Studio does not natively support generating a compile_commands.json file, there is a free, open-source Visual Studio extension called SourceTrail Extension that allows you to generate a compile_commands.json file for your project from within Visual Studio. I gave it a try with one of my Visual Studio .sln projects and it worked really well.
Once SourceTrail Extension is installed, open your C++ project in Visual Studio. Then, within Visual Studio, navigate to the Sourcetrail > Create Compilation Database option in the top ribbon bar. This will open a popup window in which you can select your projects, configure different Clang options (if desired), and generate a compile_commands.json file. I haven’t done a lot of experimenting with this tool to find its limitations, but it looks like a great option so far. I think it is worth a try if you would like to get started with using Clang Tools in your Visual Studio project.
conclusion.
Once you have followed these steps and generated a compile_commands.json file for your C++ project, you can begin to use Clang Tools in your software development process to help improve the quality and consistency of your C++ code. In a future article, I would like to talk about how I use Clang Tools like clangd and clang-format in my workflow. For now, I will leave you with a link to the “features” page for clangd, which showcases some of the awesome things that clangd can do for you. All of these features (and more) are accessible to you simply by generating a compile_commands.json file for your project.
Until next time!
