Using Clang-Tidy

Static analysis is the process of analyzing code for potential errors without executing it. Static analysis tools simply read our code files to see if they can find any potential issues.

A linter is a type of static analysis tool that checks for stylistic errors, common programming mistakes, and violations of best practices.

Clang-Tidy is a highly configurable linter for C++, C, and Objective-C. It can detect everything from simple formatting issues to complex bugs like potential memory leaks or incorrect API usage.

Clang-Tidy is part of the LLVM Project. It's likely you already have it installed in your environment, particularly if you followed along with the earlier section on using ClangFormat .

You can verify Clang-Tidy is available in your environment in the usual way:

1clang-tidy --version

1LLVM (http://llvm.org/):
2  LLVM version 20.1.8
3  Optimized build.

From our build scripts, we can find clang-tidy in the usual way, via find_program():

1cmake --preset default

1...
2-- clang-tidy found: D:/msys64/clang64/bin/clang-tidy.exe
3...

We can now use this program using the same techniques we covered previously, by invoking it within a custom command or encapsulating it within a custom target .

However, CMake is aware of ClangTidy by default, and we can use it within our build simply by setting the CMAKE_CXX_CLANG_TIDY variable. This tells CMake to run clang-tidy alongside the compiler for every source file:

1cmake_minimum_required(VERSION 3.23)
2find_program(CLANG_TIDY_EXE "clang-tidy")
3
4if(CLANG_TIDY_EXE)
5    message(STATUS "clang-tidy found: ${CLANG_TIDY_EXE}")
6    set(CMAKE_CXX_CLANG_TIDY ${CLANG_TIDY_EXE})
7else()
8    message(WARNING "clang-tidy not found!")
9endif()

If we configure and build now, then we may already see some clang-tidy warnings, depending on the state of our code base:

1cmake --preset default

1cmake --build --preset default

1warning: Value stored to '_' during its initialization is never read [clang-analyzer-deadcode.DeadStores]
2   10 |   for (auto _ : state) {
3      |             ^ ~

In large projects, linters will often output warnings or errors for sections of code that we're happy with, or don't want to refactor. To handle this, we can suppress the linter by adding specifically formated comments at or near the offending lines.

Adding a NOLINT comment will ask the linter to ignore that line:

1#include <benchmark/benchmark.h>
2#include <greeter/Greeter.h>
3#include <string>
4
5static void BM_Greeter_Greet(benchmark::State& state) {
6  std::string name(state.range(0), 'x');
7  Greeter g(name);
8
9  for (auto _ : state) {// NOLINT
10    std::string result = g.greet();
11    benchmark::DoNotOptimize(result);
12  }
13}
14
15BENCHMARK(BM_Greeter_Greet)->Range(8, 32768);
16
17BENCHMARK_MAIN();

We can also ask the linter to ignore the next line using NOLINTNEXTLINE:

1// NOLINTNEXTLINE 
2for (auto _ : state) {
3  std::string result = g.greet();
4  benchmark::DoNotOptimize(result);
5}

We can ignore an entire block by wrapping it between NOLINTBEGIN and NOLINTEND comments:

1// NOLINTBEGIN 
2for (auto _ : state) {
3  std::string result = g.greet();
4  benchmark::DoNotOptimize(result);
5}
6// NOLINTEND

All of these NOLINT variations allow us to specify the rule we want to suppress within brackets. The name of the rull that was violated will be included in the warning or the error that was emitted:

1// NOLINTNEXTLINE(clang-analyzer-deadcode.DeadStores)
2for (auto _ : state) {
3  std::string result = g.greet();
4  benchmark::DoNotOptimize(result);
5}

This is generally recommended, as it clarifies to readers what the comment is actually suppressing.

Additionally, if a new violation is added to the area, that new violation will emit a warning to attract our attention, rather than also get suppressed.

We can suppress multiple rules by comma-seperating them:

1// NOLINTNEXTLINE(rule-1,rule-2)

Clang-Tidy is highly configurable. The primary way of doing this is through a .clang-tidy file - note the initial . in the file name. This file is stored in your project root and shared among the team.

The most notable thing we configure is which rules we want Clang-Tidy to check for. Clang-Tidy can scan for around 300 issue at the time of writing. You can find them all on the official documentation.

Let's enable a check that suggests using nullptr instead of the old NULL macro:

1Checks: '-*,modernize-use-nullptr'

The -* syntax tells Clang-Tidy to disable all checks. The following modernize-use-nullptr then tells it to renable checking for just that rule.

We can add further rules using comma-separation. The following configuration also discourages the use of std::endl:

1Checks: '-*,modernize-use-nullptr,performance-avoid-endl'

Let's introduce some code that violates the modernize-use-nullptr. Historically, the NULL keyword was often used to represent null pointers. NULL is a macro typically defined as the integer 0.

Setting a pointer to 0 technically works as a way to represent a null pointer, but it causes issues in overload resolution:

1void f(int); 
2void f(char*);
3
4f(NULL); // calls f(int), not f(char*)

C++11 introduced the explicit nullptr keyword, which is now the best practice:

1void f(int); 
2void f(char*);
3
4f(nullptr); // calls f(char*)

We'll violate this rule in Greeter.cpp so we can confirm that our configuration is working:

1#include <greeter/Greeter.h>
2
3Greeter::Greeter(std::string name)
4  : name_(std::move(name)) {}
5
6std::string Greeter::greet() const {
7  int* SomePtr{NULL};
8  return "Hello, " + name_ + "!";
9}

Let's rebuild our project:

1cmake --build --preset default

During compilation, Clang-Tidy should run and emit a warning directly in our build log, pointing out the violation and often suggesting a fix:

1.../greeter/src/Greeter.cpp:20:13: warning: use nullptr [modernize-use-nullptr]
2  if (ptr == NULL) {
3             ^
4             nullptr

Emitting Errors

Our previous rule emits a warning when violations are detected. If we care a lot about ensuring a specific rule is followed, we can upgrade that to an error instead. We can do this using the WarningAsErrors option in our .clang-tidy:

1Checks: '-*,modernize-use-nullptr'
2
3# Treat specific warnings as errors:
4WarningsAsErrors: 'modernize-use-nullptr'
5
6# Alternatively, treat all warnings as errors:
7WarningsAsErrors: '*'

If we rebuild the project, our use of NULL over nullptr should now generate an error.

Our build system may skip rebuilding our targets if the only thing that has changed is a .clang-tidy file. We can delete our outputs and force them to be recompiled by passing the --clean-first argument:

1cmake --build --preset default --clean-first

1D:/Projects/cmake/greeter/src/Greeter.cpp:7:16: error: use nullptr [modernize-use-nullptr,-warnings-as-errors]
2    7 |   int* SomePtr{NULL};
3      |                ^~~~
4      |                nullptr
5
61 warning treated as error

Configuring Clang-Tidy using Variables

We can configure Clang-Tidy by extending our use of the CMAKE_CXX_CLANG_TIDY variable. This approach would override any rules we had set in our .clang-tidy file, if we had one.

For example, to override the warnings-as-errors configuration we set in our .clang-tidy, we could set that argument to -*, removing the errors for all rules:

1cmake_minimum_required(VERSION 3.23)
2find_program(CLANG_TIDY_EXE "clang-tidy")
3
4if(CLANG_TIDY_EXE)
5  message(STATUS "clang-tidy found: ${CLANG_TIDY_EXE}")
6  set(CMAKE_CXX_CLANG_TIDY ${CLANG_TIDY_EXE}
7    --warnings-as-errors=-*
8  )
9else()
10  message(WARNING "clang-tidy not found!")
11endif()

As with any variable, this could also be set from a preset:

1{
2  "version": 3,
3  "configurePresets": [
4    // ... other presets
5    {
6      "name": "no-lint-errors",
7      "inherits": "default",
8      "cacheVariables": {
9        "CMAKE_CXX_CLANG_TIDY":
10          "clang-tidy;--warnings-as-errors=-*"
11      }
12    }
13  ]
14  // ... 
15}

1Checks: '-*,modernize-use-nullptr,performance-*'
2WarningsAsErrors: 'performance-unnecessary-value-param'

1#include <greeter/Greeter.h>
2
3Greeter::Greeter(std::string name)
4  : name_(std::move(name)) {}
5
6namespace {
7bool should_ignore(std::string name) {
8  return name == "Bob";
9}
10}
11
12std::string Greeter::greet() const {
13  if (should_ignore(name_)) return "";
14  return "Hello, " + name_ + "!";
15}

1Greeter.cpp:7:32: warning: the parameter 'name' is copied for each invocation but only used as a const reference; consider making it a const reference [performance-unnecessary-value-param]
2    7 | bool should_ignore(std::string name) {
3      |                                ^
4      |                    const      &

1cmake --build --preset release

1./build/benchmarks/GreeterBenchmarks

1------------------------------------------------------
2Benchmark                   Time      CPU   Iterations
3------------------------------------------------------
4...
5BM_Greeter_Greet/32768   2440 ns  2382 ns       295153

1#include <greeter/Greeter.h>
2
3Greeter::Greeter(std::string name)
4  : name_(std::move(name)) {}
5
6namespace {
7bool should_ignore(const std::string& name) {
8  return name == "Bob";
9}
10}
11
12std::string Greeter::greet() const {
13  if (should_ignore(name_)) return "";
14  return "Hello, " + name_ + "!";
15}

1cmake --build --preset release

1./build/benchmarks/GreeterBenchmarks

1-------------------------------------------------------
2Benchmark                   Time       CPU   Iterations
3-------------------------------------------------------
4...
5BM_Greeter_Greet/32768   1722 ns   1713 ns       401408