22、使用CMake的--debug-output与--trace：调试CMake配置过程的技巧
说实话，CMake的配置过程有时候像个黑盒子。
你写好了CMakeLists.txt，敲下cmake命令，然后……要么一切顺利，要么就是一堆看不懂的错误。我刚开始用CMake那会儿，遇到配置失败，只能一遍遍检查代码，效率低得让人抓狂。
后来我才发现，CMake其实自带了两把调试利器——--debug-output和--trace。用好它们，配置过程就像开了上帝视角，每一步都清清楚楚。
为什么需要调试CMake配置？
先说说我踩过的坑。有一次做交叉编译，工具链文件写了一大堆，结果配置时死活找不到编译器。我盯着CMakeLists.txt看了半天，逻辑上没问题啊。最后用了一个调试选项，才发现是变量作用域搞错了——某个set命令写在了子目录里，根本没生效。
你想想看，如果没有调试工具，这种问题只能靠猜。CMake的配置过程涉及变量定义、条件判断、文件包含、函数调用……任何一个环节出问题，都可能让整个构建失败。
所以，掌握调试技巧，不是锦上添花，而是必备技能。
--debug-output：看CMake在做什么
--debug-output这个选项，说白了就是让CMake把配置过程中的关键步骤打印出来。它不会告诉你每一行代码的执行细节，但会展示出重要的决策点。
基本用法：
cmake --debug-output -B build运行后，你会看到类似这样的输出：
CMake Debug Output:
Determining if the C compiler works
Determining if the C compiler works - yes
Determining if the CXX compiler works
Determining if the CXX compiler works - yes
Looking for include files
Looking for include files - found
...
嗯，这里要注意：--debug-output的输出比较简洁，它主要告诉你CMake在哪个阶段、做了什么检查。比如编译器是否可用、头文件是否找到、库文件是否链接成功。
我个人习惯在第一次配置新项目时，总是带上这个选项。它能帮我快速确认：
- 编译器检测是否通过
- 依赖库是否被正确找到
- 平台相关的条件判断是否命中
有一次我在Windows上交叉编译ARM程序，配置时一直报错说找不到某个库。用--debug-output一看，发现CMake在搜索路径时根本没去我指定的目录。原来是路径字符串里混了反斜杠和正斜杠，CMake解析出了问题。这种问题，不看调试输出，真的很难定位。
--trace：逐行追踪CMake的执行
如果说--debug-output是看大纲，那--trace就是看逐字稿。它会打印出CMake执行的每一行代码，包括变量展开后的实际值。
基本用法：
cmake --trace -B build输出会非常详细，像这样：
/path/to/CMakeLists.txt:10: set(CMAKE_C_FLAGS "-O2 -Wall")
/path/to/CMakeLists.txt:12: add_executable(myapp main.c)
/path/to/CMakeLists.txt:15: target_link_libraries(myapp m)
每一行都标注了文件名和行号，后面跟着实际执行的命令。这有什么用？我举个例子。
我曾经在项目里用了一个复杂的宏函数，里面嵌套了好几个if-else。配置时总是选错分支，但代码看起来没问题。用--trace一跑，发现某个变量的值跟我预期的不一样——原来是在前面的某个地方被意外覆盖了。你想想看，如果没有逐行追踪，这种问题得排查多久？
小技巧：如果输出太多，可以配合grep过滤。比如只关注某个文件或某个变量：
cmake --trace -B build 2>&1 | grep "CMAKE_C_COMPILER"--trace-expand：看变量的真实值
--trace虽然好，但它打印的是原始命令。如果命令里用了变量，比如${MY_VAR}，它只会打印${MY_VAR}，而不是展开后的值。
这时候就需要--trace-expand了。它会先把变量展开，再打印出来。
cmake --trace-expand -B build输出示例：
/path/to/CMakeLists.txt:20: set(CMAKE_C_FLAGS "-O2 -Wall -DDEBUG=1")
/path/to/CMakeLists.txt:22: add_executable(myapp /home/user/src/main.c /home/user/src/utils.c)
看到区别了吗？变量${CMAKE_C_FLAGS}和${SRC_FILES}都被展开了。这在调试变量传递问题时特别有用。
我记得有一次，我在工具链文件里定义了一个CMAKE_SYSROOT变量，但配置时总是找不到头文件。用--trace-expand一看，发现变量展开后路径少了一个斜杠——/opt/arm/sysroot变成了/opt/armsysroot。原来是字符串拼接时忘了加分隔符。这种细节，不展开看根本发现不了。
三个选项的对比
| 选项 | 输出粒度 | 适用场景 |
|---|---|---|
--debug-output |
阶段级（编译器检测、库查找等） | 快速确认配置流程是否正常 |
--trace |
行级（原始命令） | 追踪代码执行路径，定位逻辑错误 |
--trace-expand |
行级（变量展开后） | 排查变量值传递、路径拼接等问题 |
实战：调试交叉编译的工具链文件
交叉编译时，工具链文件最容易出问题。我分享一个我常用的调试流程。
假设我有一个工具链文件arm-toolchain.cmake，内容大致如下：
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR arm)
set(CMAKE_C_COMPILER /opt/arm-gcc/bin/arm-linux-gnueabihf-gcc)
set(CMAKE_CXX_COMPILER /opt/arm-gcc/bin/arm-linux-gnueabihf-g++)
set(CMAKE_FIND_ROOT_PATH /opt/arm-gcc/arm-linux-gnueabihf/sysroot)
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
配置时，我会这样调试：
- 先用
--debug-output看整体流程：确认编译器检测、sysroot查找是否正常。 - 如果某个库找不到，用
--trace-expand追踪find_library：看看搜索路径是不是对的。 - 如果条件判断出错，用
--trace看执行路径：确认哪个分支被执行了。
举个例子，有一次我在工具链文件里写了：
if(CMAKE_SYSTEM_PROCESSOR STREQUAL "arm")
set(ARM_FLAGS "-march=armv7-a")
endif()
配置时发现ARM_FLAGS没被设置。用--trace一看，发现CMAKE_SYSTEM_PROCESSOR的值是ARM（大写），而我比较的是小写的arm。这种大小写问题，不看追踪输出，真的很难想到。
注意事项：
--trace和--trace-expand输出量很大，建议重定向到文件查看：cmake --trace -B build 2> trace.log- 调试完成后，记得去掉这些选项。它们会拖慢配置速度，尤其是大项目。
- 如果项目使用了
include()或add_subdirectory()，追踪输出会包含所有被包含的文件，注意区分。
知识体系总览
下面这张图，帮你理清这三个调试选项的关系和使用场景：
写在最后
调试CMake配置，说白了就是让CMake告诉你它到底在想什么。--debug-output、--trace、--trace-expand这三个选项，就是你和CMake对话的翻译器。
我个人建议，每个CMake项目在初期配置时，至少用--debug-output跑一遍。花不了几秒钟，但能帮你省下大把排查问题的时间。至于--trace系列，遇到疑难杂症时再用，毕竟输出量确实不小。
嗯，调试工具就在那里，用不用是你的事。但我想说，真正的高手，不是不出错，而是出错后能快速定位问题。希望今天的内容，能让你在CMake调试这条路上，少走一些弯路。
公众号:蓝海资料掘金营，微信deep3321