002-cmake预设设置(cmakepreset)

来源：cmake-presets(7) — CMake 4.3.0 文档

---

简介

CMake 3.19 引入预设（Presets）功能，通过 CMakePresets.json 和 CMakeUserPresets.json 两个文件来共享项目的通用配置方式，方便 CI 构建和团队成员使用相同的构建设置。

• CMakePresets.json：项目级构建配置，应提交到版本控制系统。
• CMakeUserPresets.json：开发者个人本地配置，不应提交到版本控制（如加入 .gitignore）。

两个文件格式完全相同，均位于项目根目录，都是可选的。

---

根对象格式

预设文件是以对象为根节点的 JSON 文档，根对象支持以下字段：

字段	类型	必填	说明
version	整数	✅ 必填	JSON 架构版本号
$schema	字符串	可选	JSON Schema 的 URI（版本 8+ 支持）
cmakeMinimumRequired	对象	可选	构建所需的最低 CMake 版本（含 major、minor、patch）
include	字符串数组	可选	要包含的其他文件路径（版本 4+ 支持）
vendor	映射	可选	供应商特定信息（键格式：域名/产品/版本）
configurePresets	数组	可选	配置预设数组（版本 1+）
buildPresets	数组	可选	构建预设数组（版本 2+）
testPresets	数组	可选	测试预设数组（版本 2+）
packagePresets	数组	可选	打包预设数组（版本 6+）
workflowPresets	数组	可选	工作流预设数组（版本 6+）
$comment	字符串/数组	可选	JSON 注释（版本 10+ 支持，可在任意层级使用）

---

包含（Includes）

从版本 4 开始，CMakePresets.json 和 CMakeUserPresets.json 可通过 include 字段包含其他文件。

• 隐式包含：若两个文件同时存在，CMakeUserPresets.json 在所有格式版本中隐式包含 CMakePresets.json。
• 继承规则：若预设继承自另一文件中的预设，则必须直接或间接包含该文件。
• 循环禁止：不允许包含循环（如 a.json 包含 b.json，则 b.json 不能包含 a.json），但同一文件可被多次包含。
• 宏展开支持：版本 7+ 支持 $penv{} 宏；版本 9+ 支持更多宏展开（$env{} 和预设特定宏除外）。

---

配置预设（Configure Preset）

用于 cmake --preset 命令。每个配置预设是一个 JSON 对象，包含以下字段：

通用字段

字段	类型	说明
name	字符串（必填）	预设的机器标识符，同一目录下不可重名
hidden	布尔值	隐藏预设，不可直接使用，仅供继承
inherits	字符串/字符串数组	继承的预设名称列表（靠前者优先）
condition	对象	启用条件（版本 3+）
vendor	映射	供应商特定信息
displayName	字符串	人类友好的预设名称
description	字符串	人类友好的描述

构建配置字段

字段	类型	说明
generator	字符串	生成器名称（版本 3+ 可选，支持回退到常规发现）
architecture	字符串/对象	目标平台架构（支持 value + strategy 对象形式）
toolset	字符串/对象	工具集（支持 value + strategy 对象形式）
toolchainFile	字符串	工具链文件路径（版本 3+，支持宏展开）
binaryDir	字符串	二进制输出目录（版本 3+ 可选，支持宏展开）
installDir	字符串	安装目录，对应 CMAKE_INSTALL_PREFIX（版本 3+，支持宏展开）
cmakeExecutable	字符串	CMake 可执行文件路径（仅供 IDE 使用）
graphviz	字符串	Graphviz 依赖关系图输出路径（版本 10+，支持宏展开）

architecture/toolset 的 strategy 值："set"（默认，设置值）| "external"（CMake 忽略，供 IDE 使用）。

缓存变量与环境

字段	类型	说明
cacheVariables	映射	缓存变量。值可为 null、布尔值、字符串或 {type, value} 对象。支持宏展开
environment	映射	环境变量。值可为 null 或字符串。支持宏展开和 $penv{} 引用父环境

警告与错误控制

• warnings：对象，包含 dev、deprecated、uninitialized、unusedCli、systemVars（均为布尔值）。
• errors：对象，包含 dev、deprecated（均为布尔值）。

调试选项

• debug：对象，包含 output、tryCompile、find（均为布尔值）。

追踪选项（版本 7+）

• trace：对象，包含：
  • mode："on" | "off" | "expand"
  • format："human" | "json-v1"
  • source：字符串数组，要追踪的源文件
  • redirect：追踪输出文件路径

---

构建预设（Build Preset）

用于 cmake --build --preset 命令。除通用字段外，特有字段如下：

字段	类型	说明
configurePreset	字符串	关联的配置预设名称
inheritConfigureEnvironment	布尔值	是否继承配置预设的环境变量（默认 true）
jobs	整数	并行构建任务数（等同于 --parallel，版本 4.3 起不接受负数）
targets	字符串/字符串数组	构建目标（等同于 --target，支持宏展开）
configuration	字符串	构建配置（等同于 --config）
cleanFirst	布尔值	是否先清理（等同于 --clean-first）
resolvePackageReferences	字符串	包引用解析模式："on"
verbose	布尔值	是否详细输出（等同于 --verbose）
nativeToolOptions	字符串数组	原生工具选项（等同于 -- 之后的参数，支持宏展开）
environment	映射	环境变量（同配置预设）

⚠️ ExternalProject 注意：若使用 ExternalProject 且配置预设中设置了环境变量（如 CC/CXX），构建预设应继承该配置预设，否则 ExternalProject 可能使用系统默认编译器。

---

测试预设（Test Preset）

用于 ctest --preset 命令。除通用字段外，特有字段如下：

基础字段

字段	类型	说明
configurePreset	字符串	关联的配置预设名称
inheritConfigureEnvironment	布尔值	是否继承配置预设的环境变量（默认 true）
configuration	字符串	构建配置（等同于 --build-config）
overwriteConfigurationFile	字符串数组	覆盖 CTest 配置文件选项（支持宏展开）

输出控制

output 对象包含：

字段	类型	说明
shortProgress	布尔值	简短进度（--progress）
verbosity	字符串	详细程度："default"
debug	布尔值	调试模式（--debug）
outputOnFailure	布尔值	失败时输出（--output-on-failure）
quiet	布尔值	安静模式（--quiet）
outputLogFile	字符串	日志文件路径（--output-log，支持宏展开）
outputJUnitFile	字符串	JUnit 文件路径（版本 6+，支持宏展开）
labelSummary	布尔值	标签摘要（--no-label-summary）
subprojectSummary	布尔值	子项目摘要（--no-subproject-summary）
maxPassedTestOutputSize	整数	通过测试最大输出字节
maxFailedTestOutputSize	整数	失败测试最大输出字节
testOutputTruncation	字符串	输出截断模式（版本 5+）
maxTestNameWidth	整数	测试名称最大宽度（--max-width）

过滤控制

filter 对象包含 include 和 exclude 子对象：

• include：name（正则）、label（正则）、useUnion（布尔值）、index（{start, end, stride, specificTests}）
• exclude：name（正则）、label（正则）、fixtures（{any, setup, cleanup} 正则）

执行控制

execution 对象包含：

字段	类型	说明
stopOnFailure	布尔值	--stop-on-failure
enableFailover	布尔值	-F
jobs	整数/字符串	并行任务数（--parallel），版本 11+ 支持空字符串
resourceSpecFile	字符串	资源规格文件（支持宏展开）
testLoad	整数	--test-load
showOnly	字符串	"human"
repeat	对象	{mode: "until-fail"/"until-pass"/"after-timeout", count: 整数}
interactiveDebugging	布尔值	--interactive-debug-mode
scheduleRandom	布尔值	--schedule-random
timeout	整数	--timeout
noTestsAction	字符串	"default"

---

打包预设（Package Preset）

用于 cpack --preset 命令（版本 6+）。除通用字段外，特有字段：

字段	类型	说明
configurePreset	字符串	关联的配置预设名称
inheritConfigureEnvironment	布尔值	是否继承配置预设环境变量（默认 true）
generators	字符串数组	CPack 生成器列表
configurations	字符串数组	要打包的构建配置列表
variables	映射	传递给 CPack 的变量（等同于 -D）
configFile	字符串	CPack 配置文件路径
output	对象	{debug, verbose}（布尔值）
packageName	字符串	⚠️ 注意：不影响最终包文件名，建议暂不使用
packageVersion	字符串	⚠️ 注意：不影响最终包文件名，建议暂不使用
packageDirectory	字符串	包输出目录
vendorName	字符串	供应商名称

---

工作流预设（Workflow Preset）

用于 cmake --workflow --preset 命令（版本 6+），将多个预设串联为流水线。

• steps（必填数组）：第一步必须是 type: "configure"，后续可为 "build"、"test"、"package"。每个步骤含 type 和 name（对应的预设名称）。
• 所有后续步骤的 configurePreset 必须与起始配置预设匹配。

---

条件（Condition）

版本 3+ 支持，用于判断预设是否启用。condition 可为布尔值、null 或对象。对象 type 支持以下类型：

类型	说明	附加字段
"const"	常量条件	value（布尔值）
"equals"	字符串相等比较	lhs、rhs（支持宏展开）
"notEquals"	字符串不等比较	lhs、rhs（支持宏展开）
"inList"	在列表中搜索	string、list（支持宏展开，短路求值）
"notInList"	不在列表中	string、list
"matches"	正则匹配	string、regex（支持宏展开）
"notMatches"	正则不匹配	string、regex
"anyOf"	任意条件满足	conditions（条件数组，短路求值）
"allOf"	所有条件满足	conditions（条件数组，短路求值）
"not"	条件取反	condition（嵌套条件对象）

---

宏展开（Macro Expansion）

预设中某些字段支持宏展开，格式为 $<namespace>{<name>}。

注意：后跟非 { 字符的 $ 会被视为字面量美元符号。

内置宏

宏	说明	最低版本
${sourceDir}	项目源代码目录（同 CMAKE_SOURCE_DIR）	1
${sourceParentDir}	源码目录的父目录	1
${sourceDirName}	源码目录的最后一级目录名	1
${presetName}	当前预设的 name 字段值 *	1
${generator}	当前预设的生成器 *	1
${hostSystemName}	主机操作系统名称	3
${fileDir}	包含该宏的预设文件所在目录	4
${dollar}	字面量美元符号 $	1
${pathListSep}	路径列表分隔符（如 : 或 ;）	5

* 标记为预设特定宏，在 include 字段中不可用。

环境变量宏

宏	说明
$env{<var>}	环境变量值（优先取 environment 字段中的值，未定义则为空串）
$penv{<var>}	仅从父环境取值（不从 environment 字段取），可用于向现有变量追加值

⚠️ Windows 环境变量名不区分大小写，但预设中变量名区分大小写，建议保持一致。

供应商宏

$vendor{<macro-name>}：留给 IDE 厂商的自定义宏扩展点。CMake 会忽略含此宏的预设。建议厂商使用简短前缀（≤4 字符），如 $vendor{xide.ideInstallDir}。

---

版本历史

版本	CMake 版本	主要变更
1	3.19	初始版本：配置预设 + 宏展开
2	3.20	新增构建预设、测试预设
3	3.21	新增条件对象；installDir、toolchainFile；binaryDir/generator 变可选；新增 ${hostSystemName}
4	3.23	新增 include 包含机制；resolvePackageReferences；新增 ${fileDir}
5	3.24	testOutputTruncation；新增 ${pathListSep}
6	3.25	新增打包预设、工作流预设；outputJUnitFile
7	3.27	新增 trace 字段；include 支持 $penv{}
8	3.28	新增 $schema 字段
9	3.30	include 支持更多宏展开
10	3.31	新增 $comment 注释支持；新增 graphviz
11	4.3	测试预设 jobs 支持空字符串

---

完整示例

{
  "version": 10,
  "cmakeMinimumRequired": {
    "major": 3,
    "minor": 23,
    "patch": 0
  },
  "$comment": "An example CMakePresets.json file",
  "include": [
    "otherThings.json",
    "moreThings.json"
  ],
  "configurePresets": [
    {
      "name": "default",
      "displayName": "Default Config",
      "description": "Default build using Ninja generator",
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/build/default",
      "cacheVariables": {
        "FIRST_CACHE_VARIABLE": { "type": "BOOL", "value": "OFF" },
        "SECOND_CACHE_VARIABLE": "ON"
      },
      "environment": {
        "MY_ENVIRONMENT_VARIABLE": "Test",
        "PATH": "$env{HOME}/ninja/bin:$penv{PATH}"
      },
      "vendor": {
        "example.com/ExampleIDE/1.0": {
          "autoFormat": true
        }
      }
    },
    {
      "name": "ninja-multi",
      "inherits": "default",
      "displayName": "Ninja Multi-Config",
      "generator": "Ninja Multi-Config"
    },
    {
      "name": "windows-only",
      "inherits": "default",
      "displayName": "Windows-only configuration",
      "condition": {
        "type": "equals",
        "lhs": "${hostSystemName}",
        "rhs": "Windows"
      }
    }
  ],
  "buildPresets": [
    {
      "name": "default",
      "configurePreset": "default"
    }
  ],
  "testPresets": [
    {
      "name": "default",
      "configurePreset": "default",
      "output": { "outputOnFailure": true },
      "execution": { "noTestsAction": "error", "stopOnFailure": true }
    }
  ],
  "packagePresets": [
    {
      "name": "default",
      "configurePreset": "default",
      "generators": ["TGZ"]
    }
  ],
  "workflowPresets": [
    {
      "name": "default",
      "steps": [
        { "type": "configure", "name": "default" },
        { "type": "build", "name": "default" },
        { "type": "test", "name": "default" },
        { "type": "package", "name": "default" }
      ]
    }
  ],
  "vendor": {
    "example.com/ExampleIDE/1.0": {
      "autoFormat": false
    }
  }
}