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 或更高的预设文件可以使用键 $comment 在 JSON 对象的任何级别中包含注释以提供文档。

根对象识别以下字段

$schema

一个可选的字符串，提供一个 URI 指向描述此 JSON 文档结构的 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 中的预设继承。

条件

一个可选的条件对象。这在指定版本 3 或更高版本的预设文件中允许。

vendor

一个可选的映射，包含特定于供应商的信息。除了验证它是一个映射（如果存在）之外，CMake 不解释此字段的内容。但是，它应该遵循与顶层 vendor 字段相同的约定。如果供应商使用他们自己的每个预设 vendor 字段，他们应该在适当的时候以明智的方式实现继承。

displayName

一个可选的字符串，包含预设的易于理解的名称。

description

一个可选的字符串，包含预设的易于理解的描述。

generator

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

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

architecture, toolset

可选字段，分别表示平台和工具集，用于 generators 支持它们。

有关 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

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

dev: 一个可选的布尔值。等效于在命令行上传递 -Wdev 或 -Wno-dev。如果 errors.dev 设置为 true，则它不能设置为 false。
deprecated: 可选布尔值。等效于在命令行中传递 -Wdeprecated 或 -Wno-deprecated。如果 errors.deprecated 设置为 true，则不能将其设置为 false。
未初始化: 可选布尔值。将其设置为 true 等效于在命令行中传递 --warn-uninitialized。
unusedCli: 可选布尔值。将其设置为 false 等效于在命令行中传递 --no-warn-unused-cli。
systemVars: 可选布尔值。将其设置为 true 等效于在命令行中传递 --check-system-vars。

errors

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

dev: 可选布尔值。等效于在命令行中传递 -Werror=dev 或 -Wno-error=dev。如果 warnings.dev 设置为 false，则不能将其设置为 true。
deprecated: 可选布尔值。等效于在命令行中传递 -Werror=deprecated 或 -Wno-error=deprecated。如果 warnings.deprecated 设置为 false，则不能将其设置为 true。

debug

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

output: 可选布尔值。将其设置为 true 等效于在命令行中传递 --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

必需的字符串，表示预设的机器友好名称。此标识符在 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 中的预设继承。

条件

一个可选的条件对象。这在指定版本 3 或更高版本的预设文件中允许。

vendor

一个可选的映射，包含特定于供应商的信息。除了验证它是一个映射（如果存在）之外，CMake 不解释此字段的内容。但是，它应该遵循与顶层 vendor 字段相同的约定。如果供应商使用他们自己的每个预设 vendor 字段，他们应该在适当的时候以明智的方式实现继承。

displayName

一个可选的字符串，包含预设的易于理解的名称。

description

一个可选的字符串，包含预设的易于理解的描述。

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 属性或隐藏明确指定目标的构建预设。该字段支持宏扩展。

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 对象，它可能包含以下字段

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 中的预设继承。

条件

一个可选的条件对象。这在指定版本 3 或更高版本的预设文件中允许。

vendor

一个可选的映射，包含特定于供应商的信息。除了验证它是一个映射（如果存在）之外，CMake 不解释此字段的内容。但是，它应该遵循与顶层 vendor 字段相同的约定。如果供应商使用他们自己的每个预设 vendor 字段，他们应该在适当的时候以明智的方式实现继承。

displayName

一个可选的字符串，包含预设的易于理解的名称。

description

一个可选的字符串，包含预设的易于理解的描述。

environment

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

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

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

configurePreset

一个可选的字符串，指定要与该测试预设关联的配置预设的名称。如果未指定 configurePreset，则必须从 inherits 预设继承它（除非此预设被隐藏）。构建目录是从配置预设推断出来的，因此测试将在与配置和构建相同的 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

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

name

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

label

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

useUnion

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

索引

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

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

exclude

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

name

一个可选的字符串，指定测试名称的正则表达式。等效于在命令行中传递 --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。该字符串必须是以下值之一

human

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 对象，可能包含以下字段

name

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

hidden

一个可选布尔值，指定预设是否应该隐藏。如果预设被隐藏，则无法在 --preset 参数中使用它，并且不需要具有有效的 configurePreset（即使是通过继承获得的）。 hidden 预设旨在用作其他预设通过 inherits 字段继承的基准。

inherits

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

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

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

条件

一个可选的条件对象。

vendor

一个可选的映射，包含特定于供应商的信息。除了验证它是一个映射（如果存在）之外，CMake 不解释此字段的内容。但是，它应该遵循与顶层 vendor 字段相同的约定。如果供应商使用他们自己的每个预设 vendor 字段，他们应该在适当的时候以明智的方式实现继承。

displayName

一个可选的字符串，包含预设的易于理解的名称。

description

一个可选的字符串，包含预设的易于理解的描述。

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，则在所有继承的包预设环境之后，但在此包预设中明确指定的环境变量之前，将继承关联的配置预设的环境变量。

generators

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

configurations

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

variables

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

configFile

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

output

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

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

packageName

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

packageVersion

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

packageDirectory

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

vendorName

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

工作流程预设 ¶

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

name

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

vendor

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

displayName

一个可选的字符串，包含预设的易于理解的名称。

description

一个可选的字符串，包含预设的易于理解的描述。

steps

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

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

条件 ¶

在指定版本 3 或更高版本的预设文件中，预设的 condition 字段用于确定预设是否启用。例如，这可以用于在除 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"

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

条件: 一个必填的条件对象。

宏展开 ¶

如上所述，某些字段支持宏展开。宏以 $<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)¶

简介 ¶

格式 ¶

包含 ¶

配置预设 ¶

构建预设 ¶

测试预设 ¶

包预设 ¶

工作流程预设 ¶

条件 ¶

宏展开 ¶

模式 ¶

目录

上一主题

下一主题

此页面