预设的验证与调试：使用 cmake --preset 命令测试预设配置
写好的预设配置，到底能不能用？
这个问题，我当年刚接触 CMake Presets 时也问过自己。你想想看，辛辛苦苦写了一大堆 CMakePresets.json，结果一跑就报错，那多尴尬。其实 CMake 早就替我们想好了——cmake --preset 这个命令，就是用来验证和调试预设的。
验证预设的基本命令
我个人习惯，写完预设后第一件事就是跑验证。命令很简单：
# 验证所有预设
cmake --preset --list
# 验证特定预设
cmake --preset debug --check
# 查看预设的完整展开结果
cmake --preset debug --trace这里有个小细节：--list 会列出所有可用的预设，但不会执行任何构建。它只是帮你确认 JSON 文件有没有被正确解析。
核心要点：验证预设不等于执行构建。验证只是检查 JSON 语法和配置逻辑是否正确，不会真的去编译代码。
常见的验证错误与排查
我在项目中遇到过好几次这样的问题：预设写好了，一跑就报错。嗯，这里我总结了几类常见错误：
| 错误类型 | 典型表现 | 排查方法 |
|---|---|---|
| JSON 语法错误 | 缺少逗号、花括号不匹配 | 用 cmake --preset --list 检查 |
| 路径引用错误 | binaryDir 或 sourceDir 不存在 | 使用绝对路径测试，确认后再改相对路径 |
| 变量覆盖冲突 | cacheVariables 中同名变量被多次定义 | 用 --trace 查看变量最终值 |
| 继承链断裂 | 子预设引用了不存在的父预设 | 检查 inherits 字段的拼写 |
说白了，大部分错误都是手误。但有一个坑特别容易踩——路径问题。我曾经因为 binaryDir 写了个相对路径，结果在不同机器上构建目录跑到了奇怪的地方。后来我养成了习惯：先用绝对路径验证一遍，确认逻辑没问题再改回相对路径。
注意：CMake Presets 中的路径是相对于 CMakePresets.json 文件所在目录的。如果你把 JSON 文件放在项目根目录，那路径就从根目录开始算。这个规则很容易被忽略。
使用 --trace 进行深度调试
有时候光看错误信息不够，你想知道 CMake 到底是怎么解析你的预设的。这时候 --trace 就派上用场了。
# 开启 trace 模式
cmake --preset debug --trace
# 只追踪预设相关的信息
cmake --preset debug --trace-source="CMakePresets.json"trace 模式会输出 CMake 内部执行的每一步。我一般用它来检查：
- 变量是否被正确展开
- 条件判断是否按预期执行
- 继承链中的变量覆盖顺序
举个例子，假设你有一个预设定义了 CMAKE_BUILD_TYPE=Debug，但实际构建时发现它变成了 Release。用 trace 一看，原来是某个继承的父预设把值覆盖了。这种问题，光看 JSON 文件很难发现。
验证预设的完整流程
我建议你按照这个流程来验证预设：
- 语法检查：
cmake --preset --list，确认 JSON 能被正确解析 - 配置验证：
cmake --preset <name> --check，检查配置逻辑 - 变量展开：
cmake --preset <name> --trace，查看最终变量值 - 实际构建：
cmake --preset <name>，执行一次完整的配置和构建
这个流程我用了很久，基本没出过问题。尤其是第 2 步的 --check，很多人不知道这个选项。它只做配置检查，不会真的去编译，速度很快。
小技巧：如果你在 CI/CD 中使用预设，建议在流水线中加入 cmake --preset --list 这一步。这样一旦 JSON 文件有语法错误，CI 会立刻报错，而不是等到构建阶段才发现。
预设验证的 SVG 流程图
下面这张图展示了预设验证的完整流程，你可以对照着看：
实战：调试一个继承链复杂的预设
我记得有一次，团队里有人写了一个三层继承的预设：
{
"configurePresets": [
{
"name": "base",
"hidden": true,
"cacheVariables": {
"CMAKE_BUILD_TYPE": "Debug",
"CMAKE_CXX_STANDARD": "17"
}
},
{
"name": "debug",
"inherits": "base",
"cacheVariables": {
"CMAKE_BUILD_TYPE": "Debug",
"ENABLE_SANITIZERS": "ON"
}
},
{
"name": "debug-ubsan",
"inherits": "debug",
"cacheVariables": {
"ENABLE_UBSAN": "ON"
}
}
]
}跑 cmake --preset debug-ubsan --trace 后，发现 CMAKE_BUILD_TYPE 被正确继承为 Debug，但 ENABLE_SANITIZERS 却不见了。为什么？
用 trace 一看，原来是 debug-ubsan 预设里没有显式继承 ENABLE_SANITIZERS。虽然它继承了 debug，但 CMake Presets 的继承规则是：子预设只继承父预设中显式定义的变量。如果子预设重新定义了 cacheVariables，父预设的变量会被完全覆盖，而不是合并。
这个坑，我踩过一次后就记住了。解决方案很简单：要么在子预设中显式引用父预设的变量，要么用 inherits 时注意不要重新定义整个 cacheVariables 对象。
经验之谈：调试继承链时，--trace 是你的好朋友。它能让你看到 CMake 内部是如何一步步展开变量的。我每次遇到变量覆盖问题，第一反应就是开 trace。
总结
验证和调试预设，说白了就是三步：语法检查、配置验证、变量展开。别嫌麻烦，这几步花不了几分钟，但能省下后面排查问题的大把时间。
我个人习惯是把验证命令写进项目的 README.md 里，这样新成员接手时也能快速上手。你想想看，如果每个人都能用同样的方式验证预设，团队协作的效率会高很多。