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 週前更新