调试CMake：message()调试，--trace与--trace-source选项，CMake的--find-package模式

说实话，CMake 写多了，谁还没遇到过几个莫名其妙的构建错误呢？变量没传过去、路径不对、依赖找不到……这些问题，光靠瞪眼是看不出来的。今天我就跟你聊聊 CMake 调试的几把“瑞士军刀”。

一、最朴素的调试法：message()

我个人习惯，遇到问题先上 message()。这玩意儿就像 C++ 里的 printf，简单粗暴，但极其有效。

message(STATUS "当前 CMAKE_SOURCE_DIR 是: ${CMAKE_SOURCE_DIR}")
message(WARNING "这个变量可能为空: ${MY_VAR}")
message(FATAL_ERROR "关键依赖缺失，停止构建！")

你看，三种级别：STATUS 打印普通信息，WARNING 会标黄警告，FATAL_ERROR 直接报错退出。我在项目中遇到过好几次，明明路径写对了，但变量就是空的。后来一查，原来是 set() 命令写在了子目录里，父目录根本看不到。用 message() 一打，立马现原形。

二、追查变量来源：--trace 与 --trace-source

有时候 message() 打出来变量是空的，但你明明记得赋值了。这时候就需要 --trace 出马了。

--trace 会打印 CMake 执行的每一行代码，包括来自哪个文件、哪一行。说白了，就是给你一个“执行流水账”。

cmake --trace -B build

输出会像这样：

/path/CMakeLists.txt:10: set(MY_VAR "hello")
/path/CMakeLists.txt:15: message(STATUS "MY_VAR = ${MY_VAR}")

嗯，这里要注意：--trace 的输出量非常大，如果你的项目有几百个文件，那刷屏速度堪比火箭发射。所以，我更常用的是 --trace-source，只追踪特定文件。

cmake --trace-source=CMakeLists.txt -B build

这样只打印主 CMakeLists.txt 的执行过程，清爽多了。我曾经为了找一个变量被谁覆盖了，用 --trace-source 配合 grep，三分钟就定位到了问题——原来是一个 add_subdirectory 里的同名变量把外层的给冲掉了。

三、查找依赖利器：--find-package 模式

你有没有遇到过这种情况：find_package(OpenCV REQUIRED) 报错说找不到，但你明明装好了？这时候 --find-package 模式就派上用场了。

这个模式是 CMake 3.24 引入的，专门用来测试 find_package 能否成功，而不需要真的执行整个构建。

cmake --find-package -DNAME=OpenCV -DCOMPILER_ID=GNU -DLANGUAGE=CXX -DMODE=EXIST

如果返回 OpenCV found，说明包是好的。如果报错，它会告诉你具体卡在哪一步。我个人觉得，这比翻 FindXXX.cmake 脚本要快得多。

为什么会有这个模式？你想想看，有时候你只是想确认一下某个库能不能被找到，但不想跑完整套 CMake 配置。这个模式就是干这个的——轻量、快速、专注。

四、知识体系总览

下面这张图，我把三种调试方法的关系和适用场景画了出来，方便你对照记忆。

五、实战组合拳

光说不练假把式。我分享一个真实案例：

有一次，我在一个大型项目中集成 OpenCV，find_package(OpenCV REQUIRED) 总是失败。我先用 --find-package 测试，发现包是存在的。然后用 message() 打印 CMAKE_PREFIX_PATH，发现路径不对。最后用 --trace-source=FindOpenCV.cmake 追查，发现脚本里有个硬编码的路径判断，跟我的系统版本不匹配。

你看，三步走，问题就解决了。如果只靠瞎猜，可能折腾半天。

好了，CMake 调试的三种方法就聊到这里。记住：message() 是侦察兵，--trace 是监控摄像头，--find-package 是体检医生。各有所长，灵活搭配才是王道。