Static Analysis in C: How to Use Clangd, Clang-Tidy & Cppcheck to Improve Your Codebase

Originally published on my personal website.

If you've ever worked in a C codebase, you've probably been frustrated with the lack of tooling that is available to you, especially compared to more modern languages like TypeScript. The truth is, C does have capable tooling support, but they aren't as well-known as other tools are, and most don't come automatically out of the box. This article aims to show you how to set up three C tools to improve code quality and your editor experience: clangd, clang-tidy, and cppcheck.

Why use these tools?

Before explaining why to use these tools, it's important to explain what they are. clang-tidy and cppcheck are static analyzers, meaning they check your code for bugs before they happen and suggest how to make your code cleaner through formatting and style suggestions. clang-tidy focuses on linting (performing style checks) and bug-finding, while cppcheck mainly focuses on bug-finding.

clangd is a language server tool that acts as an Intellisense provider, allowing for autocomplete, hover information, and error information. One of the most helpful features of clangd is its ability to highlight warnings found by clang-tidy, so you can see them in your IDE while developing.

Installation

This article assumes you have a C project and are using CMake to build it, and you are using VSCode as your IDE.

1. Install clang and cppcheck using your package manager (apt, MSYS2, etc.).
2. Install clangd by LLVM from the extension store.
3. Disable any other language providers for C. If you have the C/C++ extension from Microsoft, clangd will prompt you to disable it.
4. Add these flags to your settings (Ctrl + ,) for clangd to enable clang-tidy support, indexing, and detailed completion styles:

"clangd.arguments": [
    "--compile-commands-dir=build",
    "--clang-tidy",
    "--background-index",
    "--completion-style=detailed"
]

Make sure you change build to the output directory for CMake

Setting up clangd to work with clang-tidy

Although in the last step we enabled clang-tidy support for clangd, we still need to do a few more things before we can get warning highlights.

The first step is to create a .clang-tidy file in your root directory:

Checks: >
  *
HeaderFilterRegex: '^(src|include)/.*'
FormatStyle: file

If your source files live in a place other than src and include, change the name under HeaderFilterRegex.

This file is essentially a configuration for clang-tidy, and clangd will use it to provide warning highlights for you. Before it does that though, add this line to your CMakeLists.txt:

set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

This is necessary for clangd to see how your project is compiled, telling it what files to check and where your include directories are.

To make sure that these compile commands are created, run your CMake build command. You should see a compile_commands.json file in your CMake output directory.

As you start looking through your C files, one thing you may notice is there are a lot of warnings you don't care about, conflict with one another, or don't go with your coding style. The good thing is, we can disable certain warnings in our .clang-tidy file. Look for the warning name (it should be in parethesis or brackets), add a - to the front, and add it to the Checks list. Some suggested warnings to supress are shown below:

Checks: >
  *,
  -altera-*,
  -llvmlibc-restrict-system-libc-headers,
  -misc-no-recursion

Of course, the * at the beginning enables ALL warnings, so you may want to only enable certain warnings:

Checks: >
  -*,
  modernize-*,
  performance-*,
  readability-*

clang-tidy will read in checks sequentially, so -* will disable all checks then the next three lines will enable all checks within the modernize, performance, and readability categories

You can find a full list of checks on the clang-tidy website.

Fully setting up clang-tidy

While clangd does handle most errors, it doesn't show every warning, so we'll need to set up clang-tidy to run in our terminal to get every warning project-wide.

The good thing is that we already set up our .clang-tidy file, meaning whatever rules we put in there will be shared between clangd and clang-tidy.

First, add this to your CMakeLists.txt after your add_executable call:

find_program(CLANG_TIDY_EXE NAMES clang-tidy)

if(CLANG_TIDY_EXE)
    message(STATUS "clang-tidy found: ${CLANG_TIDY_EXE}")
    set(CLANG_TIDY_COMMAND
        ${CLANG_TIDY_EXE}
        -quiet
        --config-file=${CMAKE_SOURCE_DIR}/.clang-tidy
        -p ${CMAKE_BINARY_DIR}
    )
    add_custom_target(clang-tidy
        # Replace SOURCES with the variable containing all your source files
        # It should be the same SOURCES passed into add_executable
        COMMAND ${CLANG_TIDY_COMMAND} ${SOURCES}
        COMMENT "Running clang-tidy..."
        USES_TERMINAL
        VERBATIM
    )

    # Replace EXEC_NAME with the name of your executable
    # This makes it so that when you run your code, 
    # it executes clang-tidy on every file that is being recompiled
    # You can remove this line if you'd rather have direct control
    # over when warnings show up
    set_target_properties(${EXEC_NAME} PROPERTIES C_CLANG_TIDY "${CLANG_TIDY_COMMAND}")
else()
    message(STATUS "clang-tidy not found")
endif()

Now you can run cmake --build build/ --target clang-tidy in your terminal to analyze every file. Make sure to change build to whatever your CMake output folder is.

USES_TERMINAL makes it so that when we run the clang-tidy target, it writes its output to the terminal live, instead of CMake printing it all when it's finished

Setting up cppcheck

To set up cppcheck, we again have to use add_custom_target that runs the command:

find_program(CPPCHECK_EXE NAMES cppcheck)

if(CPPCHECK_EXE)
    message(STATUS "cppcheck found: ${CPPCHECK_EXE}")
    add_custom_target(cppcheck
        COMMAND ${CPPCHECK_EXE}
            --project=${CMAKE_BINARY_DIR}/compile_commands.json
            # Change these to match your project directory
            --file-filter=${CMAKE_SOURCE_DIR}/src/*
            --file-filter=${CMAKE_SOURCE_DIR}/include/*
            # These are all 6 categories. You can remove them as needed
            --enable=error,warning,style,performance,portability,information
            --suppress=missingIncludeSystem
            --inline-suppr
            --error-exitcode=1
            --quiet
            # enables multithreading (4 threads)
            -j4
        COMMENT "Running cppcheck..."
        USES_TERMINAL
        VERBATIM
    )
else()
    message(STATUS "cppcheck not found")
endif()

Additionally, since cppcheck uses compile_commands.json, make sure you set CMAKE_EXPORT_COMPILE_COMMANDS to ON earlier.

After that, you can run cppcheck on every file by running cmake --build build/ --target cppcheck in your terminal. As always, change build/ to whatever your CMake output folder is.

Next Steps

If you want to do some more tinkering with these tools:

1. Try setting up run-clang-tidy (comes builtin to LLVM) to support multithreading and drastically reduce the time it takes to check for warnings.
2. Set up a CI pipeline to auto run clang-tidy and cppcheck on every PR.

Final Thoughts

Setting up these three tools will help tremendously in making both your editor experience and C codebase better. Always be sure to run both cppcheck and clang-tidy regularly to make sure you catch style mistakes and bugs often.

Happy Coding!