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 可以使用 include 字段包含其他文件（在文件版本 4 及以后）。通过这些文件包含的文件也可以包含其他文件。如果 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（即使是从继承中获得的）。隐藏的预设旨在通过 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 输入文件的路径，该文件将包含项目中所有库和可执行文件的依赖项。有关更多详细信息，请参阅 cmake --graphviz 的文档。

此字段支持宏展开。如果指定了相对路径，则该路径相对于当前工作目录计算。此字段允许在指定版本 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: 一个可选的布尔值。将其设置为 true 等同于在命令行上传递 --debug-output。
tryCompile: 一个可选的布尔值。将其设置为 true 等同于在命令行上传递 --debug-trycompile。
find: 一个可选的布尔值。将其设置为 true 等同于在命令行上传递 --debug-find。

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（即使是从继承中获得的）。隐藏的预设旨在通过 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（即使是从继承中获得的）。隐藏的预设旨在通过 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

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

any: 一个可选的字符串，指定要从添加任何测试的 fixture 中排除的文本 fixture 的正则表达式。等同于命令行上的 --fixture-exclude-any。此字段支持宏展开。
setup: 一个可选的字符串，指定要从添加设置测试的 fixture 中排除的文本 fixture 的正则表达式。等同于命令行上的 --fixture-exclude-setup。此字段支持宏展开。
cleanup: 一个可选的字符串，指定要从添加清理测试的 fixture 中排除的文本 fixture 的正则表达式。等同于命令行上的 --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（即使是从继承中获得的）。隐藏的预设旨在通过 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

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

注意

由于实现问题，此字段不会影响最终生成的包文件的名称。包的其他方面可能会使用此值，从而导致不一致。将来的 CMake 版本可能会解决此问题，但在此之前，建议不要使用此字段。

packageVersion

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

注意

由于实现问题，此字段不会影响最终生成的包文件的名称。包的其他方面可能会使用此值，从而导致不一致。将来的 CMake 版本可能会解决此问题，但在此之前，建议不要使用此字段。

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/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}。

模式 ¶

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

cmake-presets(7)¶

简介 ¶

格式 ¶

包含 ¶

配置预设 ¶

构建预设 ¶

测试预设 ¶

打包预设 ¶

工作流预设 ¶

条件 ¶

宏展开 ¶

模式 ¶

目录

上一主题

下一主题

本页