cppclean

Run in a project's directory

$ cppclean [path/to/project]

$ cppclean [path/to/project] --include-path [inc1] --include-path [inc2]

$ cppclean [main.cpp]

$ cppclean [.] --exclude [build]

cppclean [OPTIONS] [PATH ...]

--root=<dir>
    Specify the root directory of the project for relative paths.

--compile-commands-dir=<dir>
    Path to the directory containing compile_commands.json.

--include=<regex>
    Regular expression to include files for analysis. Only matching files are processed.

--exclude=<regex>
    Regular expression to exclude files from analysis. Matching files are ignored.

--verbose
    Enable verbose output, useful for debugging parsing issues.

--print_xml
    Output the results in XML format, suitable for programmatic parsing.

--exit_if_unused
    Exit with a non-zero status code (1) if any unused code is detected, useful for CI/CD pipelines.

--version
    Display the cppclean version and exit.

--help
    Show a comprehensive help message and exit.

cppclean is a static analysis tool designed for C and C++ source code. Its primary function is to identify and report unused code elements within a project. This includes unreferenced functions, methods, variables, types, and header inclusions. By parsing source files and building a dependency graph, cppclean meticulously traces symbol usage, highlighting parts of the codebase that are never called, instantiated, or accessed. The aim is to help developers remove dead code, thereby reducing compilation times, improving code readability, and decreasing the overall binary size. It operates by analyzing the project's compilation units and often benefits from a compile_commands.json file generated by tools like CMake or Bear, which provides necessary compilation flags for accurate parsing. While cppclean excels at dead code detection, it is not a linter for style or a bug finder; its scope is specifically focused on identifying and facilitating the removal of unreferenced code.

cppclean relies heavily on the accuracy of its C++ parser; for complex projects, providing a compile_commands.json file (e.g., generated by CMake or Bear) is crucial for correct analysis. Without it, the tool may fail to resolve symbols due to missing include paths or compiler flags, leading to incomplete or incorrect results. It may also produce false positives for code accessed via advanced runtime mechanisms (like dynamic loading or plugin architectures) that are beyond its static analysis capabilities. cppclean focuses exclusively on dead code detection and should not be confused with tools for code style checking or bug finding.

For accurate analysis, especially in complex C++ projects, cppclean strongly recommends using a compilation database (compile_commands.json). This file, typically generated by build systems like CMake (with -DCMAKE_EXPORT_COMPILE_COMMANDS=ON) or tools like Bear (bear -- <your_build_command>), provides cppclean with essential information about compiler flags and include paths for each source file. Using it vastly improves parsing accuracy and reduces false positives/negatives.

A common workflow involves generating compile_commands.json first, then running cppclean. For example:

cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON .
cppclean --compile-commands-dir=. --root=.

The output will list unused elements, which developers can then review and remove.

cppclean was originally developed at Google and later open-sourced, becoming part of the google/cppclean project on GitHub. Its creation was motivated by the need to manage and optimize large-scale C++ codebases by systematically identifying and removing dead code. Over the years, it has been used by various organizations and individual developers to improve code hygiene, reduce build times, and decrease binary sizes in C/C++ projects.

clang-tidy(1), cppcheck(1), bear(1)