构建工具开发工具CLI【免费下载链接】CMakeMirror of CMake upstream repository项目地址https://gitcode.com/gh_mirrors/cm/CMake点击查看免费下载CMake 为集成开发环境IDE提供了官方推荐的集成最佳实践覆盖捆绑分发、Presets 解析、配置/构建/测试全流程对接等关键环节。本文将基于 CMake 官方IDE Integration GuideHelp/guide/ide-integration/index.rst展开并结合仓库中的源码、手册与 JSON Schema帮助你掌握一套既尊重 CMake 向后兼容承诺、又充分利用CMakePresets.json、File API 与 CTest JSON 输出等现代化机制的可落地方案。适用对象IDE/插件/工具链开发者以及希望在 CI 或自定义工具中深度对接 CMake 的工程团队。文中所有命令、配置与 JSON 结构均以本仓库CMake 源码树中对应文档与源码为准。一、整体集成策略三条核心原则原文开篇即给出 IDE 集成的宏观建议可归纳为三条原则使用最新版 CMakeCMake 有很强的向后兼容保证项目要求的旧版本 CMake 完全可以由更新的版本来替代因此捆绑时应选用发布时刻可用的最新 patch 版本而不是为不同项目捆绑不同版本。用 CMake 官方机制代替 DIY解析 Presets 用 CMake 同款逻辑、获取产物信息用 File API、构建用cmake --build、测试用ctest直连而不是绕过它们。避免制造不必要的构建树仅在切换编译器、编译选项等真正需要时才创建多个构建树单配置多构建树的伪多配置做法被明确禁止。下面依次展开每条原则背后的实现细节。二、Bundling捆绑 CMake 与 Ninja 的版本策略对于希望随 IDE 分发 CMake 的厂商官方建议始终捆绑最新 patch 版本的 CMake。CMake 提供强向后兼容保证使用比项目要求更新的版本没有理由不可行因此没有必要为了适配某个项目而捆绑旧版本更不建议同一应用内捆绑多个不同版本。允许用户切换外部 CMake捆绑版可能过时IDE 应提供使用外部安装的 CMake 替代捆绑版的选项。Ninja 捆绑建议Ninja 在所有支持 CMake 的平台上性能高、支持好建议随 IDE 一并分发并且应使用Ninja 1.10 或更新版本——该版本包含支持 Fortran 构建所需的功能。Ninja 1.10 之所以重要是因为它引入了对 Fortran 模块依赖等特性的支持参见 Help/manual/cmake-generators.7.rst 中关于 Ninja 生成器的说明以及 Modules/FortranCInterface 相关工具链对 Fortran 的支持。三、PresetsIDE 应计算而不是转交--presetCMakePresets.json与CMakeUserPresets.json是 CMake 官方支持的预设文件格式详见 cmake-presets(7) 手册与机器可读的 presets/schema.json。官方对 IDE 的明确要求是IDE 应像 CMake 一样读取和评估这些文件把其中的预设展示给用户用户应能看到并可能编辑某预设定义的cache 变量、环境变量与命令行选项IDE 应根据这些设置自行构造cmake命令行参数而不是直接调用--preset选项——--preset只是面向命令行用户的便捷前端不应被 IDE 使用。3.1 官方示例从--preset到展开后的命令原文给出的对比非常直观。假设存在一个名为ninja的 configure preset指定生成器为Ninja、构建目录为${sourceDir}/build# 命令行用户可以直接这样用IDE 不应这样做 cmake -S /path/to/source --presetninja # IDE 应该计算预设的设置后运行展开后的等价命令 cmake -S /path/to/source -B /path/to/source/build -G Ninja3.2 长命令行兜底临时 cache 脚本当预设包含大量 cache 变量、全部转成-D标志会超过平台命令行长度限制时IDE 应构造一个临时 cache 脚本并通过-C标志传递cmake -S /path/to/source -B /path/to/source/build -G Ninja -C /tmp/generated-cache-script.cmake这正好利用了cmake -C选项预加载 cache 脚本的能力。3.3 预设文件格式要点与 IDE 解析直接相关结合 cmake-presets(7) 与 example.jsonIDE 解析器需要重点处理以下结构根对象字段见 root-properties.rst字段说明version必填整数指定 JSON schema 版本当前示例为 10$schema可选指向 JSON schema 的 URI供编辑器校验与补全cmakeMinimumRequired可选构建此项目所需的最低 CMake 版本include可选字符串数组包含其他预设文件版本 4configurePresets/buildPresets/testPresets/packagePresets/workflowPresets各类预设数组vendor厂商自定义信息CMake 只校验其是否为 mapconfigure preset 关键字段见 configurePresets-properties.rstname机器友好名用于--preset同一目录下CMakePresets.json与CMakeUserPresets.json合并后不得重名hidden隐藏预设不能作为--preset参数、不出现在 CMake GUI 中且无需有效generator/binaryDir专供其他预设通过inherits继承作基类inherits可继承其他预设的所有字段name、hidden、inherits、description、displayName除外多父预设冲突时数组靠前者优先generator、architecture、toolset生成器及其平台/工具集对应-G/-A/-T注意 Visual Studio 生成器名中不能夹带平台名须用architecture字段toolchainFile工具链文件路径支持宏展开相对路径先相对构建目录再相对源码目录计算binaryDir/installDir构建目录与安装目录对应CMAKE_INSTALL_PREFIXcacheVariablescache 变量 map值可为null、布尔、字符串或带type/value的对象继承规则是并集设为null可取消继承值environment环境变量 map支持宏展开与变量间引用但不能成环$penv{NAME}可访问父环境做前后缀拼接warnings/errors/debug/trace诊断与调试选项。宏展开$namespace{name}形式是解析器必须实现的包括${sourceDir}、${sourceParentDir}、${sourceDirName}、${presetName}、${generator}、${hostSystemName}、${fileDir}、${dollar}、${pathListSep}、$env{NAME}、$penv{NAME}以及厂商扩展点$vendor{macro-name}CMake 不解释、IDE 厂商应加 ≤4 字符前缀防冲突如$vendor{xide.ideInstallDir}。宏在被使用的预设上下文中求值${fileDir}自版本 12 起改为在当前文件上下文求值。条件对象condition版本 3值为布尔、null或对象对象类型包括const、equals/notEquals、inList/notInList、matches/notMatches、anyOf/allOf、not可据此按平台禁用预设如${hostSystemName}等于Windows才启用。3.4 源码级提示解析并不 trivial原文特别提醒读取、解析、评估预设文件虽直接但非琐碎IDE 厂商可参考 CMake 源码与测试用例。仓库中可佐证的材料包括预设解析/校验的 C 实现cmCMakePresetsGraphReadJSON.cxx、cmCMakePresetsGraphReadJSONConfigurePresets.cxx、cmCMakePresetsGraphResolve.cxx预设错误处理cmCMakePresetsErrors.cxx机器可读 JSON Schemapresets/schema.jsonIDE 可用于校验与编辑辅助其 YAML 源为 presets/schema.yaml。四、Configuring用 File API 获取语义化构建信息4.1 为什么用 File API 而不是 Server 模式IDE 调用cmake执行 configure 步骤时可通过File APIcmake-file-api(7)获得构建产物、include 目录、编译定义等语义信息Server 模式cmake-server(7)自 CMake 3.20 起被移除在 CMake 3.14 及之后不应再使用。4.2 File API 工作流File API 基于构建树顶部的build/.cmake/api/目录当前仅支持 API v1位于build/.cmake/api/v1/客户端在query/写入查询文件请求零个或多个 Object KindCMake 生成构建系统时读取查询文件在reply/写入回复文件客户端必须首先读取回复索引index-*.json再按其中引用读取具体回复文件回复文件名不确定不允许客户端自行推断。查询文件有三种形态以codemodel为例# 1. 共享无状态查询不归属任何客户端不要随意删除 build/.cmake/api/v1/query/codemodel-v2 # 2. 客户端无状态查询归 client 所有可随时删除 build/.cmake/api/v1/query/client-client/codemodel-v2 # 3. 客户端有状态查询query.json按版本协商只取最新 build/.cmake/api/v1/query/client-client/query.json有状态查询query.json的内容示例CMake 会为每个请求选择它能识别的第一个版本并对所选 major 使用已知的最高 minor{ requests: [ { kind: codemodel, version: 1 }, { kind: codemodel, version: { major: 1, minor: 2 } }, { kind: codemodel, version: [2, { major: 1, minor: 2 }] }, { kind: codemodel, version: 1, client: {} } ], client: {} }CMake 3.27 起还可用cmake_file_api命令提交当前运行的查询见 cmake_file_api。用户级查询可通过 CMAKE_CONFIG_DIR 环境变量下的api/v1/query目录CMake 3.31为所有项目生效。4.3 回复索引与回复文件结构回复索引index-*.json的顶层结构简化{ cmake: { version: { major: 3, minor: 14, patch: 0, suffix: , string: 3.14.0, isDirty: false }, paths: { cmake: /prefix/bin/cmake, ctest: /prefix/bin/ctest, cpack: /prefix/bin/cpack, root: /prefix/share/cmake-3.14 }, generator: { multiConfig: false, name: Unix Makefiles } }, objects: [ { kind: codemodel, version: { major: 1, minor: 0 }, jsonFile: file } ], reply: { codemodel-v1: { kind: codemodel, version: { major: 1, minor: 0 }, jsonFile: file }, client-client: { query.json: { requests: [], responses: [ { kind: codemodel, version: { major: 1, minor: 0 }, jsonFile: file } ], client: {} } } } }回复文件含索引永远不会被同名不同内容的文件替换因此客户端可与正在生成新回复的 CMake 并发读取若引用的文件缺失说明并发 CMake 已生成新回复客户端重新读取新的索引即可。CMake 4.1 起生成失败时还会写error-*.json错误索引其中只提供configureLog等部分 Object Kind其余以error消息占位。4.4 Object KindcodemodelFile API 的 Object Kind 各自独立进行语义化版本管理。最核心的是codemodel无 version 1以避免与已移除的 server 模式混淆当前为 version 2。其顶层结构{ kind: codemodel, version: { major: 2, minor: 8 }, paths: { source: /path/to/top-level-source-dir, build: /path/to/top-level-build-dir }, configurations: [ { name: Debug, directories: [ { source: ., build: ., childIndexes: [ 1 ], projectIndex: 0, targetIndexes: [ 0 ], hasInstallRule: true, minimumCMakeVersion: { string: 3.14 }, jsonFile: file } ], projects: [ { name: MyProject, directoryIndexes: [ 0, 1 ], targetIndexes: [ 0, 1 ] } ], targets: [ { name: MyExecutable, directoryIndex: 0, projectIndex: 0, jsonFile: file } ], abstractTargets: [ { name: MyImportedExecutable, directoryIndex: 1, projectIndex: 0, jsonFile: file } ] } ] }关键成员configurations单配置生成器只有CMAKE_BUILD_TYPE对应的一项多配置生成器为CMAKE_CONFIGURATION_TYPES每项一条directories每个含CMakeLists.txt的构建目录一项含source/build路径、parentIndex/childIndexes树结构、projectIndex、targetIndexes、hasInstallRule与minimumCMakeVersionprojects顶层项目与子项目由project()命令定义targets真实构建目标add_executable/add_library/add_custom_target产生排除 imported 与不产生构建规则的 interface 库abstractTargets2.9imported 目标与无源码的 interface 库等不在构建系统中的目标不可被构建不应作为可构建目标展示给用户。通过jsonFile可继续引用更细粒度的directory对象含 installers 列表file/directory/target/export/script/code等类型与target对象含type、nameOnDisk、artifacts、sources、compileGroups、dependencies、link/archive片段等。从源码实现看回复数据由 cmFileApiCodemodel.cxx 等生成其机器可读描述见 file_api/schema_codemodel.json、schema_target.json、schema_directory.json。4.5 构建树纪律与额外生成器禁令不要创建仅CMAKE_BUILD_TYPE不同的多个单配置构建树来模拟多配置环境应改用Ninja Multi-Config生成器generator配合 File API 获取配置列表不要对 Makefile/Ninja 生成器使用额外生成器extra generators来生成 IDE 工程文件获取构建产物列表应使用 File API。五、Building用cmake --build而不是直接调 make/ninja对于 Makefile 或 Ninja 生成器不要直接调用make/ninja应调用cmake --build dir由 CMake 转调合适的构建工具若使用 IDE 工程生成器如 Xcode 或 Visual Studio 生成器且 IDE 本身理解该工程格式则按常规方式读取工程文件并构建即可构建配置列表仍通过 File API 从构建树获取IDE 应将该列表展示给用户选择。示例cmake --build /path/to/source/build --config Debug --target MyExecutable六、Testing直接调 ctest用 JSON 输出枚举测试ctest支持输出包含可用测试与测试配置信息的 JSON 格式IDE 应获取该信息并向用户呈现测试列表不应调用构建系统的test目标而应直接调用ctest。获取测试清单的典型命令-N/--show-only不实际运行测试ctest --test-dir /path/to/source/build --show-onlyjson-v1--show-onlyjson-v1输出的 JSON 对象模型见 ctest(1)包含kind字符串ctestInfoversionmajor/minor版本组件backtraceGraphcommands/files/nodes组成的回溯图tests测试数组每项含name测试名不可为空、config与-C选项对应的配置、command测试命令与参数、backtrace、properties测试属性列表。CMake 4.1 起该 JSON 格式还有机器可读描述ctest/show-only-schema.json。运行测试时可配合ctest --test-dir dir --output-on-failure等选项测试预设testPresets可统一管理output.outputOnFailure、execution.stopOnFailure、execution.jobs等行为见 testPresets-properties.rst 与 example.json。七、生态盘点原生支持与内置生成器原文将生态分为两类原生支持 CMake 的 IDE通过插件或内置支持CLion、KDevelop、Qt Creator、Vim插件、Visual Studio、VS Code插件。CMake 内置的 IDE 支持IDE Build Tool Generators直接生成 IDE 原生构建系统如 Visual Studio 生成器 与 XcodeExtra Generators在命令行构建工具生成器之上扩展、生成可挂接的 IDE 工程文件但已被 File API 取代。这一演进路径印证了全文的核心判断File API 是当前与未来 IDE 集成的事实标准extra generators 与 server 模式均已让位于它。八、IDE 集成的推荐落地清单捆绑最新 patch 版 CMake可选捆绑 Ninja ≥ 1.10并提供外部 CMake 切换选项像 CMake 一样解析CMakePresets.json/CMakeUserPresets.json参考 presets/schema.json 与解析源码 cmCMakePresetsGraphReadJSON.cxx向用户展示预设与 cache/环境变量将预设展开为显式cmake参数-S/-B/-G/-D/-A/-T等超长时用临时 cache 脚本 -C避免直接使用--presetconfigure 阶段通过 File APIbuild/.cmake/api/v1/query/查询、index-*.json索引获取 codemodel 语义信息与产物清单多配置需求用 Ninja Multi-Config File API禁止用多个单配置构建树模拟禁止对 Makefile/Ninja 使用额外生成器构建一律走cmake --build或 IDE 原生工程格式不直接调make/ninja测试用ctest --show-onlyjson-v1枚举、ctest直跑不调用test目标面向 CMake 3.14 一律不再依赖已移除的 server 模式。参考资料仓库内本文主体Help/guide/ide-integration/index.rst预设手册与 Schemacmake-presets(7)、presets/example.json、presets/schema.json、presets/configurePresets-properties.rstFile API 手册与 Schemacmake-file-api(7)、file_api/schema_codemodel.json、file_api/schema_index.json、file_api/schema_stateful_query.jsonCTest JSON 输出ctest(1)、ctest/show-only-schema.json预设解析实现cmCMakePresetsGraphReadJSON.cxx、cmCMakePresetsGraphResolve.cxxFile API 实现cmFileApiCodemodel.cxx赞分享构建工具开发工具CLI【免费下载链接】CMakeMirror of CMake upstream repository项目地址https://gitcode.com/gh_mirrors/cm/CMake点击查看免费下载相关推荐Social Analyzer 使用教程3 分钟找到一个人的 1000 社媒主页Social Analyzer 使用教程3 分钟找到一个人的 1000 社媒主页 把 Social Analyzer 当成你的社媒侦探丢一个用户名给它开发工具构建工具系统编程Kubernetes code-generator 实践指南从官方生成器到 Karmada 多集群 API 代码生成Kubernetes code generator 实践指南从官方生成器到 Karmada 多集群 API 代码生成 Kubernetes 风格的 API 类云原生多集群集群管理微服务mimalloc 的 Vcpkg 集成指南官方 Port、自定义 Overlay 与 CMake 消费实践mimalloc 的 Vcpkg 集成指南官方 Port、自定义 Overlay 与 CMake 消费实践 mimalloc 是一个紧凑、通用且性能出色的内存内存管理系统编程上一篇MAA助手v5.12.0-beta.1架构解密跨平台自动化框架的技术实现与性能优化下一篇Trivy VEX Repository基于 VEX 仓库的漏洞影响判定与抑制实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
