构建工具开发工具CLI【免费下载链接】CMakeMirror of CMake upstream repository项目地址https://gitcode.com/gh_mirrors/cm/CMake点击查看免费下载本指南以 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 校验器拒绝outputbooleantryCompilebooleanfindboolean值得注意的版本线索在 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.cxxexpandedPreset-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.cxxPresetDebugHelper通过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-pkgpkg[,...]与--debug-find-varvar[,...]两个限定版命令行选项见 cmake.1.rst均于 3.23 加入分别限定到指定包名或指定结果变量名——不过它们目前没有对应的 preset 字段只能通过命令行或CMAKE_FIND_DEBUG_MODE变量使用。预设层的debug.find是全局开关输出写到标准错误注意不要将其输出接入需要机器解析的管道。六、总结预设与命令行的一一对应debug 字段类型默认值等价命令行选项引入版本命令行源码落点outputbooleanfalse--debug-output早期即存在cmake.cxxtryCompilebooleanfalse--debug-trycompile日志消息 3.25 增强cmCoreTryCompile.cxxfindbooleanfalse--debug-find3.17cmake.cxxdebug对象是 configure preset 中把调试意图写进配置文件的标准化入口。通过继承机制团队可以把整套调试开关沉淀在共享基预设中按需覆盖配合 schema.json 提供的 JSON SchemaIDE 中还能获得字段级的校验与自动补全。理解debug三个字段与命令行选项的等价关系、以及它们最终如何驱动cmCoreTryCompile、cmFindCommon等底层实现是高效排查 CMake 配置阶段问题的关键一步。赞分享构建工具开发工具CLI【免费下载链接】CMakeMirror of CMake upstream repository项目地址https://gitcode.com/gh_mirrors/cm/CMake点击查看免费下载相关推荐Ladybird 浏览器的 VS Code 开发环境配置CMake Presets、clangd 索引、任务与调试指南Ladybird 浏览器的 VS Code 开发环境配置CMake Presets、clangd 索引、任务与调试指南 本文基于 Ladybird 仓库官方文前端WebAssemblyFIND配置参数详解从基础设置到高级调优FIND配置参数详解从基础设置到高级调优 FINDFramework for Internal Navigation and Discovery是一个高精后端机器学习物联网Frigate 对象检测调试完全指南历史标注回放、Debug Replay 与手动 Dummy Camera 配置Frigate 对象检测调试完全指南历史标注回放、Debug Replay 与手动 Dummy Camera 配置 本指南聚焦 Frigate NVR 中最实人工智能计算机视觉音视频上一篇Slang光线追踪加速结构BVH构建与遍历优化下一篇Voilà安全防护机制保护Jupyter应用的5个关键策略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考