CMake项目中配置clang-tidy时排除外部系统头文件分析的正确方法

你遇到的核心问题是：即便你已经通过SYSTEM PRIVATE标记了TCLAP的包含目录，clang-tidy的静态分析模块（比如clang-analyzer系列选项）仍然会扫描外部依赖的头文件，导致触发第三方库本身的代码警告（甚至因为你开了-warnings-as-errors而编译失败）。下面是几种不用NOLINT就能解决问题的正确配置方式：

方法一：针对单个Target调整clang-tidy选项 #

你可以修改现有的enable_clang_tidy函数，给clang-tidy添加--system-headers=false选项，明确告诉它跳过系统头文件的分析：

# 根目录CMakeLists.txt中的enable_clang_tidy函数
function(enable_clang_tidy target)
  set_target_properties(${target} PROPERTIES
    CXX_CLANG_TIDY "${CLANG_TIDY_EXE};--quiet;--system-headers=false"
  )
endfunction()

这个选项会让clang-tidy完全忽略所有标记为系统目录的头文件，自然就不会触发TCLAP内部的虚拟调用警告了。

方法二：全局配置CMAKE_CXX_CLANG_TIDY（推荐） #

如果你想在整个项目中统一启用clang-tidy，更符合最佳实践的方式是使用全局的CMAKE_CXX_CLANG_TIDY变量，同时保留SYSTEM包含目录的设置：

1. 在根目录CMakeLists.txt中配置全局clang-tidy：

find_program(CLANG_TIDY_EXE NAMES "clang-tidy")
if(CLANG_TIDY_EXE)
  # 全局启用clang-tidy，添加--system-headers=false跳过系统头文件
  set(CMAKE_CXX_CLANG_TIDY "${CLANG_TIDY_EXE};--quiet;--system-headers=false")
  message(STATUS "Found clang-tidy: ${CLANG_TIDY_EXE} (enabled globally)")
else()
  message(FATAL_ERROR "clang-tidy not found!")
endif()

2. 在src/CMakeLists.txt中，你可以移除enable_clang_tidy(ccwc)调用（因为全局配置已经生效），但要保留SYSTEM包含目录的设置：

find_path(TCLAP_INCLUDE_DIR tclap/CmdLine.h 
  HINTS /opt/homebrew/include /usr/local/include /usr/include 
)
if(NOT TCLAP_INCLUDE_DIR)
  message(FATAL_ERROR "TCLAP not found. Please install it with `brew install tclap`.")
endif()

add_executable(ccwc main.cpp)
# 保持SYSTEM PRIVATE标记，确保CMake和clang-tidy都识别为系统目录
target_include_directories(ccwc SYSTEM PRIVATE ${TCLAP_INCLUDE_DIR})
target_link_libraries(ccwc)
# 不需要再调用enable_clang_tidy，全局配置已生效

方法三：精确过滤要检查的文件（进阶） #

如果你想更精细地控制clang-tidy扫描的范围（比如只检查你自己项目的代码），可以添加--header-filter选项，指定只扫描项目目录下的头文件：

比如针对全局配置：

set(CMAKE_CXX_CLANG_TIDY "${CLANG_TIDY_EXE};--quiet;--header-filter=^${PROJECT_SOURCE_DIR}/src/")

这个选项会让clang-tidy只处理src目录下的头文件，完全忽略外部依赖的头文件。如果你项目有多个代码目录（比如include），可以调整过滤规则：

--header-filter=^${PROJECT_SOURCE_DIR}/(src|include)/

最后验证 #

配置完成后，删除代码中的// NOLINT注释，重新生成CMake缓存并编译：

cmake --build . --clean-first

此时clang-tidy应该只会扫描你自己的代码，不再触发TCLAP头文件中的警告，编译可以正常通过。

内容来源于stack exchange