调试CMake：message命令、cmake --trace、cmake --debug-output、CMake错误排查
说实话，CMake 这玩意儿，写起来挺爽，但一旦出问题，排查起来也够呛。我见过不少同事，CMakeLists.txt 写了上百行，一运行报错，整个人就懵了。其实啊，CMake 自己带了一套很实用的调试工具，只是很多人不知道，或者懒得用。
今天我就把这些压箱底的调试手段，一个一个掰开揉碎了讲给你听。
message()：最朴素的调试利器
你想想看，写 C++ 代码的时候，我们怎么调试？printf 大法对吧？CMake 里也有类似的——message() 命令。这玩意儿简单粗暴，但真的管用。
message("当前变量 MY_VAR 的值是：${MY_VAR}")
message(STATUS "正在配置模块：${MODULE_NAME}")
message(WARNING "这个路径好像不太对：${FILE_PATH}")
message(FATAL_ERROR "必须指定 BUILD_TYPE，否则无法继续！")
我个人习惯，在写复杂 CMake 脚本时，每定义一个关键变量，后面就跟一句 message() 打印出来。这样配置过程一目了然。
- 不加前缀：直接打印，没什么格式
STATUS：最常用，前面会带两个横线，看起来清爽WARNING：警告，会高亮显示，但不会中断FATAL_ERROR：致命错误，打印完直接退出
我在项目中遇到过一个问题：一个第三方库死活找不到，折腾了半天。后来加了一行 message(STATUS "CMAKE_PREFIX_PATH = ${CMAKE_PREFIX_PATH}")，才发现路径写错了。你说冤不冤？
cmake --trace：追踪每一行执行
有时候，光靠 message() 不够。比如你的 CMakeLists.txt 里有很多条件判断、循环、函数调用，你根本不知道哪一行被执行了，哪一行被跳过了。这时候，cmake --trace 就派上用场了。
# 在终端执行
cmake --trace -B build
这个命令会打印出 CMake 执行的每一行代码，包括它来自哪个文件、哪一行。说白了，就像给 CMake 装了个放大镜，每一行都逃不过你的眼睛。
/home/user/project/CMakeLists.txt:12: set(MY_VAR "hello")
/home/user/project/CMakeLists.txt:15: if(MY_VAR STREQUAL "hello")
/home/user/project/CMakeLists.txt:16: message(STATUS "MY_VAR is hello")
嗯，这里要注意：--trace 的输出量很大。如果你的项目很大，建议先在小范围测试，或者配合 --trace-source 只追踪特定文件。
# 只追踪 CMakeLists.txt 这个文件
cmake --trace-source=CMakeLists.txt -B build
cmake --debug-output：更详细的配置信息
如果说 --trace 是放大镜，那 --debug-output 就是 X 光机。它不会打印每一行代码，但会输出 CMake 内部的一些关键决策过程，比如：
- 查找了哪些路径
- 哪些缓存变量被读取了
- 哪些策略被设置了
cmake --debug-output -B build
我记得有一次，一个项目在 Windows 上编译不过，Linux 上却好好的。我用了 --debug-output，发现 CMake 在 Windows 上查找某个库时，走了一条完全不同的路径。原来是因为环境变量没设置对。
--debug-output 和 --trace 可以一起用，但输出会非常冗长。建议先单独用，不行再组合。
CMake 错误排查：从报错信息到解决方案
好了，工具都介绍完了，咱们来聊聊实战。遇到 CMake 报错，别慌，按这个步骤来：
- 看报错信息的第一行：CMake 的错误信息通常很明确，比如
CMake Error at CMakeLists.txt:10，直接告诉你哪一行出问题了。 - 看错误类型：是语法错误？还是找不到文件？还是变量未定义？
- 用 message() 打印关键变量：很多时候，错误是因为变量值不是你想象的那样。
- 用 --trace 定位执行路径：看看是不是走了不该走的分支。
- 检查缓存：有时候
CMakeCache.txt里残留了旧值，删掉重新配置试试。
| 错误信息 | 可能原因 | 解决方法 |
|---|---|---|
| 找不到某个库 | 路径没设置对 | 检查 CMAKE_PREFIX_PATH 或 find_package 的路径 |
| 语法错误 | 括号不匹配、拼写错误 | 用 --trace 定位到具体行 |
| 变量未定义 | 变量名写错了，或者作用域不对 | 用 message() 打印变量值 |
| 策略错误 | CMake 版本不兼容 | 设置 cmake_policy 或升级 CMake |
我曾经遇到过一个特别坑的问题：一个项目在同事电脑上能配置，在我电脑上就报错。折腾了半天，最后发现是 CMake 版本不一样。他用的 3.20，我用的 3.10，有些新特性不支持。从那以后，我养成了一个习惯——在 CMakeLists.txt 开头加一句：
cmake_minimum_required(VERSION 3.15)
这样至少能保证基础功能一致。
知识体系总览
下面这张图，把本章的调试方法串起来了。你可以把它当成一个排查路线图：
说白了，调试 CMake 没什么高深的。核心就三点：打印变量、追踪执行、查看内部决策。把这三点用好，90% 的问题都能自己搞定。
message(STATUS) 打印关键路径和变量。等一切稳定了，再删掉。这样既不影响最终配置，又能随时排查问题。
好了，这一章的内容就到这里。记住，遇到 CMake 报错别慌，先深呼吸，然后按我们讲的步骤来。你很快就能成为团队里的 CMake 调试高手。
公众号：蓝海资料掘金营，微信 deep3321