使用CMake接口目标与编译数据库时clang-tidy报文件未找到错误

问题背景 #

基于CMake构建的C++代码库中，使用clang-tidy -p <build-dir>调用工具时，出现如下错误：

error: 'static_1.h' file not found [clang-diagnostic-error]

clang-tidy以状态码2退出，导致构建失败。已知移除、重命名名为ignored的目标，或将其改为INTERFACE类型时错误消失，但需求是仅通过CMake配置修复，不修改目标类型或依赖额外工具。环境为Debian 12、CMake 3.25.1、clang-tidy 14.0.6。

原因分析 #

该问题本质是CMake生成的编译数据库（compile_commands.json）中，ignored目标的编译命令干扰了主目标的头文件路径解析。当ignored为STATIC/SHARED类型时，即使未被主目标依赖，CMake仍会将其编译命令写入数据库，导致clang-tidy解析时丢失或混淆了必要的-I包含路径。

可行解决方案 #

1. 排除干扰目标的编译命令导出 #

通过设置ignored目标的EXPORT_COMPILE_COMMANDS属性为OFF，阻止其编译命令被写入数据库，仅保留需要检查的目标条目：

set_target_properties(ignored PROPERTIES EXPORT_COMPILE_COMMANDS OFF)

重新生成构建文件后，编译数据库将只包含主目标的正确编译命令，消除路径干扰。

2. 确保主目标的头文件路径正确传递 #

若static_1.h属于项目依赖的头文件目录，通过target_include_directories明确声明包含路径，并使用PUBLIC/INTERFACE保证路径被传递到编译命令中：

# 替换为static_1.h实际所在的目录
target_include_directories(your_main_target
  PUBLIC
    ${PROJECT_SOURCE_DIR}/path/to/static_headers
)

该操作确保clang-tidy能通过编译命令中的-I参数找到目标头文件。

3. 直接使用CMake集成的clang-tidy #

CMake原生支持在构建流程中调用clang-tidy，通过设置CMAKE_CXX_CLANG_TIDY变量，让CMake自动传递完整的编译环境参数，无需手动处理编译数据库：

# 可根据需求调整clang-tidy的检查规则
set(CMAKE_CXX_CLANG_TIDY "clang-tidy;-checks=*")

启用该配置后，每次构建时CMake会自动对源码运行clang-tidy，完全复用构建时的头文件路径和编译参数，从根源避免路径问题。

验证方法 #

应用上述任一方案后，执行以下步骤验证：

• 删除旧的编译数据库和构建文件
• 重新运行cmake -S . -B <build-dir>生成构建配置
• 运行clang-tidy -p <build-dir>或直接执行构建命令，确认头文件错误消失

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