How to use the command clang-tidy (with examples)

Clang-tidy is an LLVM-based linter for C/C++ code that helps identify style violations, bugs, and security flaws through static analysis. It provides a way to enforce coding standards and improve the overall quality of the codebase.

Use case 1: Run default checks on a source file

Code:

clang-tidy path/to/file.cpp

Motivation: Running default checks on a source file is useful when you want to quickly identify and fix common style violations and bugs in your code. It helps ensure that the code follows best practices and is more maintainable in the long run.

Explanation:

• clang-tidy: The command to run the clang-tidy linter.
• path/to/file.cpp: The path to the C/C++ source file to be analyzed.

Example output:

path/to/file.cpp:25:5: warning: Use nullptr [modernize-use-nullptr]
    if (ptr == NULL) {
    ^~~~~~~~~~~~~~~~~
    nullptr

Use case 2: Don’t run any checks other than the cppcoreguidelines checks on a file

Code:

clang-tidy path/to/file.cpp -checks=-*,cppcoreguidelines-*

Motivation: If you have a specific set of coding guidelines that you want to enforce (e.g., C++ Core Guidelines), you can use this command to run only the checks related to those guidelines. This is helpful in situations where you want to focus on specific code quality aspects and minimize noise from other checks.

Explanation:

• -checks=-*: Exclude all the default checks.
• cppcoreguidelines-*: Include only the checks related to C++ Core Guidelines.

Example output:

path/to/file.cpp:15:1: warning: Control flows into loop [cppcoreguidelines-pro-bounds-loop]
while (i < 10) {
^~~~~~~~~~~~~~~

Use case 3: List all available checks

Code:

clang-tidy -checks=* -list-checks

Motivation: When you want to explore the available checks that clang-tidy provides, you can use this command to list them. This helps you understand the analysis capabilities of clang-tidy and choose the appropriate checks for your codebase.

Explanation:

• -list-checks: Option to list all the available checks.

Example output:

Available checks:
        -*,                     Enable all checks.
        bugprone-                     Enable bugprone checks.
        cert-                     Enable cert checks.
        clang-analyzer-                     Enable clang-analyzer checks.
        cppcoreguidelines-                     Enable cppcoreguidelines checks.
        ...

Use case 4: Specify defines and includes as compilation options

Code:

clang-tidy path/to/file.cpp -- -Imy_project/include -Ddefinitions

Motivation: When analyzing a source file, you might need to provide additional compilation options such as include directories (-I) and preprocessor definitions (-D). This is useful when clang-tidy needs to correctly resolve dependencies or handle conditional compilation in the codebase.

Explanation:

• --: Indicates the beginning of compiler options.
• -Imy_project/include: Specifies an include directory for clang-tidy to search for header files.
• -Ddefinitions: Specifies a preprocessor definition to be used during the analysis.

Example output:

path/to/file.cpp:10:20: error: 'MY_DEFINITION' macro is not defined, but used [-Werror,-Wundef]
    #ifdef MY_DEFINITION
                   ^

Conclusion:

Clang-tidy is a powerful tool for ensuring code quality and detecting common programming mistakes in C/C++ codebases. Through its comprehensive set of checks and customizable options, it enables developers to improve the maintainability, performance, and security of their code. By understanding and utilizing the various use cases of the command, developers can make the most of clang-tidy and produce higher-quality code.