Include What You Use

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

作者 mohitmishra786bdc58472fa9f无许可证253 个星标收录于 2026年10月9日更新于 2026年10月9日仓库3个月前更新

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.

仅含说明Software Development
AI 生成的概览

指导 C/C++ 开发者使用 Include What You Use 精简头文件包含并减少编译级联。

功能
说明如何安装和运行 IWYU，包括单文件运行以及通过 iwyu_tool.py 配合 compile_commands.json 的整项目运行。介绍如何解读 IWYU 报告、用 fix_include 应用修复、把 IWYU 集成到 CMake 构建、为第三方头文件编写映射文件，以及在向前声明与完整包含之间做选择。还列出 IWYU 的局限，以及运行、修复、重新构建并测试的安全迭代流程。
适用场景
适用于因头文件膨胀导致 C/C++ 编译变慢、需要解读 IWYU 输出、在向前声明与完整包含之间取舍、应用映射文件，或把 IWYU 接入 CMake 构建的场景。也适合排查大型代码库中的编译级联问题。不适用于通用构建加速或 C++20 模块，这些由相关技能覆盖。
运行要求
该技能不附带脚本，仅为说明性指令。按所述流程操作需要 IWYU 工具（iwyu、iwyu_tool.py、fix_include）、C/C++ 编译器（如 clang++）、CMake，以及 compile_commands.json 构建数据库。

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

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()
bash
# 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---

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

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

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"] },]
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

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

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

来源与署名

来源：mohitmishra786/low-level-dev-skills位于skills/build-systems/include-what-you-use提交bdc5847

许可证： 无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

更多来自 mohitmishra786/low-level-dev-skills 的技能

Zig Debugging

mohitmishra786

指导使用 GDB、LLDB 调试 Zig 程序，解读 panic、错误返回追踪、日志记录及 IDE 配置。

Software Development2533个月前更新

Simd Intrinsics

mohitmishra786

指导使用 x86 SSE/AVX 与 ARM NEON 内建函数编写和诊断 SIMD 向量化。

Software Development2533个月前更新

Zig Cross

mohitmishra786

指导 Zig 交叉编译：目标三元组、CPU 特性、用 zig cc 编译 C、嵌入式与 WASM 目标。

Software Development2533个月前更新

Rustc Basics

mohitmishra786

指导 Rust 编译器配置：RUSTFLAGS、Cargo 配置文件、构建调优，以及查看 MIR 或汇编输出。

Software Development2533个月前更新

Zig Cinterop

mohitmishra786

指导 Zig 与 C 互操作：@cImport、translate-c、extern 与 packed 结构体，以及 C/Zig 混合构建。

Software Development2533个月前更新

Zig Build System

mohitmishra786

指导编写和调试 Zig 的 build.zig 文件，涵盖目标、C 源码、选项、测试与包清单。

Software Development2533个月前更新

更多Software Development技能

Playground

anthropics

精选

构建自包含的交互式 HTML 演练场，包含控件、实时预览和可复制的提示词输出。

Software Development37K今天更新

M5 Onboard

anthropics

精选

通过 USB 检测 M5Stack ESP32 开发板，刷写 UIFlow 2.0 固件并安装 MicroPython 应用包。

Software Development37K今天更新

Cardputer Buddy

anthropics

精选

指导迭代 Cardputer-Adv 的 MicroPython 应用包：添加应用、通过 USB 串口推送文件、查看日志并运行 REPL 命令。

Software Development37K今天更新

Web Design Guidelines

vercel-labs

精选

依据从远程来源获取的 Web Interface Guidelines 审查 UI 代码，并以 file:line 形式报告问题。

Software Development32K5周前更新

Vercel React Native Skills

vercel-labs

精选

React Native 与 Expo 最佳实践规则，涵盖列表性能、动画、导航、UI 模式、状态与 monorepo 配置。

Software Development32K5周前更新

Vercel React Best Practices

vercel-labs

精选

Vercel 的 React 与 Next.js 性能指南，以 70 条规则的形式用于编写、审查和重构代码。

Software Development32K5周前更新