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 文档结构的 JSON 模式的 URI。此字段用于支持 JSON 模式的编辑器中的验证和自动完成。它不影响文档本身的行为。如果未指定此字段，JSON 文档仍然有效，但使用 JSON 模式进行验证和自动完成的工具可能无法正常运行。这在指定版本 8 或更高的预设文件中是允许的。

版本

一个必需的整数，表示 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 最低版本。此对象包含以下字段

主要版本: 一个可选整数，表示主版本。
次要版本: 一个可选整数，表示次版本。
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 对象，可能包含以下字段

名称

一个必需的字符串，表示预设的机器友好名称。此标识符用于 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

一个可选的字符串，包含预设的人机友好名称。

描述

一个可选的字符串，包含预设的人机友好描述。

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: 一个必需的字符串或布尔值，表示变量的值。布尔值等同于 "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

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

开发: 一个可选布尔值。等同于在命令行上传递 -Wdev 或 -Wno-dev>。如果 errors.dev 设置为 true，则不能将其设置为 false。
已弃用: 一个可选布尔值。等同于在命令行上传递 -Wdeprecated 或 -Wno-deprecated>。如果 errors.deprecated 设置为 true，则不能将其设置为 false。
uninitialized: 一个可选布尔值。将其设置为 true 等同于在命令行上传递 --warn-uninitialized。
unusedCli: 一个可选布尔值。将其设置为 false 等同于在命令行上传递 --no-warn-unused-cli。
systemVars: 一个可选布尔值。将其设置为 true 等同于在命令行上传递 --check-system-vars。

errors

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

开发: 一个可选布尔值。等同于在命令行上传递 -Werror=dev 或 -Wno-error=dev>。如果 warnings.dev 设置为 false，则不能将其设置为 true。
已弃用: 一个可选布尔值。等同于在命令行上传递 -Werror=deprecated 或 -Wno-error=deprecated>。如果 warnings.deprecated 设置为 false，则不能将其设置为 true。

debug

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

output

trace

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

mode

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

on: 导致打印所有调用的跟踪以及从何处调用。等同于在命令行上传递 --trace。
off: 将不打印所有调用的跟踪。
expand: 导致打印所有调用的跟踪（变量已扩展）以及从何处调用。等同于在命令行上传递 --trace-expand。

format

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

人工: 以人类可读的格式打印每一行跟踪。这是默认格式。等同于在命令行上传递 --trace-format=human。
json-v1: 将每一行打印为单独的 JSON 文档。等同于在命令行上传递 --trace-format=json-v1。

源

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

redirect

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

构建预设 ¶

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

名称

一个必需的字符串，表示预设的机器友好名称。此标识符用于 cmake --build --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

一个可选的字符串，包含预设的人机友好名称。

描述

一个可选的字符串，包含预设的人机友好描述。

environment

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

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

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

注意

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

configurePreset

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

inheritConfigureEnvironment

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

jobs

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

targets

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

configuration

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

cleanFirst

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

resolvePackageReferences

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

包引用用于定义对外部包管理器中包的依赖关系。目前仅支持与 Visual Studio 生成器结合使用的 NuGet。如果没有定义包引用的目标，则此选项不起作用。有效值是

on: 导致包引用在尝试构建之前被解析。
off: 包引用将不会被解析。请注意，这可能会在某些构建环境中导致错误，例如 .NET SDK 样式项目。
only: 仅解析包引用，但不执行构建。

注意

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

使用 Visual Studio 生成器时，包引用使用 VS_PACKAGE_REFERENCES 属性定义。包引用使用 NuGet 恢复。可以通过将 CMAKE_VS_NUGET_PACKAGE_RESTORE 变量设置为 OFF 来禁用它。这也可以在配置预设中完成。

verbose

一个可选布尔值。如果为 true，等同于在命令行上传递 --verbose。

nativeToolOptions

一个可选的字符串数组。等同于在命令行上在 -- 之后传递选项。数组值支持宏扩展。

测试预设 ¶

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

名称

一个必需的字符串，表示预设的机器友好名称。此标识符用于 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

一个可选的字符串，包含预设的人机友好名称。

描述

一个可选的字符串，包含预设的人机友好描述。

environment

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

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

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

configurePreset

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

inheritConfigureEnvironment

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

configuration

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

overwriteConfigurationFile

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

output

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

shortProgress

一个可选布尔值。如果为 true，等同于在命令行上传递 --progress。

verbosity

一个可选字符串，指定详细程度。必须是以下之一

default: 等同于在命令行上不传递任何详细程度标志。
verbose: 等同于在命令行上传递 --verbose。
extra: 等同于在命令行上传递 --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。

filter

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

include

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

名称

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

label

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

useUnion

一个可选布尔值。等同于在命令行上传递 --union。

索引

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

start: 一个可选整数，指定开始测试的测试索引。
end: 一个可选整数，指定停止测试的测试索引。
stride: 一个可选整数，指定增量。
specificTests: 一个可选的整数数组，指定要运行的特定测试索引。

exclude

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

名称

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

label

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

fixtures

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

any: 一个可选字符串，指定要从添加任何测试中排除的文本夹具的正则表达式。等同于命令行上的 --fixture-exclude-any。此字段支持宏扩展。
setup: 一个可选字符串，指定要从添加设置测试中排除的文本夹具的正则表达式。等同于命令行上的 --fixture-exclude-setup。此字段支持宏扩展。
cleanup: 一个可选字符串，指定要从添加清理测试中排除的文本夹具的正则表达式。等同于命令行上的 --fixture-exclude-cleanup。此字段支持宏扩展。

execution

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

stopOnFailure

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

enableFailover

一个可选布尔值。如果为 true，等同于在命令行上传递 -F。

jobs

一个可选整数。等同于在命令行上传递 --parallel。

resourceSpecFile

一个可选字符串。等同于在命令行上传递 --resource-spec-file。此字段支持宏扩展。

testLoad

一个可选整数。等同于在命令行上传递 --test-load。

showOnly

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

人工

json-v1

repeat

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

mode

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

until-fail

until-pass

after-timeout

count

一个必需的整数。

interactiveDebugging

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

scheduleRandom

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

timeout

一个可选整数。等同于在命令行上传递 --timeout。

noTestsAction

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

default: 等同于不在命令行上传递任何值。
error: 等同于在命令行上传递 --no-tests=error。
ignore: 等同于在命令行上传递 --no-tests=ignore。

打包预设 ¶

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

名称

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

hidden

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

inherits

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

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

预设只能继承自同一文件或其包含（直接或间接）的文件中定义的其他预设。CMakePresets.json 中的预设不能继承自 CMakeUserPresets.json 中的预设。

condition

一个可选的条件对象。

vendor

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

displayName

一个可选的字符串，包含预设的人机友好名称。

描述

一个可选的字符串，包含预设的人机友好描述。

environment

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

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

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

configurePreset

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

inheritConfigureEnvironment

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

生成器

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

configurations

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

variables

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

configFile

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

output

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

debug: 一个可选布尔值，指定是否打印调试信息。值为 true 等同于在命令行上传递 --debug。
verbose: 一个可选布尔值，指定是否详细打印。值为 true 等同于在命令行上传递 --verbose。

packageName

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

packageVersion

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

packageDirectory

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

vendorName

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

工作流预设 ¶

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

名称

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

vendor

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

displayName

一个可选的字符串，包含预设的人机友好名称。

描述

一个可选的字符串，包含预设的人机友好描述。

steps

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

type: 一个必需的字符串。第一个步骤必须是 configure。后续步骤必须是 build、test 或 package。
名称: 一个必需的字符串，表示作为此工作流步骤运行的配置、构建、测试或打包预设的名称。

条件 ¶

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

type

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

"const"

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

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

"equals"

"notEquals"

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

lhs: 要比较的第一个字符串。此字段支持宏扩展。
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}

项目源目录的路径（即与 CMAKE_SOURCE_DIR 相同）。

${sourceParentDir}

${sourceDirName}

${sourceDir} 的最后一个文件名组件。例如，如果 ${sourceDir} 是 /path/to/source，则此为 source。

${presetName}

在预设的 name 字段中指定的名称。

这是一个预设特定宏。

${generator}

在预设的 generator 字段中指定的生成器。对于构建和测试预设，这将评估为由 configurePreset 指定的生成器。

这是一个预设特定宏。

${hostSystemName}

主机操作系统的名称。包含与 CMAKE_HOST_SYSTEM_NAME 相同的值。这在指定版本 3 或更高的预设文件中是允许的。

${fileDir}

包含宏的预设文件所在的目录路径。这在指定版本 4 或更高的预设文件中是允许的。

${dollar}

字面美元符号（$）。

${pathListSep}

用于分隔路径列表的本地字符，例如 : 或 ;。

例如，通过将 PATH 设置为 /path/to/ninja/bin${pathListSep}$env{PATH}，${pathListSep} 将扩展为底层操作系统用于在 PATH 中进行连接的字符。

这在指定版本 5 或更高的预设文件中是允许的。

$env{<variable-name>}

名称为 <variable-name> 的环境变量。变量名称不能为空字符串。如果变量在 environment 字段中定义，则使用该值而不是来自父环境的值。如果未定义环境变量，则此值为空字符串。

请注意，虽然 Windows 环境变量名称不区分大小写，但预设中的变量名称仍然区分大小写。这可能会导致使用不一致大小写时出现意外结果。为获得最佳结果，请保持环境变量名称的大小写一致。

$penv{<variable-name>}

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

$vendor{<macro-name>}

供应商插入其自己的宏的扩展点。CMake 无法使用包含 $vendor{<macro-name>} 宏的预设，并有效地忽略此类预设。但是，它仍然可以使用同一文件中的其他预设。

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

模式 ¶

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

cmake-presets(7)¶

简介 ¶

格式 ¶

包含 ¶

配置预设 ¶

构建预设 ¶

测试预设 ¶

打包预设 ¶

工作流预设 ¶

条件 ¶

宏扩展 ¶

模式 ¶

目录

上一主题

下一主题

本页