调试CMake：message()调试技巧、cmake --trace与--trace-source、CMake输出变量查看、常见错误与解决方案
说实话，CMake 的调试体验一直是个痛点。不像 C++ 代码有 GDB 这种成熟的调试器，CMake 脚本出问题了，你往往只能靠猜。我刚开始用 CMake 那会儿，经常被莫名其妙的变量空值、路径不对、生成器表达式不生效这些问题折磨得够呛。
后来慢慢摸索出一套调试方法，今天就把这些经验分享给你。说白了，CMake 调试就三板斧：打日志、看追踪、查变量。
message()：最朴素的调试武器
这玩意儿就像 C++ 里的 printf，简单粗暴但极其有效。我个人习惯在关键位置插入 message()，把变量值、条件判断结果、生成器表达式展开后的结果都打印出来。
# 打印普通变量
message(STATUS "PROJECT_NAME = ${PROJECT_NAME}")
message(STATUS "CMAKE_CXX_STANDARD = ${CMAKE_CXX_STANDARD}")
# 打印列表变量
message(STATUS "SOURCES = ${SOURCES}")
# 打印生成器表达式（注意：不会展开）
message(STATUS "Generator expression: $<TARGET_FILE:myapp>")
我在项目中遇到过最坑的一次：一个变量在顶层 CMakeLists.txt 里赋值了，但子目录里死活拿不到。后来用 message() 一打，发现是 set() 没加 PARENT_SCOPE，变量根本没传出去。嗯，这种低级错误，打一行日志就现原形了。
cmake --trace：追踪每一行执行
message() 需要你手动插入代码，有时候你根本不知道问题出在哪一行。这时候 cmake --trace 就派上用场了。
# 追踪所有 CMake 脚本的执行
cmake --trace -B build
# 只追踪特定文件
cmake --trace-source=CMakeLists.txt -B build
# 同时追踪多个文件
cmake --trace-source=src/CMakeLists.txt --trace-source=cmake/modules/FindMyLib.cmake -B build
这个命令会把每一行执行的 CMake 代码都打印出来，包括文件名、行号、调用的命令和参数。说白了，就是给你一个逐行执行的录像回放。
cmake --trace -B build 2>&1 | grep "my_target"。
我记得有一次，一个同事说他的 target_link_libraries 明明写了，但链接时就是找不到库。我让他跑一遍 cmake --trace-source=CMakeLists.txt，结果发现他写在了 add_executable 之前——CMake 直接忽略了这条命令，连警告都没有。这种问题，光看代码根本看不出来。
查看 CMake 变量：你到底藏了多少秘密？
CMake 有几百个内置变量，加上你自己定义的，变量空间简直是个迷宫。我常用的查看方式有几种：
方法一：用 message() 打印关键变量
# 打印所有与路径相关的变量
message(STATUS "CMAKE_SOURCE_DIR = ${CMAKE_SOURCE_DIR}")
message(STATUS "CMAKE_BINARY_DIR = ${CMAKE_BINARY_DIR}")
message(STATUS "CMAKE_CURRENT_SOURCE_DIR = ${CMAKE_CURRENT_SOURCE_DIR}")
message(STATUS "CMAKE_CURRENT_BINARY_DIR = ${CMAKE_CURRENT_BINARY_DIR}")
方法二：使用 cmake -L 列出缓存变量
# 列出所有缓存变量（包括类型和值）
cmake -LA -B build
# 只列出未标记为高级的变量
cmake -L -B build
# 列出所有变量（包括高级变量）
cmake -LAH -B build
方法三：使用 CMake 的 variable_watch 命令
# 监控某个变量的所有读写操作
variable_watch(MY_VARIABLE)
# 也可以监控多个变量
variable_watch(CMAKE_CXX_FLAGS)
variable_watch(CMAKE_BUILD_TYPE)
核心经验：调试变量问题时，先确认变量是否被定义，再确认作用域是否正确，最后确认值是否被覆盖。我见过太多人花几小时找 bug，结果只是变量名拼写错了。
常见错误与解决方案
下面这些错误，我敢说你迟早会遇到。先列出来，省得你走弯路。
| 错误类型 | 典型表现 | 解决方案 |
|---|---|---|
| 变量未定义 | ${VAR} 展开为空 | 检查变量名拼写，确认 set() 是否执行，确认作用域是否正确 |
| 路径错误 | 找不到头文件/库文件 | 用 message() 打印路径变量，检查相对路径是否正确 |
| 生成器表达式不生效 | $<...> 原样输出 | 确认是否在正确上下文（如 target_link_libraries 内部）使用 |
| target 未定义 | Cannot find target "xxx" | 检查 add_executable/add_library 是否在 target_link_libraries 之前 |
| 语法错误 | CMake Error: Parse error | 检查括号匹配、空格、换行符（Windows 换行符有时会出问题） |
| 缓存冲突 | 修改了 CMakeLists.txt 但没生效 | 删除 build 目录重新配置，或使用 cmake --fresh |
避坑指南：我曾经踩过的坑
坑一：我曾经在 Windows 上写 CMake，路径用了反斜杠 \，结果 CMake 把它当成了转义字符。后来统一用正斜杠 / 或者 file(TO_CMAKE_PATH) 转换，再也没出过问题。
坑二：有一次我写 if(${VAR} STREQUAL "ON")，结果 VAR 是空字符串，展开后变成了 if( STREQUAL "ON")，CMake 直接报语法错误。正确的写法是 if(VAR STREQUAL "ON")，不要加 ${}。
坑三：生成器表达式里嵌套变量，比如 $<$<CONFIG:Debug>:-g>，我一开始以为外层 $<> 会自动展开内层。后来发现生成器表达式不支持嵌套，得用 $<$<CONFIG:Debug>:-g> 这种写法——等等，这其实也不对。正确的做法是用 genex 的组合语法，或者干脆用 if() 判断。
知识体系总览
下面这张图总结了 CMake 调试的核心方法，你可以把它当作调试时的路线图：
调试 CMake 其实没那么玄乎。你只要记住：先确认变量值对不对，再确认执行顺序对不对，最后确认语法对不对。这三步走完，大部分问题都能解决。
我个人还有一个习惯：在 CMakeLists.txt 开头加一段调试开关，用 option(ENABLE_CMAKE_DEBUG "Enable CMake debug output" OFF) 控制。需要调试时打开，不需要时关掉，省得每次改代码。
最后说一句：别怕在 CMake 里加 message()。它不像 C++ 里的 printf 会影响性能，CMake 只在配置阶段执行一次。多打几行日志，比瞎猜半小时强多了。