# 包括您使用的内容 (IWYU) ## 目的指导代理使用 IWYU 减少不必要的“#include”指令，解释 IWYU 报告和映射文件，在前向声明和完整包含之间做出决定，并将 IWYU 集成到 CMake 构建中以减少大型代码库中的编译级联。 ## 触发器 *“我如何使用 include-what-you-use？” *“如何通过修复包含来减少 C++ 编译时间？” *“如何解释 IWYU 输出？” *“我应该使用前向声明还是包含？” *“如何将 IWYU 与 CMake 集成？” *“什么是编译级联以及如何避免它？” ## 工作流程 ### 1\.安装并运行 IWYU # 安装 apt-get install iwyu # Ubuntu/Debian brew install include-what-you-use # macOS # 在单个文件上运行 iwyu -Xiwyu --error main.cpp 2>&1 # 通过compile_commands.json运行 iwyu_tool.py -p build/src/main.cpp 2>&1 | T恤 iwyu.log # 在整个项目上运行 iwyu_tool.py -p 构建/ 2>&1 | T恤 iwyu.log ### 2\. CMake集成 # CMakeLists.txt — 在构建期间使用 IWYU 作为包含检查器 find_program(IWYU_PROGRAM NAMES include-what-you-use iwyu) 如果（IWYU_PROGRAM）设置（CMAKE_CXX_INCLUDE_WHAT_YOU_USE ${IWYU_PROGRAM} -Xiwyu --mapping_file=${CMAKE_SOURCE_DIR}/iwyu.imp -Xiwyu --no_comments ）结束（） # 使用 IWYU 分析进行构建 cmake -S 。 -B 构建 -DCMAKE_CXX_COMPILER=clang++ cmake --build 构建 2>&1 | T恤 iwyu.log ### 3\.解释 IWYU 输出 main.cpp 应添加以下行： #include // 对于 std::string #include "mylib/widget.h" // 对于小部件 main.cpp 应删除这些行： - #include <向量> // 第 5-5 行 - #include "internal/detail.h" // 第 8-8 行 main.cpp 的完整包含列表： #include // 对于 std::cout #include // 对于 std::string #include "mylib/widget.h" // 对于小部件 --- 读取输出： * **应该添加**：提供已使用但尚未包含的符号的标头 * **应该删除** ：包含标头，但不直接使用其符号 * **完整的包含列表**：最终的标头列表应该是什么样子 ### 4\.自动应用 IWYU 修复 # fix_include 脚本（IWYU 附带） fix_include < iwyu.log # 选项 fix_include --nosafe_headers < iwyu.log # 更激进 — 还删除系统标头 fix_include --comments < iwyu.log # 保留 // 包含中的注释 fix_include --dry_run < iwyu.log # 预览更改而不应用 # 限制特定文件 fix_include --only_re='src/.*\.cpp' < iwyu.log # 在一个管道中运行并应用 iwyu_tool.py -p 构建/ 2>&1 |修复包含 ### 5\.前向声明与完整包含当不需要完整类型时，IWYU 更喜欢前向声明（没有定义的类/结构声明）： // full_include.h — 如果仅使用指针，则不包含此内容 #include "widget.h" // 完整定义：Widget 成员、vtable 等。 //forward_decl.h — 当 Widget* 或 Widget& 足够时 OK 小部件类； // 前向声明无效进程(Widget *w); // 指针：向前 decl 就足够了 // 当前向声明足够时： // - 指针或引用参数：Widget*、Widget& // - 返回类型作为指针：Widget* // - 在其他地方声明的基类（但在 .cpp 中定义） // 当需要完整包含时： // - 继承自 Widget: class MyWidget : public Widget // - 访问 Widget 成员：w.field、w.method() // - 创建 Widget 实例：Widget w; // - Sizeof(小部件) // - 模板实例化：std::vector // IWYU 友好的标头 #pragma 一次小部件类； // 前向声明（保存下游编译）类容器{ 小部件*head_； // 指针：向前 decl 就足够了公众：无效添加（小部件* w）；小部件 *get(int idx); }; // Container.cpp 包含“widget.h”——只有 .cpp 支付编译成本 ### 6\.第三方标头的映射文件 IWYU 映射文件向 IWYU 介绍间接包含（其中“#include ”由某些内部 STL 标头提供）： # iwyu.imp — IWYU 映射文件 [ # 将内部 LLVM 标头映射到公共标头 {“包括”：[“”，“私有”， "", "公共"] }, # 将系统标头映射到 POSIX 等效项 { "include": ["", "private", "", "public"] }, { "include": ["", "private", "", "public"] }, # 符号 → 标头映射 { "symbol": ["std::string", "private", "", "public"] }, { "symbol": ["NULL", "private", "", "public"] }, ] # 使用映射文件 iwyu -Xiwyu --mapping_file=iwyu.imp main.cpp # IWYU 附带通用映射 ls /usr/share/include-what-you-use/ # gcc.stl.headers.imp、boost-1.62.imp、libcxx.imp 等 iwyu -Xiwyu --mapping_file=/usr/share/include-what-you-use/gcc.stl.headers.imp ### 7\. IWYU 不做什么 IWYU 有其局限性——请注意： # IWYU 可能会给出错误的建议： # - 来自标头的宏（难以跟踪） # - 包含的标头中的模板专业化 # - 正确 ODR 链接所需的标头 # 安全的迭代工作流程： # 1. 运行 IWYU # 2. 使用 fix_include 应用修复 # 3. 重建并运行测试 # 4. 恢复任何破坏构建的更改 # 5.重复直到干净 # 检查编译级联：有多少 TU 包含标头 grep -rl '#include "expense.h"' src/|厕所-l ## 相关技能 * 使用 `skills/build-systems/build-acceleration` 进行 ccache 和其他编译速度技术 * 使用 `skills/build-systems/cmake` 进行构建分析工具的 CMake 集成 * 对 C++20 模块使用 `skills/compilers/cpp-modules` 作为包含膨胀的长期解决方案

包括您使用的内容

包含技能