Include What You Use

mohitmishra786/low-level-dev-skills/skills/build-systems/include-what-you-use

by mohitmishra786bdc58472fa9fNo license253 starsListed Oct 9, 2026Updated Oct 9, 2026Repository updated 3 months ago

Include What You Use (IWYU) skill for optimizing C/C++ header includes. Use when reducing compilation cascades, interpreting IWYU reports, applying mapping files, deciding between forward declarations and full includes, or integrating IWYU with CMake. Activates on queries about IWYU, include-what-you-use, header bloat, reducing includes, forward declarations, compilation cascade, or slow C++ compilation from headers.

Instructions onlySoftware Development

AI-generated overview

Guides C/C++ developers in using Include What You Use to trim header includes and cut compilation cascades.

What it does: Explains how to install and run IWYU, including single-file runs and project-wide runs through iwyu_tool.py with compile_commands.json. It shows how to read IWYU reports, apply fixes with fix_include, integrate IWYU into CMake builds, write mapping files for third-party headers, and choose between forward declarations and full includes. It also lists IWYU limitations and a safe iterative workflow of running, fixing, rebuilding, and testing.
When to use it: Use when reducing C/C++ compilation times caused by header bloat, interpreting IWYU output, deciding between forward declarations and full includes, applying mapping files, or wiring IWYU into a CMake build. Also relevant when investigating compilation cascades in large codebases. It is not for general build acceleration or C++20 modules, which are covered by related skills.
Requirements: No scripts ship with the skill; it is instructions only. Using the described workflow requires the IWYU tool (iwyu, iwyu_tool.py, fix_include), a C/C++ compiler such as clang++, CMake, and a compile_commands.json build database.

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

bash

# Installapt-get install iwyu              # Ubuntu/Debianbrew install include-what-you-use # macOS
# Run on a single fileiwyu -Xiwyu --error main.cpp 2>&1
# Run via compile_commands.jsoniwyu_tool.py -p build/ src/main.cpp 2>&1 | tee iwyu.log
# Run on entire projectiwyu_tool.py -p build/ 2>&1 | tee iwyu.log

# Installapt-get install iwyu              # Ubuntu/Debianbrew install include-what-you-use # macOS
# Run on a single fileiwyu -Xiwyu --error main.cpp 2>&1
# Run via compile_commands.jsoniwyu_tool.py -p build/ src/main.cpp 2>&1 | tee iwyu.log
# Run on entire projectiwyu_tool.py -p build/ 2>&1 | tee iwyu.log

2. CMake integration

cmake

# CMakeLists.txt — use IWYU as include checker during buildfind_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()

# CMakeLists.txt — use IWYU as include checker during buildfind_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()

bash

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

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

3. Interpreting IWYU output

text

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---

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

4. Apply IWYU fixes automatically

bash

# fix_include script (comes with IWYU)fix_include < iwyu.log
# Optionsfix_include --nosafe_headers < iwyu.log    # more aggressive — also removes system headersfix_include --comments < iwyu.log          # preserve // comments in includesfix_include --dry_run < iwyu.log           # preview changes without applying
# Limit to specific filesfix_include --only_re='src/.*\.cpp' < iwyu.log
# Run and apply in one pipelineiwyu_tool.py -p build/ 2>&1 | fix_include

# fix_include script (comes with IWYU)fix_include < iwyu.log
# Optionsfix_include --nosafe_headers < iwyu.log    # more aggressive — also removes system headersfix_include --comments < iwyu.log          # preserve // comments in includesfix_include --dry_run < iwyu.log           # preview changes without applying
# Limit to specific filesfix_include --only_re='src/.*\.cpp' < iwyu.log
# Run and apply in one pipelineiwyu_tool.py -p build/ 2>&1 | fix_include

5. Forward declarations vs full includes

IWYU prefers forward declarations (class/struct declarations without definition) when the full type isn't needed:

cpp

// full_include.h — DON'T include this if only a pointer is used#include "widget.h"      // full definition: Widget members, vtable, etc.
// forward_decl.h — OK when Widget* or Widget& is sufficientclass Widget;            // forward declarationvoid process(Widget *w); // pointer: forward decl is enough
// When forward declaration is sufficient:// - Pointer or reference parameter: Widget*, Widget&// - Return type as pointer: Widget*// - Base class declared elsewhere (but defined in .cpp)
// When full include is required:// - Inheriting from Widget: class MyWidget : public Widget// - Accessing Widget members: w.field, w.method()// - Creating Widget instances: Widget w;// - Sizeof(Widget)// - Template instantiation: std::vector<Widget>

// full_include.h — DON'T include this if only a pointer is used#include "widget.h"      // full definition: Widget members, vtable, etc.
// forward_decl.h — OK when Widget* or Widget& is sufficientclass Widget;            // forward declarationvoid process(Widget *w); // pointer: forward decl is enough
// When forward declaration is sufficient:// - Pointer or reference parameter: Widget*, Widget&// - Return type as pointer: Widget*// - Base class declared elsewhere (but defined in .cpp)
// When full include is required:// - Inheriting from Widget: class MyWidget : public Widget// - Accessing Widget members: w.field, w.method()// - Creating Widget instances: Widget w;// - Sizeof(Widget)// - Template instantiation: std::vector<Widget>

cpp

// IWYU-friendly header#pragma onceclass Widget;            // forward declare (saves downstream compilation)
class Container {    Widget *head_;       // pointer: forward decl is enoughpublic:    void add(Widget *w);    Widget *get(int idx);};// Container.cpp includes "widget.h" — only .cpp pays the compile cost

// IWYU-friendly header#pragma onceclass Widget;            // forward declare (saves downstream compilation)
class Container {    Widget *head_;       // pointer: forward decl is enoughpublic:    void add(Widget *w);    Widget *get(int idx);};// Container.cpp includes "widget.h" — only .cpp pays the compile cost

6. Mapping files for third-party headers

IWYU mapping files teach IWYU about indirect includes (where #include <vector> is provided by some internal STL header):

python

# iwyu.imp — IWYU mapping file[  # Map internal LLVM headers to public ones  { "include": ["<llvm/ADT/StringRef.h>", "private",                 "<llvm/ADT/StringRef.h>", "public"] },
  # Map system headers to POSIX equivalents  { "include": ["<bits/types.h>", "private", "<sys/types.h>", "public"] },  { "include": ["<bits/socket.h>", "private", "<sys/socket.h>", "public"] },
  # Symbol → header mappings  { "symbol": ["std::string", "private", "<string>", "public"] },  { "symbol": ["NULL",        "private", "<cstddef>", "public"] },]

# iwyu.imp — IWYU mapping file[  # Map internal LLVM headers to public ones  { "include": ["<llvm/ADT/StringRef.h>", "private",                 "<llvm/ADT/StringRef.h>", "public"] },
  # Map system headers to POSIX equivalents  { "include": ["<bits/types.h>", "private", "<sys/types.h>", "public"] },  { "include": ["<bits/socket.h>", "private", "<sys/socket.h>", "public"] },
  # Symbol → header mappings  { "symbol": ["std::string", "private", "<string>", "public"] },  { "symbol": ["NULL",        "private", "<cstddef>", "public"] },]

bash

# Use mapping fileiwyu -Xiwyu --mapping_file=iwyu.imp main.cpp
# IWYU ships with common mappingsls /usr/share/include-what-you-use/# gcc.stl.headers.imp, boost-1.62.imp, libcxx.imp, etc.
iwyu -Xiwyu --mapping_file=/usr/share/include-what-you-use/gcc.stl.headers.imp

# Use mapping fileiwyu -Xiwyu --mapping_file=iwyu.imp main.cpp
# IWYU ships with common mappingsls /usr/share/include-what-you-use/# gcc.stl.headers.imp, boost-1.62.imp, libcxx.imp, etc.
iwyu -Xiwyu --mapping_file=/usr/share/include-what-you-use/gcc.stl.headers.imp

7. What IWYU does not do

IWYU has limits — be aware:

bash

# IWYU may give wrong advice for:# - Macros from headers (hard to track)# - Template specializations in included headers# - Headers required for correct ODR linking
# Safe iterative workflow:# 1. Run IWYU# 2. Apply fixes with fix_include# 3. Rebuild and run tests# 4. Revert any changes that break the build# 5. Repeat until clean
# Check for compilation cascade: how many TUs include a headergrep -rl '#include "expensive.h"' src/ | wc -l

# IWYU may give wrong advice for:# - Macros from headers (hard to track)# - Template specializations in included headers# - Headers required for correct ODR linking
# Safe iterative workflow:# 1. Run IWYU# 2. Apply fixes with fix_include# 3. Rebuild and run tests# 4. Revert any changes that break the build# 5. Repeat until clean
# Check for compilation cascade: how many TUs include a headergrep -rl '#include "expensive.h"' src/ | wc -l

Related skills

Use skills/build-systems/build-acceleration for ccache and other compile speed techniques
Use skills/build-systems/cmake for CMake integration of build analysis tools
Use skills/compilers/cpp-modules for C++20 modules as a long-term solution to include bloat

Source and attribution

Source:mohitmishra786/low-level-dev-skillsinskills/build-systems/include-what-you-useat commitbdc5847

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

Include What You Use

Include What You Use (IWYU)

Purpose

Triggers

Workflow

1. Install and run IWYU

2. CMake integration

3. Interpreting IWYU output

4. Apply IWYU fixes automatically

5. Forward declarations vs full includes

6. Mapping files for third-party headers

7. What IWYU does not do

Related skills

Source and attribution

More from mohitmishra786/low-level-dev-skills

Zig Debugging

Simd Intrinsics

Zig Cross

Rustc Basics

Zig Cinterop

Zig Build System

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices