如何排查CMake中触发全量重编译的选项或属性？

一、获取过期判定的详细执行日志 #

• 重新执行CMake配置时，添加--debug-output和--trace-expand参数：前者会输出CMake内部依赖检查、过期判定的核心细节；后者会展开所有变量并追踪每条指令的执行流程，能帮你定位到哪一步触发了全局依赖失效。示例命令：

  cmake --build . --debug-output --trace-expand
  

• 如果使用Ninja作为构建生成器，搭配-v参数可以让构建系统输出更完整的依赖链信息，便于追踪哪些目标被标记为过期：

  ninja -v
  

• 构建目录下的CMakeCache.txt、CMakeFiles/CMakeOutput.log和CMakeFiles/CMakeError.log也是关键参考，这些文件记录了配置阶段的缓存变量变更、指令执行结果，能帮你排查缓存污染或配置错误。

二、常规排查方法 #

1. 检查全局变量的不当定义 #

• 排查根CMakeLists.txt或全局引入的脚本中，是否把源文件列表、编译选项、宏定义等核心配置直接硬编码，或通过不稳定变量（比如依赖系统时间、临时文件路径）生成。这类全局变更会导致所有目标的依赖链被标记为过期。
• 借助--trace-expand的输出，对比修改CMakeLists.txt前后的变量值变化，重点关注CMAKE_CXX_FLAGS、CMAKE_C_FLAGS、项目全局的源文件列表变量这类影响范围广的内容。

2. 排查自定义命令/目标的依赖错误 #

• 检查add_custom_command或add_custom_target是否错误地将根CMakeLists.txt、全局脚本文件作为依赖，导致修改任意CMakeLists.txt时触发这些自定义目标重建，进而牵连整个项目。
• 用cmake --graphviz=dep.dot生成项目依赖图，可视化查看是否存在不合理的全局依赖链路（比如所有目标都直接依赖根CMakeLists.txt）。

3. 检查CMake缓存的异常变更 #

• 运行cmake -L列出所有缓存变量，确认是否有变量被滥用FORCE属性，导致每次配置时强制覆盖缓存值，触发全量重建。
• 尝试删除构建目录下的CMakeCache.txt和CMakeFiles目录，重新配置后测试是否还会全量编译，排除缓存残留导致的异常。

4. 排查INTERFACE目标的全局影响 #

• 检查项目中的INTERFACE类型目标（比如头文件库），是否错误地将CMakeLists.txt文件纳入依赖，或其INTERFACE_COMPILE_DEFINITIONS、INTERFACE_INCLUDE_DIRECTORIES等属性被全局修改，导致所有依赖该目标的子项目都触发重建。

5. 检查生成器表达式的错误使用 #

• 若项目大量使用生成器表达式，排查是否有表达式依赖了CMAKE_CURRENT_LIST_DIR这类随脚本位置变化的变量，却被全局引用，导致修改任意CMakeLists.txt时表达式结果全局变更，触发全量编译。

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