cmake-presets(7)

简介

版本 3.19 中新增。

CMake 用户经常面临的一个问题是如何与他人共享配置项目的常用方式。这可能是为了支持 CI 构建，或者为了经常使用相同构建的用户。CMake 支持两个主要文件，CMakePresets.json 和 CMakeUserPresets.json，它们允许用户指定通用的配置选项并与他人共享。CMake 还支持使用 include 字段包含的文件。

CMakePresets.json 和 CMakeUserPresets.json 位于项目的根目录中。它们都具有完全相同的格式，并且都是可选的（但如果指定了 --preset，则至少必须存在一个）。CMakePresets.json 旨在指定项目范围的构建详细信息，而 CMakeUserPresets.json 旨在供开发人员指定其自己的本地构建详细信息。

CMakePresets.json 可能会被检入到版本控制系统，而 CMakeUserPresets.json 不应被检入。例如，如果项目正在使用 Git，则可以跟踪 CMakePresets.json，并且应将 CMakeUserPresets.json 添加到 .gitignore 中。

格式

这些文件是 JSON 文档，根对象为对象

{
  "version": 10,
  "cmakeMinimumRequired": {
    "major": 3,
    "minor": 23,
    "patch": 0
  },
  "$comment": "An example CMakePresets.json file",
  "include": [
    "otherThings.json",
    "moreThings.json"
  ],
  "configurePresets": [
    {
      "$comment": [
        "This is a comment row.",
        "This is another comment,",
        "just because we can do it"
      ],
      "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",
      "description": "Default build using Ninja Multi-Config generator",
      "generator": "Ninja Multi-Config"
    },
    {
      "name": "windows-only",
      "inherits": "default",
      "displayName": "Windows-only configuration",
      "description": "This build is only available on Windows",
      "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
    }
  }
}

指定版本为 10 或更高的预设文件可以在 JSON 对象内的任何级别使用键 $comment 来包含注释以提供文档。

根对象识别以下字段

$schema

一个可选的字符串，提供 JSON 模式的 URI，用于描述此 JSON 文档的结构。此字段用于支持 JSON 模式的编辑器中的验证和自动完成。它不影响文档本身的行为。如果未指定此字段，JSON 文档仍然有效，但使用 JSON 模式进行验证和自动完成的工具可能无法正常工作。在指定版本为 8 或更高的预设文件中允许使用此字段。

version

一个必需的整数，表示 JSON 模式的版本。支持的版本有

1

版本 3.19 中新增。

2

版本 3.20 中新增。

3

版本 3.21 中新增。

4

版本 3.23 中新增。

5

版本 3.24 中新增。

6

版本 3.25 中新增。

7

版本 3.27 中新增。

8

版本 3.28 中新增。

9

版本 3.30 中新增。

10

版本 3.31 中新增。

cmakeMinimumRequired

一个可选的对象，表示构建此项目所需的最低 CMake 版本。此对象包含以下字段

major

一个可选的整数，表示主版本号。

minor

一个可选的整数，表示次版本号。

patch

一个可选的整数，表示补丁版本号。

include

一个可选的字符串数组，表示要包含的文件。如果文件名不是绝对路径，则将其视为相对于当前文件。在指定版本为 4 或更高的预设文件中允许使用此字段。有关包含文件的约束的讨论，请参见 包含。

vendor

一个可选的映射，包含供应商特定的信息。CMake 不会解释此字段的内容，除非验证它是否是映射（如果存在）。但是，键应为供应商特定的域名，后跟以 / 分隔的路径。例如，Example IDE 1.0 可以使用 example.com/ExampleIDE/1.0。每个字段的值可以是供应商所需的任何内容，但通常将是一个映射。

configurePresets

一个可选的 配置预设 对象数组。在指定版本为 1 或更高的预设文件中允许使用此字段。

buildPresets

一个可选的 构建预设 对象数组。在指定版本为 2 或更高的预设文件中允许使用此字段。

testPresets

一个可选的 测试预设 对象数组。在指定版本为 2 或更高的预设文件中允许使用此字段。

packagePresets

一个可选的 打包预设 对象数组。在指定版本为 6 或更高的预设文件中允许使用此字段。

workflowPresets

一个可选的 工作流预设 对象数组。在指定版本为 6 或更高的预设文件中允许使用此字段。

包含

CMakePresets.json 和 CMakeUserPresets.json 可以在文件版本 4 及更高版本中使用 include 字段包含其他文件。这些文件包含的文件也可以包含其他文件。如果 CMakePresets.json 和 CMakeUserPresets.json 都存在，则 CMakeUserPresets.json 隐式包含 CMakePresets.json，即使在所有格式版本中都没有 include 字段。

如果预设文件包含从另一个文件中的预设继承的预设，则该文件必须直接或间接地包含另一个文件。文件之间不允许包含循环。如果 a.json 包含 b.json，则 b.json 不能包含 a.json。但是，一个文件可能会从同一文件或不同文件多次包含。

从 CMakePresets.json 直接或间接包含的文件应保证由项目提供。CMakeUserPresets.json 可以包含来自任何位置的文件。

从版本 7 开始，include 字段支持 宏展开，但仅支持 $penv{} 宏展开。从版本 9 开始，其他宏展开也可用，但 $env{} 和预设特定的宏除外，即那些从预设定义内的字段派生的宏，如 presetName。

配置预设

configurePresets 数组的每个条目都是一个 JSON 对象，可能包含以下字段

name

一个必需的字符串，表示预设的机器友好名称。此标识符在 cmake --preset 选项中使用。在同一目录下的 CMakePresets.json 和 CMakeUserPresets.json 的并集中，不得有两个同名的配置预设。但是，配置预设可以与构建、测试、打包或工作流预设同名。

hidden

一个可选的布尔值，指定预设是否应隐藏。如果预设被隐藏，则不能在 --preset= 参数中使用，也不会显示在 CMake GUI 中，并且即使从继承中获得，也不必具有有效的 generator 或 binaryDir。hidden 预设旨在用作其他预设通过 inherits 字段继承的基础。

inherits

一个可选的字符串数组，表示要从中继承的预设的名称。此字段也可以是一个字符串，它等效于包含一个字符串的数组。

预设将默认继承来自 inherits 预设的所有字段（除了 name、hidden、inherits、description 和 displayName），但可以根据需要覆盖它们。如果多个 inherits 预设为同一字段提供冲突的值，则 inherits 数组中较早的预设将被优先考虑。

预设只能从在同一文件或其包含的文件之一（直接或间接）中定义的另一个预设继承。CMakePresets.json 中的预设可能不会从 CMakeUserPresets.json 中的预设继承。

condition

一个可选的 条件 对象。在指定版本为 3 或更高的预设文件中允许使用此字段。

vendor

一个可选的映射，包含供应商特定的信息。CMake 不会解释此字段的内容，除非验证它是否是映射（如果存在）。但是，它应遵循与根级别的 vendor 字段相同的约定。如果供应商使用他们自己的每个预设的 vendor 字段，则他们应在适当时以合理的方式实现继承。

displayName

一个可选的字符串，表示预设的人类友好名称。

description

一个可选的字符串，表示预设的人类友好描述。

generator

一个可选的字符串，表示要用于预设的生成器。如果未指定 generator，则必须从 inherits 预设继承（除非此预设是 hidden）。在版本 3 或更高版本中，可以省略此字段以回退到常规生成器发现过程。

请注意，对于 Visual Studio 生成器，与命令行 -G 参数不同，您不能在生成器名称中包含平台名称。请改用 architecture 字段。

architecture, toolset

可选字段，分别表示支持它们的 生成器 的平台和工具集。

有关 architecture 的可能值，请参见 cmake -A 选项，有关 toolset 的可能值，请参见 cmake -T 选项。

每个字段可以是字符串或具有以下字段的对象

value

一个可选的字符串，表示值。

strategy

一个可选的字符串，告诉 CMake 如何处理 architecture 或 toolset 字段。有效值为

"set"

设置相应的值。对于不支持相应字段的生成器，这将导致错误。

"external"

即使生成器支持该值，也不要设置该值。例如，如果预设使用 Ninja 生成器，并且 IDE 知道如何从 architecture 和 toolset 字段设置 Visual C++ 环境，则此选项很有用。在这种情况下，CMake 将忽略该字段，但 IDE 可以使用它们在调用 CMake 之前设置环境。

如果没有给出 strategy 字段，或者如果该字段使用字符串形式而不是对象形式，则行为与 "set" 相同。

toolchainFile

一个可选的字符串，表示工具链文件的路径。此字段支持 宏展开。如果指定了相对路径，则相对于构建目录计算，如果未找到，则相对于源目录计算。此字段优先于任何 CMAKE_TOOLCHAIN_FILE 值。在指定版本为 3 或更高的预设文件中允许使用此字段。

graphviz

一个可选的字符串，表示 graphviz 输入文件的路径，该文件将包含项目中的所有库和可执行文件依赖项。有关更多详细信息，请参见 CMakeGraphVizOptions 的文档。

此字段支持 宏展开。如果指定了相对路径，则相对于当前工作目录计算。在指定版本为 10 或更高的预设文件中允许使用此字段。

binaryDir

一个可选的字符串，表示输出二进制文件目录的路径。此字段支持 宏展开。如果指定了相对路径，则相对于源目录计算。如果未指定 binaryDir，则必须从 inherits 预设继承（除非此预设是 hidden）。在版本 3 或更高版本中，可以省略此字段。

installDir

一个可选的字符串，表示安装目录的路径。此字段支持 宏展开。如果指定了相对路径，则相对于源目录计算。在指定版本为 3 或更高的预设文件中允许使用此字段。

cmakeExecutable

一个可选的字符串，表示要用于此预设的 CMake 可执行文件的路径。这保留供 IDE 使用，CMake 本身不使用。使用此字段的 IDE 应展开其中的任何宏。

cacheVariables

一个可选的缓存变量映射。键是变量名（不能为空字符串），值可以是 null、布尔值（等效于 "TRUE" 或 "FALSE" 的值和 BOOL 类型）、表示变量值的字符串（支持 宏展开），或者具有以下字段的对象

type

一个可选的字符串，表示变量的类型。

value

value

一个必需的字符串或布尔值，表示变量的值。布尔值等效于 "TRUE" 或 "FALSE"。此字段支持 宏展开。

缓存变量通过 inherits 字段继承，预设的变量将是其自身的 cacheVariables 与其所有父级的 cacheVariables 的并集。如果此并集中的多个预设定义了相同的变量，则应用 inherits 的标准规则。将变量设置为 null 会导致不设置该变量，即使从另一个预设继承了值也是如此。

environment

一个可选的环境变量映射。键是变量名（不能为空字符串），值可以是 null 或表示变量值的字符串。无论进程的环境是否为其赋值，都会设置每个变量。

此字段支持 宏展开，并且此映射中的环境变量可以相互引用，并且可以按任何顺序列出，只要此类引用不会导致循环（例如，如果 ENV_1 是 $env{ENV_2}，则 ENV_2 不能是 $env{ENV_1}）。$penv{NAME} 允许通过仅访问父环境中的值来为现有环境变量添加前缀或后缀。

环境变量通过 inherits 字段继承，预设的环境将是其自身的 environment 与其所有父级的 environment 的并集。如果此并集中的多个预设定义了相同的变量，则应用 inherits 的标准规则。将变量设置为 null 会导致不设置该变量，即使从另一个预设继承了值也是如此。

warnings

一个可选的对象，指定要启用的警告。该对象可能包含以下字段

dev

一个可选的布尔值。等效于在命令行上传递 -Wdev 或 -Wno-dev。如果 errors.dev 设置为 true，则不能将其设置为 false。

deprecated

一个可选的布尔值。等效于在命令行上传递 -Wdeprecated 或 -Wno-deprecated。如果 errors.deprecated 设置为 true，则不能将其设置为 false。

uninitialized

一个可选的布尔值。将其设置为 true 等效于在命令行上传递 --warn-uninitialized。

unusedCli

一个可选的布尔值。将其设置为 false 等效于在命令行上传递 --no-warn-unused-cli。

systemVars

一个可选的布尔值。将其设置为 true 等效于在命令行上传递 --check-system-vars。

errors

一个可选的对象，指定要启用的警告。该对象可能包含以下字段

一个可选的对象，指定要启用的错误。该对象可能包含以下字段

一个可选的布尔值。等效于在命令行上传递 -Wdev 或 -Wno-dev。如果 errors.dev 设置为 true，则不能将其设置为 false。

dev

deprecated

debug

一个可选的对象，指定调试选项。该对象可能包含以下字段

output

tryCompile

一个可选的布尔值。将其设置为 true 等效于在命令行上传递 --debug-trycompile。

find

一个可选的布尔值。将其设置为 true 等效于在命令行上传递 --debug-find。

trace

一个可选的对象，指定跟踪选项。在指定版本为 7 的预设文件中允许使用此字段。该对象可能包含以下字段

mode

一个可选的字符串，指定跟踪模式。有效值为

on

导致打印所有进行的调用及其来源的跟踪。等效于在命令行上传递 --trace。

off

不会打印所有调用的跟踪。

expand

导致打印所有进行的调用及其来源的跟踪，并展开变量。等效于在命令行上传递 --trace-expand。

format

一个可选的字符串，指定跟踪的格式输出。有效值为

human

以人类可读的格式打印每条跟踪行。这是默认格式。等效于在命令行上传递 --trace-format=human。

json-v1

将每行打印为单独的 JSON 文档。等效于在命令行上传递 --trace-format=json-v1。

source

一个可选的字符串数组，表示要跟踪的源文件的路径。此字段也可以是一个字符串，它等效于包含一个字符串的数组。等效于在命令行上传递 --trace-source。

redirect

一个可选的字符串，指定跟踪输出文件的路径。等效于在命令行上传递 --trace-redirect。

构建预设

buildPresets 数组的每个条目都是一个 JSON 对象，可能包含以下字段

name

name

hidden

一个必需的字符串，表示预设的机器友好名称。此标识符在 cmake --build --preset 选项中使用。在同一目录下的 CMakePresets.json 和 CMakeUserPresets.json 的并集中，不得有两个同名的构建预设。但是，构建预设可以与配置、测试、打包或工作流预设同名。

inherits

一个可选的字符串数组，表示要从中继承的预设的名称。此字段也可以是一个字符串，它等效于包含一个字符串的数组。

预设将默认继承来自 inherits 预设的所有字段（除了 name、hidden、inherits、description 和 displayName），但可以根据需要覆盖它们。如果多个 inherits 预设为同一字段提供冲突的值，则 inherits 数组中较早的预设将被优先考虑。

预设只能从在同一文件或其包含的文件之一（直接或间接）中定义的另一个预设继承。CMakePresets.json 中的预设可能不会从 CMakeUserPresets.json 中的预设继承。

condition

一个可选的 条件 对象。在指定版本为 3 或更高的预设文件中允许使用此字段。

vendor

一个可选的映射，包含供应商特定的信息。CMake 不会解释此字段的内容，除非验证它是否是映射（如果存在）。但是，它应遵循与根级别的 vendor 字段相同的约定。如果供应商使用他们自己的每个预设的 vendor 字段，则他们应在适当时以合理的方式实现继承。

displayName

一个可选的字符串，表示预设的人类友好名称。

description

一个可选的字符串，表示预设的人类友好描述。

缓存变量通过 inherits 字段继承，预设的变量将是其自身的 cacheVariables 与其所有父级的 cacheVariables 的并集。如果此并集中的多个预设定义了相同的变量，则应用 inherits 的标准规则。将变量设置为 null 会导致不设置该变量，即使从另一个预设继承了值也是如此。

environment

一个可选的环境变量映射。键是变量名（不能为空字符串），值可以是 null 或表示变量值的字符串。无论进程的环境是否为其赋值，都会设置每个变量。

此字段支持 宏展开，并且此映射中的环境变量可以相互引用，并且可以按任何顺序列出，只要此类引用不会导致循环（例如，如果 ENV_1 是 $env{ENV_2}，则 ENV_2 不能是 $env{ENV_1}）。$penv{NAME} 允许通过仅访问父环境中的值来为现有环境变量添加前缀或后缀。

hidden

一个可选的布尔值，指定预设是否应隐藏。如果预设被隐藏，则不能在 --preset 参数中使用，并且即使从继承中获得，也不必具有有效的 configurePreset。hidden 预设旨在用作其他预设通过 inherits 字段继承的基础。

注意

对于使用 ExternalProject 的 CMake 项目，如果配置预设具有 ExternalProject 中需要的环境变量，请使用继承该配置预设的构建预设，否则 ExternalProject 将不会在配置预设中设置环境变量。示例：假设主机默认为一个编译器（例如 Clang），并且用户希望使用另一个编译器（例如 GCC）。设置配置预设环境变量 CC 和 CXX，并使用继承该配置预设的构建预设。否则，ExternalProject 可能会使用与顶层 CMake 项目不同的（系统默认）编译器。

configurePreset

一个可选的字符串，指定要与此构建预设关联的配置预设的名称。如果未指定 configurePreset，则必须从 inherits 预设继承（除非此预设被隐藏）。构建目录是从配置预设推断出来的，因此构建将在与配置相同的 binaryDir 中进行。

inheritConfigureEnvironment

一个可选的布尔值，默认为 true。如果为 true，则在所有继承的构建预设环境之后，但在在此构建预设中显式指定的环境变量之前，会继承关联的配置预设中的环境变量。

jobs

一个可选的整数。等效于在命令行上传递 --parallel 或 -j。

targets

一个可选的字符串或字符串数组。等效于在命令行上传递 --target 或 -t。供应商可能会忽略 targets 属性或隐藏显式指定目标的构建预设。此字段支持宏展开。

configuration

一个可选的字符串。等效于在命令行上传递 --config。

cleanFirst

一个可选的布尔值。如果为 true，则等效于在命令行上传递 --clean-first。

resolvePackageReferences

on

一个可选的字符串，指定包解析模式。在指定版本为 4 或更高的预设文件中允许使用此字段。

off

包引用用于定义来自外部包管理器的包的依赖项。当前仅支持 NuGet 与 Visual Studio 生成器结合使用。如果没有定义包引用的目标，则此选项不执行任何操作。有效值为

resolve

导致在尝试构建之前解析包引用。

hidden

命令行参数 --resolve-package-references 将优先于此设置。如果未提供命令行参数且未指定此设置，则将评估特定于环境的缓存变量，以确定是否应执行包还原。

当使用 Visual Studio 生成器时，包引用使用 VS_PACKAGE_REFERENCES 属性定义。包引用使用 NuGet 还原。可以通过将 CMAKE_VS_NUGET_PACKAGE_RESTORE 变量设置为 OFF 来禁用此功能。这也可以从配置预设中完成。

verbose

一个可选的布尔值。如果为 true，则等效于在命令行中传递 --verbose。

nativeToolOptions

一个可选的字符串数组。等效于在命令行中传递 -- 后的选项。数组值支持宏展开。

测试预设

testPresets 数组的每个条目都是一个 JSON 对象，可以包含以下字段

name

一个必需的字符串，表示预设的机器友好名称。此标识符在 ctest --preset 选项中使用。在同一目录下的 CMakePresets.json 和 CMakeUserPresets.json 的并集中，不得存在两个同名的测试预设。但是，测试预设可以与配置、构建、打包或工作流预设同名。

hidden

一个可选的布尔值，指定是否应隐藏预设。如果预设被隐藏，则不能在 --preset 参数中使用，并且即使从继承中获得，也不必具有有效的 configurePreset。hidden 预设旨在用作其他预设通过 inherits 字段继承的基础。

inherits

一个可选的字符串数组，表示要从中继承的预设的名称。此字段也可以是一个字符串，它等效于包含一个字符串的数组。

预设将默认继承来自 inherits 预设的所有字段（除了 name、hidden、inherits、description 和 displayName），但可以根据需要覆盖它们。如果多个 inherits 预设为同一字段提供冲突的值，则 inherits 数组中较早的预设将被优先考虑。

预设只能从在同一文件或其包含的文件之一（直接或间接）中定义的另一个预设继承。CMakePresets.json 中的预设可能不会从 CMakeUserPresets.json 中的预设继承。

condition

一个可选的 条件 对象。在指定版本为 3 或更高的预设文件中允许使用此字段。

vendor

一个可选的映射，包含供应商特定的信息。CMake 不会解释此字段的内容，除非验证它是否是映射（如果存在）。但是，它应遵循与根级别的 vendor 字段相同的约定。如果供应商使用他们自己的每个预设的 vendor 字段，则他们应在适当时以合理的方式实现继承。

displayName

一个可选的字符串，表示预设的人类友好名称。

description

一个可选的字符串，表示预设的人类友好描述。

缓存变量通过 inherits 字段继承，预设的变量将是其自身的 cacheVariables 与其所有父级的 cacheVariables 的并集。如果此并集中的多个预设定义了相同的变量，则应用 inherits 的标准规则。将变量设置为 null 会导致不设置该变量，即使从另一个预设继承了值也是如此。

environment

一个可选的环境变量映射。键是变量名（不能为空字符串），值可以是 null 或表示变量值的字符串。无论进程的环境是否为其赋值，都会设置每个变量。

此字段支持 宏展开，并且此映射中的环境变量可以相互引用，并且可以按任何顺序列出，只要此类引用不会导致循环（例如，如果 ENV_1 是 $env{ENV_2}，则 ENV_2 不能是 $env{ENV_1}）。$penv{NAME} 允许通过仅访问父环境中的值来为现有环境变量添加前缀或后缀。

注意

一个可选的字符串，指定要与此测试预设关联的配置预设的名称。如果未指定 configurePreset，则必须从继承的预设中继承（除非此预设被隐藏）。构建目录是从配置预设推断出来的，因此测试将在配置和构建所在的相同 binaryDir 中运行。

configurePreset

一个可选的布尔值，默认为 true。如果为 true，则关联的配置预设中的环境变量将在所有继承的测试预设环境之后，但在在此测试预设中显式指定的环境变量之前被继承。

targets

一个可选的字符串。等效于在命令行中传递 --build-config。

overwriteConfigurationFile

一个可选的配置选项数组，用于覆盖 CTest 配置文件中指定的选项。等效于为数组中的每个值传递 --overwrite。数组值支持宏展开。

一个可选的对象，指定调试选项。该对象可能包含以下字段

一个可选的对象，指定输出选项。该对象可以包含以下字段。

shortProgress

一个可选的布尔值。如果为 true，则等效于在命令行中传递 --progress。

verbosity

一个可选的字符串，指定详细级别。必须是以下之一

default

等效于在命令行中不传递任何详细标志。

verbose

verbose

等效于在命令行中传递 --verbose。

extra

deprecated

等效于在命令行中传递 --extra-verbose。

debug

一个可选的布尔值。如果为 true，则等效于在命令行中传递 --debug。

outputOnFailure

一个可选的布尔值。如果为 true，则等效于在命令行中传递 --output-on-failure。

quiet

一个可选的布尔值。如果为 true，则等效于在命令行中传递 --quiet。

outputLogFile

一个可选的字符串，指定日志文件的路径。等效于在命令行中传递 --output-log。此字段支持宏展开。

outputJUnitFile

一个可选的字符串，指定 JUnit 文件的路径。等效于在命令行中传递 --output-junit。此字段支持宏展开。这在指定版本为 6 或更高版本的预设文件中是允许的。

labelSummary

一个可选的布尔值。如果为 false，则等效于在命令行中传递 --no-label-summary。

subprojectSummary

一个可选的布尔值。如果为 false，则等效于在命令行中传递 --no-subproject-summary。

maxPassedTestOutputSize

一个可选的整数，指定通过测试的最大输出大小（以字节为单位）。等效于在命令行中传递 --test-output-size-passed。

maxFailedTestOutputSize

一个可选的整数，指定失败测试的最大输出大小（以字节为单位）。等效于在命令行中传递 --test-output-size-failed。

testOutputTruncation

一个可选的字符串，指定测试输出截断模式。等效于在命令行中传递 --test-output-truncation。这在指定版本为 5 或更高版本的预设文件中是允许的。

maxTestNameWidth

一个可选的整数，指定要输出的测试名称的最大宽度。等效于在命令行中传递 --max-width。

include

filter

name

一个可选的对象，指定如何过滤要运行的测试。该对象可以包含以下字段。

include

一个可选的对象，指定要包含哪些测试。该对象可以包含以下字段。

names

一个可选的字符串，指定测试名称的正则表达式。等效于在命令行中传递 --tests-regex。此字段支持宏展开。CMake 正则表达式语法在 string(REGEX) 下描述。

索引

label

一个可选的字符串，指定测试标签的正则表达式。等效于在命令行中传递 --label-regex。此字段支持宏展开。

useUnion

一个可选的布尔值。等效于在命令行中传递 --union。

index

一个可选的对象，指定要按测试索引包含的测试。该对象可以包含以下字段。也可以是可选的字符串，指定包含 --tests-information 命令行语法的文件的字符串。如果指定为字符串，则此字段支持宏展开。

start

一个可选的整数，指定要开始测试的测试索引。

end

一个可选的整数，指定要停止测试的测试索引。

stride

name

一个可选的整数，指定增量。

include

specificTests

一个可选的整数数组，指定要运行的特定测试索引。

exclude

一个可选的对象，指定要排除哪些测试。该对象可以包含以下字段。

names

一个可选的字符串，指定测试名称的正则表达式。等效于在命令行中传递 --exclude-regex。此字段支持宏展开。

label

一个可选的字符串，指定测试标签的正则表达式。等效于在命令行中传递 --label-exclude。此字段支持宏展开。

fixtures

一个可选的对象，指定要从添加测试中排除哪些 fixtures。该对象可以包含以下字段。

any

一个可选的字符串，指定要从添加任何测试中排除的文本 fixtures 的正则表达式。等效于命令行中的 --fixture-exclude-any。此字段支持宏展开。

setup

一个可选的字符串，指定要从添加 setup 测试中排除的文本 fixtures 的正则表达式。等效于命令行中的 --fixture-exclude-setup。此字段支持宏展开。

cleanup

inheritConfigureEnvironment

一个可选的字符串，指定要从添加 cleanup 测试中排除的文本 fixtures 的正则表达式。等效于命令行中的 --fixture-exclude-cleanup。此字段支持宏展开。

execution

一个可选的对象，指定测试执行的选项。该对象可以包含以下字段。

stopOnFailure

一个可选的布尔值。如果为 true，则等效于在命令行中传递 --stop-on-failure。

enableFailover

一个可选的布尔值。如果为 true，则等效于在命令行中传递 -F。

human

json-v1

parallelLevel

一个可选的整数。等效于在命令行中传递 --parallel。

mode

resourceSpecFile

一个可选的字符串。等效于在命令行中传递 --resource-spec-file。此字段支持宏展开。

testLoad

一个可选的整数。等效于在命令行中传递 --test-load。

showOnly

一个可选的字符串。等效于在命令行中传递 --show-only。该字符串必须是以下值之一

显示所有测试名称

显示所有测试名称和标签

repeat

一个可选的对象，指定如何重复测试。等效于在命令行中传递 --repeat。该对象必须具有以下字段。

mode

一个必需的字符串。必须是以下值之一

until-fail

until-pass

default

after-timeout

count

tries

一个必需的整数。

interactiveDebugging

一个可选的布尔值。如果为 true，则等效于在命令行中传递 --interactive-debug-mode 1。如果为 false，则等效于在命令行中传递 --interactive-debug-mode 0。

scheduleRandom

name

一个可选的布尔值。如果为 true，则等效于在命令行中传递 --schedule-random。

hidden

timeout

inherits

一个可选的字符串数组，表示要从中继承的预设的名称。此字段也可以是一个字符串，它等效于包含一个字符串的数组。

预设将默认继承来自 inherits 预设的所有字段（除了 name、hidden、inherits、description 和 displayName），但可以根据需要覆盖它们。如果多个 inherits 预设为同一字段提供冲突的值，则 inherits 数组中较早的预设将被优先考虑。

预设只能从在同一文件或其包含的文件之一（直接或间接）中定义的另一个预设继承。CMakePresets.json 中的预设可能不会从 CMakeUserPresets.json 中的预设继承。

condition

一个可选的整数。等效于在命令行中传递 --timeout。

vendor

一个可选的映射，包含供应商特定的信息。CMake 不会解释此字段的内容，除非验证它是否是映射（如果存在）。但是，它应遵循与根级别的 vendor 字段相同的约定。如果供应商使用他们自己的每个预设的 vendor 字段，则他们应在适当时以合理的方式实现继承。

displayName

一个可选的字符串，表示预设的人类友好名称。

description

一个可选的字符串，表示预设的人类友好描述。

缓存变量通过 inherits 字段继承，预设的变量将是其自身的 cacheVariables 与其所有父级的 cacheVariables 的并集。如果此并集中的多个预设定义了相同的变量，则应用 inherits 的标准规则。将变量设置为 null 会导致不设置该变量，即使从另一个预设继承了值也是如此。

environment

一个可选的环境变量映射。键是变量名（不能为空字符串），值可以是 null 或表示变量值的字符串。无论进程的环境是否为其赋值，都会设置每个变量。

此字段支持 宏展开，并且此映射中的环境变量可以相互引用，并且可以按任何顺序列出，只要此类引用不会导致循环（例如，如果 ENV_1 是 $env{ENV_2}，则 ENV_2 不能是 $env{ENV_1}）。$penv{NAME} 允许通过仅访问父环境中的值来为现有环境变量添加前缀或后缀。

注意

noTestsAction

configurePreset

一个可选的字符串，指定如果未找到测试时的行为。必须是以下值之一

default

等效于在命令行中不传递任何值。

error

等效于在命令行中传递 --no-tests=error。

ignore

等效于在命令行中传递 --no-tests=ignore。

打包预设

打包预设可以在 schema 版本 6 或更高版本中使用。packagePresets 数组的每个条目都是一个 JSON 对象，可以包含以下字段

一个可选的对象，指定调试选项。该对象可能包含以下字段

一个必需的字符串，表示预设的机器友好名称。此标识符在 cpack --preset 选项中使用。在同一目录下的 CMakePresets.json 和 CMakeUserPresets.json 的并集中，不得存在两个同名的打包预设。但是，打包预设可以与配置、构建、测试或工作流预设同名。

deprecated

一个可选的布尔值，指定是否应隐藏预设。如果预设被隐藏，则不能在 --preset 参数中使用，并且即使从继承中获得，也不必具有有效的 configurePreset。hidden 预设旨在用作其他预设通过 inherits 字段继承的基础。

verbose

一个可选的 条件 对象。

一个可选的字符串，指定要与此打包预设关联的配置预设的名称。如果未指定 configurePreset，则必须从继承的预设中继承（除非此预设被隐藏）。构建目录是从配置预设推断出来的，因此打包将在配置和构建所在的相同 binaryDir 中运行。

一个可选的布尔值，默认为 true。如果为 true，则关联的配置预设中的环境变量将在所有继承的打包预设环境之后，但在在此打包预设中显式指定的环境变量之前被继承。

generators

一个可选的字符串数组，表示 CPack 要使用的生成器。

configurations

一个可选的字符串数组，表示 CPack 要打包的构建配置。

variables

一个可选的变量映射，用于传递给 CPack，等效于 -D 参数。每个键都是变量的名称，值是要分配给该变量的字符串。

configFile

一个可选的字符串，表示 CPack 要使用的配置文件。

name

output

vendor

一个可选的对象，指定输出选项。有效键为

displayName

一个可选的字符串，表示预设的人类友好名称。

description

一个可选的字符串，表示预设的人类友好描述。

debug

一个可选的布尔值，指定是否打印调试信息。true 值等效于在命令行中传递 --debug。

type

verbose

name

一个可选的布尔值，指定是否详细打印。true 值等效于在命令行中传递 --verbose。

packageName

一个可选的字符串，表示包名称。

type

packageVersion

一个可选的字符串，表示包版本。

packageDirectory

value

一个可选的字符串，表示放置包的目录。

vendorName

一个可选的字符串，表示供应商名称。

工作流预设

工作流预设可以在 schema 版本 6 或更高版本中使用。workflowPresets 数组的每个条目都是一个 JSON 对象，可以包含以下字段

一个必需的字符串，表示预设的机器友好名称。此标识符在 cmake --workflow --preset 选项中使用。在同一目录下的 CMakePresets.json 和 CMakeUserPresets.json 的并集中，不得存在两个同名的工作流预设。但是，工作流预设可以与配置、构建、测试或打包预设同名。

一个可选的映射，包含特定于供应商的信息。CMake 不解释此字段的内容，除非验证它是否是映射（如果存在）。但是，它应遵循与根级别的 vendor 字段相同的约定。

vendor

步骤

steps

一个必需的对象数组，描述工作流的步骤。第一步必须是配置预设，所有后续步骤必须是非配置预设，其 configurePreset 字段与起始配置预设匹配。每个对象可以包含以下字段

type

一个必需的字符串。第一步必须是 configure。后续步骤必须是 build、test 或 package。

preset

一个必需的字符串，表示要作为此工作流步骤运行的配置、构建、测试或打包预设的名称。

条件

condition 预设的字段（在指定版本为 3 或更高版本的预设文件中允许）用于确定是否启用预设。例如，这可以用于在 Windows 以外的平台上禁用预设。condition 可以是布尔值、null 或对象。如果它是布尔值，则该布尔值指示是否启用或禁用预设。如果它是 null，则启用预设，但 null 条件不会被可能从预设继承的任何预设继承。子条件（例如在 not、anyOf 或 allOf 条件中）不能为 null。如果它是一个对象，则它具有以下字段

type

type

一个必需的字符串，具有以下值之一

"const"

指示条件是常量。这等效于使用布尔值代替对象。条件对象将具有以下附加字段

value

一个必需的布尔值，它为条件的评估提供一个常量值。

"equals"

"notEquals"

指示条件比较两个字符串，以查看它们是否相等（或不相等）。条件对象将具有以下附加字段

lhs

要比较的第一个字符串。此字段支持宏展开。

condition

rhs

要比较的第二个字符串。此字段支持宏展开。

"inList"

"notInList"

指示条件在字符串列表中搜索字符串。条件对象将具有以下附加字段

string

要搜索的必需字符串。此字段支持宏展开。

list

要搜索的必需字符串数组。此字段支持宏展开，并使用短路求值。

"matches"

"notMatches"

指示条件在字符串中搜索正则表达式。条件对象将具有以下附加字段

string

要搜索的必需字符串。此字段支持宏展开。

regex

要搜索的必需正则表达式。此字段支持宏展开。

要搜索的必需字符串。此字段支持宏展开。

"anyOf"

"allOf"

指示条件是零个或多个嵌套条件的聚合。条件对象将具有以下附加字段

conditions

一个必需的条件对象数组。这些条件使用短路求值。

"not"

指示条件是另一个条件的取反。条件对象将具有以下附加字段

condition

一个必需的条件对象。

宏展开

如上所述，某些字段支持宏展开。宏以 $<macro-namespace>{<macro-name>} 的形式识别。所有宏都在正在使用的预设的上下文中求值，即使宏位于从另一个预设继承的字段中也是如此。例如，如果 Base 预设将变量 PRESET_NAME 设置为 ${presetName}，并且 Derived 预设从 Base 继承，则 PRESET_NAME 将设置为 Derived。

在宏名称末尾不放置右大括号是错误的。例如，${sourceDir 是无效的。美元符号 ($) 后跟任何不是左大括号 ({) 以及可能的命名空间的内容，都将被解释为字面美元符号。

识别的宏包括

${sourceDir}

类似于 $env{<variable-name>}，但其值仅来自父环境，而永远不会来自 environment 字段。这允许您在现有环境变量的前面或后面添加值。例如，将 PATH 设置为 /path/to/ninja/bin:$penv{PATH} 会将 /path/to/ninja/bin 添加到 PATH 环境变量的前面。这是必需的，因为 $env{<variable-name>} 不允许循环引用。

$vendor{<macro-name>}

供应商插入他们自己宏的扩展点。CMake 将无法使用包含 $vendor{<macro-name>} 宏的预设，并实际上会忽略此类预设。但是，它仍然能够使用来自同一文件的其他预设。

CMake 不会尝试解释 $vendor{<macro-name>} 宏。但是，为了避免名称冲突，IDE 供应商应在 <macro-name> 前面加上一个非常短的（最好 <= 4 个字符）供应商标识符前缀，后跟一个 .，然后再跟宏名称。例如，Example IDE 可以有 $vendor{xide.ideInstallDir}。

Schema

此 文件 为 CMakePresets.json 格式提供了机器可读的 JSON 模式。