include-what-you-use

Use include-what-you-use to analyze and remove unused C++ headers while adding missing direct includes. This reduces compilation cascades and speeds up build times in large codebases by ensuring correct dependencies.

Use forward declarations instead of full header includes when you only need to reference a type without accessing its members. This minimizes downstream compile costs and reduces header bloat, while full includes are necessary when you use the type's full definition.

Integrate include-what-you-use with CMake and CI by using compile_commands.json to automate detection. Run the IWYU tool against your build, pipe the report to fix_include to apply changes, then rebuild and validate tests in your pipeline.

Mapping files teach IWYU about indirect or platform-specific header relationships, resolving complex dependencies like third-party or STL mappings. They ensure accurate analysis when standard include paths cannot fully trace header relationships.

You can run header optimization on both single files and whole C++ projects. For whole project analysis, use compile_commands.json to process all translation units and identify unused includes across the entire codebase simultaneously.

Unnecessary header includes cause slow C++ build times by creating wide compilation cascades where changes to one header trigger recompilation of many dependent files. Removing unused includes and using forward declarations minimizes this cascading effect.