企业官网建设流程全解析

• 构建工具
• 开发工具
• CLI

本指南以 CMake 仓库中的 debug-properties.rst 为核心，系统讲解CMakePresets.json中configurePresets[].debug对象的三个布尔字段——output、tryCompile、find——各自的语义、与命令行选项的等价关系、继承规则以及底层解析与执行机制。读完本文，你将能在不修改 CMakeLists.txt 的前提下，仅通过预设文件一键开启 CMake 运行时诊断、保留 try_compile 临时文件、以及追踪 find 系列命令的搜索过程，并与cmake --debug-output、--debug-trycompile、--debug-find等命令行用法自如互换。

一、debug 对象在 configurePresets 中的位置

在 CMake 的预设（Presets）体系中，configurePresets数组中的每个元素都可以携带一个可选的debug对象，用于集中指定调试选项。在 configurePresets-properties.rst 中，该字段被定义为：

debug—— An optional object specifying debug options. The object may contain the following fields.

从仓库中的 schema.yaml 看，debug的类型约束为object，其unevaluatedProperties为false，即只允许出现下文约定的三个字段，出现任何未知键都会被 JSON Schema 校验器拒绝：

• output（boolean）
• tryCompile（boolean）
• find（boolean）

值得注意的版本线索：在 schema.yaml 中，与同级的trace（标注since: 7）不同，debug对象没有since标注。从源码结构看，这意味着它是 configure preset 自 schema v1 起便存在的早期字段，几乎所有支持 Presets 的 CMake 版本都能识别它。与之形成对比的是，trace、condition、toolchainFile等字段分别有明确的版本引入标记。

二、三个字段逐一拆解：语义、命令行等价与源码实现

debug对象中的每一个字段都是可选的布尔值，设置true与在命令行中传递对应的开关等价。下面分别展开。

2.1 debug.output —— 等价于 --debug-output

语义：可选的布尔值。设置为true等价于在命令行传入--debug-output。

--debug-output在 cmake.1.rst 中的完整定义是：

Put cmake in a debug mode. Print extra information during the cmake run like stack traces withmessage(SEND_ERROR)calls.

也就是说，开启后 CMake 在运行期间会输出额外的诊断信息，包括message(SEND_ERROR)调用时的堆栈轨迹（stack trace），用于追踪错误产生的调用链。

源码证据：在 cmake.cxx 中，命令行参数--debug-output被解析后调用state->SetDebugOutputOn(true)；而在应用预设时，cmake.cxx 中expandedPreset->DebugOutput == true会调用同一个SetDebugOutputOn(true)。两条路径殊途同归，验证了"预设字段 == 命令行选项"的等价关系。

该标志在运行期如何发挥作用？从 cmMakefile.cxx 与 cmMakefile.cxx 看，GetDebugOutput()被用于决定是否打印额外的调试消息（例如文件加载、配置相关日志）；在 cmFileCommand.cxx 中，cm->GetDebugOutput() || cm->GetTrace()的组合还控制着file()命令相关操作的额外输出。此外，CMakeSetupDialog.cxx 与 QCMake.cxx 表明 CMake GUI 也提供对应的开关，最终同样落到cmake实例的SetDebugOutputOn。

2.2 debug.tryCompile —— 等价于 --debug-trycompile

语义：可选的布尔值。设置为true等价于在命令行传入--debug-trycompile。

--debug-trycompile在 cmake.1.rst 中的完整定义如下：

Do not delete the files and directories created fortry_compile/try_runcalls. This is useful in debugging failed checks. Note that some uses oftry_compilemay use the same build tree, which will limit the usefulness of this option if a project executes more than onetry_compile. For example, such uses may change results as artifacts from a previous try-compile may cause a different test to either pass or fail incorrectly. This option is best used only when debugging. (With respect to the preceding, thetry_runcommand is effectively atry_compile. Any combination of the two is subject to the potential issues described.)versionadded:: 3.25— When this option is enabled, every try-compile check prints a log message reporting the directory in which the check is performed.

源码证据：命令行解析位于 cmake.cxx（调用DebugTryCompileOn()）；预设应用位于 cmake.cxx（expandedPreset->DebugTryCompile == true时同样调用DebugTryCompileOn()）。实际消费该标志的是 try-compile 的核心实现 cmCoreTryCompile.cxx：当GetDebugTryCompile()为真时，为try_compile/try_run创建的目录与文件不会被清理，方便开发者进入该目录检查编译器实际执行的命令与产物。

实战价值：当check_*系列（如CheckCSourceCompiles、CheckSymbolExists）或项目内显式try_compile失败且难以定位原因时，开启debug.tryCompile即可"冻结现场"。同时注意官方文档的告诫：该选项仅建议在调试时使用，因为多次 try-compile 可能共享同一构建树，遗留产物可能污染后续检查结果，导致假阳性或假阴性。

2.3 debug.find —— 等价于 --debug-find

语义：可选的布尔值。设置为true等价于在命令行传入--debug-find。

--debug-find在 cmake.1.rst 中的完整定义如下：

Put cmake find commands in a debug mode. Print extra find call information during the cmake run to standard error. Output is designed for human consumption and not for parsing. See also theCMAKE_FIND_DEBUG_MODEvariable for debugging a more local part of the project.

版本信息：--debug-find在 CMake 3.17 加入（文档标注versionadded:: 3.17）。

源码证据：命令行解析位于 cmake.cxx（调用SetDebugFindOutput(true)）；预设应用位于 cmake.cxx。在 find 命令的公共实现 cmFindCommon.cxx 中，GetDebugFindPkgMode() || ...之类的条件驱动 find 调试输出的开关；cmMakefile.cxx 中还有一个DebugFindPkgRAII辅助类，在进入find_package(<pkg>)调用时根据包的名称临时切换调试模式，退出时恢复旧值，从而实现"只调试指定包"的局部化能力。

实战价值：当find_package、find_library、find_path、find_program、find_file等找不到目标、或找到了错误版本时，开启debug.find会把每个 find 调用的搜索路径、命中/未命中的判定过程输出到标准错误（stderr），输出面向人类阅读而非机器解析。若只想调试项目中的局部区域，官方还提供了CMAKE_FIND_DEBUG_MODE变量作为更细粒度的替代。

三、三个调试字段的继承与合并规则

debug对象遵循 configure preset 的通用inherits继承机制。在 cmCMakePresetsGraph.cxx 中，展开预设时对这三个字段分别执行了InheritOptionalValue(preset.DebugOutput, parent.DebugOutput)等调用——注意它们是逐字段独立继承的：

• 若子预设未显式设置某字段，则继承父预设（inherits链上）对应字段的值；
• 若子预设显式设置，则以子预设为准；
• 多个父预设提供冲突值时，inherits数组靠前的预设优先（该规则在 configurePresets-properties.rst 中有明确定义）。

这意味着你可以把公共的调试开关放在一个"hidden": true的基预设中，再让具体配置预设继承它，无需在每个预设里重复书写。字段解析层面的对应证据在 cmCMakePresetsGraphReadJSONConfigurePresets.cxx：PresetDebugHelper通过Bind("output"_s, ...)、Bind("tryCompile"_s, ...)、Bind("find"_s, ...)将 JSON 键绑定到ConfigurePreset::DebugOutput、DebugTryCompile、DebugFind三个可选布尔成员（类型定义见 cmCMakePresetsGraph.h），并且三个键均允许缺省（最后一个false参数表示非必需键）。随后该 Helper 被整体绑定到"debug"键下（cmCMakePresetsGraphReadJSONConfigurePresets.cxx）。

四、完整可运行的配置示例

下面的示例在 example.json 的骨架之上加入debug对象，展示三种常见形态。将以下内容写入项目根目录的CMakePresets.json后，执行cmake --preset debug-on即可同时获得三路诊断输出。

{ "version": 10, "configurePresets": [ { "name": "base", "hidden": true, "generator": "Ninja", "binaryDir": "${sourceDir}/build/${presetName}", "debug": { "output": true, "tryCompile": true, "find": true } }, { "name": "debug-on", "inherits": "base", "displayName": "全量调试配置", "description": "开启 output/tryCompile/find 全部调试开关" }, { "name": "find-only", "inherits": "base", "displayName": "仅追踪 find 命令", "description": "关闭前两项，仅保留 find 调试", "debug": { "output": false, "tryCompile": false } } ] }

要点说明：

• debug-on完全继承base的三个开关，等价于执行cmake --debug-output --debug-trycompile --debug-find --preset debug-on（未显式指定的generator、binaryDir同样继承自base）。
• find-only在继承基础上显式将output、tryCompile置为false进行覆盖，最终仅保留find: true。
• 由于三个字段均为可选，即使完全不写debug对象，预设也完全合法——调试开关默认关闭，与命令行不传对应参数的行为一致。

五、调试策略与注意事项

5.1 何时使用 debug.output

当message(SEND_ERROR)触发、或需要理解 CMake 配置阶段的内部运行轨迹时开启。它与--trace（对应trace预设对象，见 schema.yaml）的区别在于：debug.output输出的是运行诊断与堆栈信息，而trace输出的是所有命令调用的调用轨迹。二者可以组合使用，各自侧重不同。

5.2 何时使用 debug.tryCompile

针对try_compile/try_run检查失败时开启。开启后每次检查还会额外打印一条日志，报告检查发生在哪个目录（该行为在 cmake.1.rst 中标注为 3.25 引入）。调试完成后务必关闭，因为遗留的构建产物可能干扰后续检查的判定结果。

5.3 何时使用 debug.find 及其局限

针对find_*系列命令找不到或找错目标时开启。若想进一步缩小范围，CMake 还提供--debug-find-pkg=<pkg>[,...]与--debug-find-var=<var>[,...]两个限定版命令行选项（见 cmake.1.rst，均于 3.23 加入），分别限定到指定包名或指定结果变量名——不过它们目前没有对应的 preset 字段，只能通过命令行或CMAKE_FIND_DEBUG_MODE变量使用。预设层的debug.find是全局开关，输出写到标准错误，注意不要将其输出接入需要机器解析的管道。

六、总结：预设与命令行的一一对应

debug对象是 configure preset 中"把调试意图写进配置文件"的标准化入口。通过继承机制，团队可以把整套调试开关沉淀在共享基预设中，按需覆盖；配合 schema.json 提供的 JSON Schema，IDE 中还能获得字段级的校验与自动补全。理解debug三个字段与命令行选项的等价关系、以及它们最终如何驱动cmCoreTryCompile、cmFindCommon等底层实现，是高效排查 CMake 配置阶段问题的关键一步。

• 构建工具
• 开发工具
• CLI