如何配置IWYU分析项目自有头文件而非仅主程序cpp源文件

踩坑原因说明 #

• 所有iwyu专属参数必须加-Xiwyu前缀，否则会被直接传递给底层clang，触发「unsupported option」报错，这点你已经定位正确。
• 0.17版本iwyu的--check_also参数不支持shell通配符，shell提前展开*时如果匹配到不符合clang命名规则的标识符、或者路径格式不匹配，就会触发你遇到的NamedDecl::getName()断言崩溃，属于该版本已知问题，不是配置写法错误。
• CMake的CMAKE_CXX_INCLUDE_WHAT_YOU_USE机制是逐编译单元（即每个.cpp文件）调用iwyu，默认仅检查当前编译单元对应的源文件，不会主动扫描关联的项目头文件。
• 通过-isystem引入的系统头文件iwyu默认会跳过，不会输出相关检查报告，不需要额外加参数屏蔽。

方案1：CMake 集成（日常开发推荐） #

不需要手动遍历文件，在配置阶段提前收集全量项目头文件的绝对路径，逐个传给--check_also即可避开通配符问题，和编译流程绑定，增量检查速度快。
在项目根CMakeLists.txt中添加如下配置：

# 自动收集项目源码、头文件目录下所有.h/.hpp文件，新增头文件时重新执行cmake即可自动更新列表
file(GLOB_RECURSE PROJECT_LOCAL_HEADERS CONFIGURE_DEPENDS
    "${PROJECT_SOURCE_DIR}/include/*.h"
    "${PROJECT_SOURCE_DIR}/include/*.hpp"
    "${PROJECT_SOURCE_DIR}/src/*.h"
    "${PROJECT_SOURCE_DIR}/src/*.hpp"
)

# 组装iwyu启动参数
set(IWYU_CMD "iwyu")
foreach(header_path ${PROJECT_LOCAL_HEADERS})
    list(APPEND IWYU_CMD "-Xiwyu" "--check_also=${header_path}")
endforeach()

# 追加常用iwyu规则
list(APPEND IWYU_CMD
    "-Xiwyu" "--cxx17ns"
    "-Xiwyu" "--quoted_includes_first"
)

# 全局开启iwyu检查
set(CMAKE_CXX_INCLUDE_WHAT_YOU_USE ${IWYU_CMD})

之后正常执行配置、编译命令即可自动触发检查：

cmake .. -DCMAKE_BUILD_TYPE=Debug
make -j$(nproc)

方案2：手动批量扫描（适合CI全量检查场景） #

你之前写的find遍历逻辑缺少编译参数传递，直接运行会因为找不到宏定义、include路径产生大量误报，需要配合CMake导出的编译命令数据库使用：

1. 配置CMake时开启编译命令数据库导出：

cmake .. -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

2. 遍历头文件执行检查时，通过-p参数指定编译数据库路径，iwyu会自动读取每个文件对应的编译参数，消除误报：

find ./include ./src \( -name "*.hpp" -o -name "*.h" \) | xargs iwyu \
    -Xiwyu --cxx17ns \
    -Xiwyu --quoted_includes_first \
    -p ./compile_commands.json \
    -std=c++17

注意：--check_also传入的路径必须和编译数据库中记录的绝对路径完全匹配，传相对路径会导致匹配失败，头文件检查不生效。

版本提示 #

你当前使用的iwyu 0.17基于clang13，对C20及以上标准的支持不完善，如果项目使用新C标准，建议升级到0.20以上版本，新版本已经修复了通配符触发的断言崩溃问题，原生支持--check_also传入glob规则，配置可以更简洁。

内容的提问来源于stack exchange，提问作者alfC