sanitizers-cmake 是一个轻量级 CMake 脚本集合，用于自动启用 Clang/GCC 的 Address/Thread/UndefinedBehaviorSanitizer，解决手动配置易漏、优化冲突、Release 下链接失败等问题。

什么是 sanitizers-cmake，它能解决什么问题

sanitizers-cmake 是一个轻量级 CMake 脚本集合，用于在构建时自动启用 Clang/GCC 的 AddressSanitizer、ThreadSanitizer、UndefinedBehaviorSanitizer 等检测器。它不替代 sanitizer 本身，而是帮你绕过手动配置编译选项的繁琐过程——比如避免漏加 -fsanitize=address、忘记禁用优化、或在 Release 模式下误启 sanitizer 导致链接失败。

如何在 CMakeLists.txt 中集成 sanitizers-cmake

最简集成方式是通过 FetchContent 动态拉取并启用所需 sanitizer。注意：必须在 project() 之后、add_executable() 或 add_library() 之前调用配置逻辑。

• 确保你的 CMake 版本 ≥ 3.14（FetchContent 稳定支持）
• Clang ≥ 6.0 或 GCC ≥ 8.0 才具备完整 sanitizer 支持；GCC 的 ThreadSanitizer 对 C++17 std::shared_mutex 等有已知限制
• 不要在 CMAKE_BUILD_TYPE=Release 下启用 sanitizer——它们依赖调试信息和未优化代码，否则会触发 undefined reference to __asan_init 类链接错误

include(FetchContent)
FetchContent_Declare(
  sanitizers_cmake
  GIT_REPOSITORY https://github.com/arsenm/sanitizers-cmake.git
  GIT_TAG        v1.2.0
)
FetchContent_MakeAvailable(sanitizers_cmake)
启用 AddressSanitizer + UndefinedBehaviorSanitizer
setup_sanitizers(ADDRESS UNDEFINED)
可选：单独启用 ThreadSanitizer（注意：仅支持 Clang，且需链接 -lpthread）
setup_sanitizers(THREAD)

常见构建失败原因与修复方式

启用后编译失败，大概率不是脚本问题，而是环境或项目配置冲突：

• undefined reference to __tsan_init：说明链接时没带 -fsanitize=thread，检查是否只在 CXX_FLAGS 加了 flag 却没同步到链接器——setup_sanitizers() 内部已处理，但若你手动覆盖了 CMAKE_EXE_LINKER_FLAGS 就会失效
• 使用 find_package(Threads) 后仍报线程相关 undefined symbol：Clang 的 TSan 要求所有目标都统一启用，包括依赖的静态库；若某个子目录没调用 setup_sanitizers()，就会断链
• 运行时报 ERROR: ThreadSanitizer: failed to intercept 'malloc'：通常是动态加载了未插桩的第三方 .so（如某些 GPU 驱动库），需用 TSAN_OPTIONS="ignore_noninstrumented_modules=1" 临时绕过
• Windows 上无法使用：sanitizers-cmake 仅支持 Linux/macOS；MSVC 完全不支持 ASan/TSan，Clang-CL 方式也受限

为什么不能把 sanitizer 当成 CI 中的“兜底测试”

sanitizer 是编译期注入的运行时检测，它只覆盖实际执行到的代码路径。这意味着：

• 没被单元测试调用的分支、异常路径、初始化逻辑，不会触发 ASan 报告内存泄漏或越界
• TSan 的数据竞争检测依赖线程调度时机，一次通过 ≠ 无竞争；需配合 TSAN_OPTIONS="second_deadlock_timeout=1" 增加压力
• UBSan 对 std::vector::at() 越界默认静默，需显式开启 -fsanitize=undefined -fno-sanitize-recover=undefined 才中止进程
• 生产环境绝对禁止启用——性能损耗达 2–3 倍，内存占用翻倍，且部分 sanitizer（如 MSan）要求全链路（包括 libc）重编译

真正有效的做法是：在 CI 中为每个 PR 构建一个 Sanitize 构建类型，跑完全部单元测试 + 关键集成路径，并把 ASAN_OPTIONS=detect_leaks=1 写进环境变量——否则 ASan 默认关闭泄漏检测。