include-what-you-use

Include What You Use (IWYU)

Purpose

Guide agents through using IWYU to reduce unnecessary #include directives, interpret IWYU reports and mapping files, decide between forward declarations and full includes, and integrate IWYU into CMake builds to reduce compilation cascades in large codebases.

Triggers

• "How do I use include-what-you-use?"
• "How do I reduce my C++ compilation times by fixing includes?"
• "How do I interpret IWYU output?"
• "Should I use a forward declaration or include?"
• "How do I integrate IWYU with CMake?"
• "What is a compilation cascade and how do I avoid it?"

Workflow

1. Install and run IWYU

# Install
apt-get install iwyu              # Ubuntu/Debian
brew install include-what-you-use # macOS

# Run on a single file
iwyu -Xiwyu --error main.cpp 2>&1

# Run via compile_commands.json
iwyu_tool.py -p build/ src/main.cpp 2>&1 | tee iwyu.log

# Run on entire project
iwyu_tool.py -p build/ 2>&1 | tee iwyu.log

2. CMake integration

# CMakeLists.txt — use IWYU as include checker during build
find_program(IWYU_PROGRAM NAMES include-what-you-use iwyu)
if(IWYU_PROGRAM)
    set(CMAKE_CXX_INCLUDE_WHAT_YOU_USE
        ${IWYU_PROGRAM}
        -Xiwyu --mapping_file=${CMAKE_SOURCE_DIR}/iwyu.imp
        -Xiwyu --no_comments
    )
endif()

# Build with IWYU analysis
cmake -S . -B build -DCMAKE_CXX_COMPILER=clang++
cmake --build build 2>&1 | tee iwyu.log

3. Interpreting IWYU output

main.cpp should add these lines:
#include <string>   // for std::string
#include "mylib/widget.h"  // for Widget

main.cpp should remove these lines:
- #include <vector>  // lines 5-5
- #include "internal/detail.h"  // lines 8-8

The full include-list for main.cpp:
#include <iostream>  // for std::cout
#include <string>    // for std::string
#include "mylib/widget.h"  // for Widget
---

Reading the output:

• should add: headers providing symbols used but not yet included
• should remove: headers included but whose symbols aren't used directly
• The full include-list: what the final header list should look like