clang-check

Run default checks on a source file

$ clang-check [path/to/file.cpp] --

$ clang-check [path/to/file.cpp] -ast-dump --

$ clang-check [path/to/file.cpp] -ast-dump -ast-dump-filter FunctionName

$ clang-check [path/to/file.cpp] -ast-print --

clang-check [options] <source0> [<source1>...] [-- <compiler arguments>]

Description:
Analyzes one or more source files using Clang's static analysis engine. The double dash (--) separates clang-check options from arguments passed directly to the compiler frontend for parsing the source files. When analyzing a project, it's often used with the -p option to specify the build directory containing compile_commands.json.

-p <build-path>
    Specifies the path to the directory containing the compile_commands.json file. This is crucial for project-wide analysis.

--extra-arg <arg>
    Passes an additional argument to the compiler command line, appended after existing arguments.

--extra-arg-before <arg>
    Passes an additional argument to the compiler command line, prepended before existing arguments.

--checks=<string>
    A comma-separated list of checks to enable or disable. Wildcards like * can be used (e.g., '*, -google-readability-*').

--enable-checker=<string>
    Enables a specific checker by name. Can be used multiple times.

--disable-checker=<string>
    Disables a specific checker by name. Can be used multiple times.

--fix-what-you-can
    Applies suggested fixes for detected issues if available. This can modify source files.

--fix-errors
    Applies fixes specifically for detected errors. This can modify source files.

--ast-dump
    Dumps the Abstract Syntax Tree (AST) for the parsed source file, useful for debugging checkers.

--analyze-headers
    Also analyzes header files included by the source file, not just the source file itself.

-v
    Shows commands as they are executed, providing verbose output which is helpful for debugging.

clang-check is a powerful command-line utility from the LLVM Clang project, designed for static code analysis of C, C++, and Objective-C source code.
It leverages the Clang compiler's Abstract Syntax Tree (AST) to identify potential bugs, enforce coding standards, and improve code quality without actually compiling the code.
By utilizing the compilation database (compile_commands.json), clang-check can precisely understand project-specific build settings and include paths, providing accurate and context-aware diagnostics.
It's commonly used by developers for continuous integration, pre-commit hooks, and general code hygiene, helping to catch issues early in the development cycle.

While powerful, clang-check has a few considerations:
1. Compile Commands Database: It heavily relies on a correct and up-to-date compile_commands.json file for accurate analysis of complex projects. Without it, analysis might be incomplete or incorrect.
2. Resource Usage: For very large codebases, running extensive checks can be memory and CPU intensive.
3. False Positives/Negatives: Like all static analysis tools, it can occasionally produce false positives (reporting an issue where none exists) or false negatives (missing a real issue).
4. Configuration Complexity: Configuring specific checks and options for optimal results can sometimes be complex.

This file is crucial for clang-check, providing the compiler invocation commands for each source file in a project. Tools like CMake, Meson, or Bear can generate it. It ensures clang-check uses the correct flags, include paths, and definitions, mimicking the actual build process.

clang-check's capabilities are often integrated into development environments through Language Server Protocol implementations like clangd, providing real-time diagnostics. It's also a common component in continuous integration (CI) and continuous delivery (CD) pipelines to automatically enforce code quality standards before code merges.

clang-check emerged as part of the broader LLVM Clang project, initiated by Apple to provide a modern, modular, and high-performance compiler for C, C++, and Objective-C.
Its development closely tracks the evolution of the Clang frontend, leveraging its robust parsing and AST generation capabilities for static analysis.
Over time, it has grown from a basic syntax checker to a sophisticated static analyzer, integrating a vast array of diagnostic checks and code transformation capabilities (like suggested fixes). Its modular design allows for the continuous addition of new checks by the open-source community, making it a cornerstone tool for code quality in modern C++ development.

clang(1), scan-build(1), clang-format(1), clangd(1), cmake(1), bear(1)