How to use clang-tidy in VS Code with catkin build tools

Want to get intelligent suggenstions to refactor your C++ code, while using VS Code? This blog explains how to integrate this IDE feature in the powerful editor VS Code and the catkin build system.

MS Visual Studio Code with clang-tidy integration


Writing clean C++ code can be hard, especially for beginners. Clang-tidy is a utility from the Clang/LLVM project that supports developers on this issue by providing automatic checks and refactoring of your source code.

Unfortunately, clang-tidy is not supported in the Microsoft VS Code C++ language extension. Therefore, it is not straightforward to enable this feature in VS Code, especially in combination with the catkin build system.

For this reason, I want to explain some “tricks”, that make the Clang-Tidy Extension work with catkin packages.

Get Started

To get started you’ll need to have VS Code, CMake, the catkin-build tools installed. Then add the Microsoft C/C++ language Extension and the Clang-Tidy Extension to VS Code. Now, you are almost done.

We only need one more tool, called compdb. This is a command line tool for manipulating JSON Compilation Databases, which are generated automatically by CMake. Compdb will be used to add all header files to the compilation database, such that clang-tidy also checks header files and not only the .cpp files.

Settings for Clang-Tidy Extension

Next, in VS Code the settings.json file must be adapted. In order to specify the clang LLVM source code format for the formatter the following settings must be made:

    "C_Cpp.clang_format_fallbackStyle": "LLVM",
    "C_Cpp.clang_format_style": "LLVM",
    "editor.defaultFormatter": "ms-vscode.cpptools",
    "editor.formatOnSave": true,

Additionally, the Clang-Tidy Extension must be configured. For that, at least two variables are passed as arguments to the clang-tidy command:

  • clang-tidy.checks: A list of checkers (leading - means disable checker). If empty, the default set of checkers will run.
  • clang-tidy.buildPath: Path to the file compile_commands.json (note: the path to the folder containing the file, not the path including the file, see here)

The following code snippet summarizes the settings to be made:

    "C_Cpp.clang_format_fallbackStyle": "LLVM",
    "C_Cpp.clang_format_style": "LLVM",
    "editor.defaultFormatter": "ms-vscode.cpptools",
    "editor.formatOnSave": true,
    "clang-tidy.checks":  [
    "clang-tidy.buildPath": "/home/max/ma/workspaces/simws/build/solver_ipft/clang-tidy",

Configure a build task in VS Code

So far, we have made the basic configuration to use the Clang-Tidy extension. However, I noticed, that clang-tidy does not perform any checks on the header files in my catkin package. The reason for this is, that the compile_commands.json only contains entries for the .cpp files and as clang-tidy performs checks only on files in the database it misses all the header files.

A very helpful command line tool to overcome this issue is compdb. It manipulates compilation databases and provides a command to add all header files to the compile_commands.json. This can be done with

compdb -p build/ list > compile_commands.json

assuming a build directory build/ contains a compile_commands.json.

As this command must be executed every time the package is rebuilt with catkin build, we define a task in VS Code that does the job for us. An example task defined in tasks.json looks as follows:

    "version": "2.0.0",
    "tasks": [
        "type": "shell",
        "label": "catkin build --this [Release]",
        "command": "cd ${fileDirname} && 
          catkin build --this --cmake-args -DCMAKE_BUILD_TYPE=Release -DCMAKE_EXPORT_COMPILE_COMMANDS=ON && 
          buildpath=${workspaceRoot}/../build/ && 
          package=$(echo '${relativeFileDirname}' | awk -F/ '{print $1}') && 
          mkdir -p ${buildpath}${package}/clang-tidy/ &&
          compdb -p ${buildpath}${package} list > ${buildpath}${package}/clang-tidy/compile_commands.json",
        "problemMatcher": [],
        "group": "build"

This task assumes, that the workspace root (path to the folder opened in VS Code, see also Predefined variables in VS Code) is in the catkin_ws/src directory. It runs catkin build for the current package and determines the build path to the package being built. Finally, comdp -p is executed for the build path and a compilation database with the header files included is generated in another directory (in the settings.json, clang-tidy.buildPath must be set to this directory).

As a result, you can see that clang-tidy performs checks for all files in your catkin package (including the header files) and shows the results in the problems panel and the editor.



Info about catkin and CMake:

Info about clang-tidy:

Info about compilation databases:

Info about VS Code tasks:

Maximilian Beck
Maximilian Beck
PhD Student

My research interests include applying machine learning in robotics for intelligent systems and autonomous robots.