cmake 预设 (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": 6,
  "cmakeMinimumRequired": {
    "major": 3,
    "minor": 23,
    "patch": 0
  },
  "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",
      "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
    }
  }
}

根对象识别以下字段：

版本

表示 JSON 架构版本的必需整数。支持的版本是：

1: 在 3.19 版本加入.
2: 在 3.20 版本加入.
3: 在 3.21 版本加入.
4: 在 3.23 版本加入.
5: 在 3.24 版本加入.
6: 在 3.25 版本加入.

cmakeMinimumRequired

一个可选对象，表示构建此项目所需的最低 CMake 版本。该对象由以下字段组成：

主要: 代表主要版本的可选整数。
未成年人: 代表次要版本的可选整数。
补丁: 表示补丁版本的可选整数。

包括

一个可选的字符串数组，表示要包含的文件。如果文件名不是绝对的，则它们被认为是相对于当前文件的。这在指定版本“4”或更高版本的预设文件中是允许的。有关包含文件的约束的讨论，请参阅“包含”。

供应商

包含供应商特定信息的可选映射。 CMake 不解释此字段的内容，除非它是一个映射（如果它确实存在）。但是，密钥应该是特定于供应商的域名，后跟“/”分隔的路径。例如，示例 IDE 1.0 可以使用 example.com/ExampleIDE/1.0。每个字段的值可以是供应商想要的任何值，但通常是地图。

配置预设

Configure Preset 对象的可选数组。这在指定版本“1”或更高版本的预设文件中是允许的。

buildPresets

Build Preset 对象的可选数组。这在指定版本“2”或更高版本的预设文件中是允许的。

测试预设

可选的“测试预设”对象数组。这在指定版本“2”或更高版本的预设文件中是允许的。

packagePresets

一个可选的 Package Preset 对象数组。这在指定版本“6”或更高版本的预设文件中是允许的。

workflowPresets

Workflow Preset 对象的可选数组。这在指定版本“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 可能包含来自任何地方的文件。

配置预设 ¶

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

名字

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

隐藏

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

继承

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

默认情况下，预设将继承“inherits”预设中的所有字段（“name”、“hidden”、“inherits”、“description”和“displayName”除外） ), 但可以根据需要覆盖它们。如果多个 inherits 预设为同一字段提供冲突的值，则 inherits 数组中较早的预设将是首选。

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

条件

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

供应商

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

显示名称

带有人性化预设名称的可选字符串。

描述

一个可选的字符串，带有对预设的人性化描述。

生成器

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

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

架构，工具集

代表平台和工具集的可选字段，分别用于:manual:generators <cmake-generators(7)> 支持它们。

请参阅:option:cmake -A 选项以了解 architecture 的可能值和 cmake -T 用于 toolset 。

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

价值

表示值的可选字符串。

策略

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

“设置”: 设置相应的值。对于不支持相应字段的生成器，这将导致错误。
“外部”: 不要设置该值，即使生成器支持它。例如，如果预设使用 Ninja 生成器，并且 IDE 知道如何从 architecture 和 toolset 字段设置 Visual C++ 环境，这将很有用。在这种情况下，CMake 将忽略该字段，但 IDE 可以使用它们在调用 CMake 之前设置环境。

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

工具链文件

表示工具链文件路径的可选字符串。该字段支持`宏扩展`_。如果指定了相对路径，则相对于构建目录进行计算，如果找不到，则相对于源目录进行计算。该字段优先于任何 CMAKE_TOOLCHAIN_FILE 值。在指定版本“3”或更高版本的预设文件中是允许的。

binaryDir

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

安装目录

表示安装目录路径的可选字符串。该字段支持`宏扩展`_。如果指定了相对路径，则它是相对于源目录计算的。这在指定版本“3”或更高版本的预设文件中是允许的。

cmakeExecutable

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

缓存变量

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

类型: 表示变量类型的可选字符串。
价值: 表示变量值的必需字符串或布尔值。布尔值等同于“真”或“假”。该字段支持`宏扩展`_。

缓存变量通过 inherits 字段继承，preset 的变量将是它自己的 cacheVariables 和来自其所有父项的 cacheVariables 的联合。如果此联合中的多个预设定义相同的变量，则应用“继承”的标准规则。将变量设置为“null”会导致它不被设置，即使值是从另一个预设继承的。

环境

环境变量的可选映射。键是变量名（可能不是空字符串），值是“null”或表示变量值的字符串。无论进程环境是否给它赋值，每个变量都会被设置。该字段支持`宏扩展`_，并且该映射中的环境变量可以相互引用，并且可以以任意顺序列出，只要这样的引用不会导致循环（例如，如果``ENV_1``是` $env{ENV_2}`，ENV_2 可能不是 $env{ENV_1}。）

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

警告

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

开发: 一个可选的布尔值。相当于在命令行上传递 -Wdev 或 -Wno-dev。如果 errors.dev 设置为 true，则不能设置为 false。
已弃用: 一个可选的布尔值。相当于在命令行上传递 -Wdeprecated 或 -Wno-deprecated。如果 errors.deprecated 设置为 true，则不能设置为 false。
未初始化: 一个可选的布尔值。将此设置为 true 相当于在命令行上传递:option:--warn-uninitialized <cmake --warn-uninitialized>。
unusedCli: 一个可选的布尔值。将此设置为 false 相当于在命令行上传递:option:--no-warn-unused-cli <cmake --no-warn-unused-cli>。
系统变量: 一个可选的布尔值。将此设置为 true 相当于在命令行上传递:option:--check-system-vars <cmake --check-system-vars>。

错误

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

开发: 一个可选的布尔值。相当于在命令行上传递 -Werror=dev 或 -Wno-error=dev。如果 warnings.dev 设置为 false，这可能不会设置为 true。
已弃用: 一个可选的布尔值。相当于在命令行上传递 -Werror=deprecated 或 -Wno-error=deprecated。如果 warnings.deprecated 设置为 false，这可能不会设置为 true。

调试

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

输出: 一个可选的布尔值。将此设置为 true 相当于在命令行上传递:option:--debug-output <cmake --debug-output>。
尝试编译: 一个可选的布尔值。将此设置为 true 相当于在命令行上传递:option:--debug-trycompile <cmake --debug-trycompile>。
找到: 一个可选的布尔值。将此设置为 true 相当于在命令行上传递:option:--debug-find <cmake --debug-find>。

构建预设 ¶

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

名字

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

隐藏

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

继承

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

默认情况下，预设将继承“inherits”预设中的所有字段（“name”、“hidden”、“inherits”、“description”和“displayName”除外） ), 但可以根据需要覆盖它们。如果多个 inherits 预设为同一字段提供冲突的值，则 inherits 数组中较早的预设将是首选。

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

条件

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

供应商

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

显示名称

带有人性化预设名称的可选字符串。

描述

一个可选的字符串，带有对预设的人性化描述。

环境

环境变量的可选映射。键是变量名（可能不是空字符串），值是“null”或表示变量值的字符串。无论进程环境是否给它赋值，每个变量都会被设置。该字段支持宏扩展，该映射中的环境变量可以相互引用，并且可以以任意顺序列出，只要这样的引用不会导致循环（例如，如果 ENV_1 是 $env {ENV_2}，ENV_2 可能不是``$env{ENV_1}``。）

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

备注

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

配置预设

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

继承配置环境

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

工作

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

目标

一个可选的字符串或字符串数组。相当于在命令行上传递:option:--target <cmake--build --target> 或 -t。供应商可能会忽略目标属性或隐藏明确指定目标的构建预设。该字段支持宏扩展。

配置

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

cleanFirst

一个可选的布尔值。如果为真，相当于在命令行上传递:option:--clean-first <cmake--build --clean-first>。

resolvePackageReferences

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

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

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

备注

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

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

冗长

一个可选的布尔值。如果为真，相当于在命令行上传递 --verbose。

nativeToolOptions

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

测试预设 ¶

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

名字

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

隐藏

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

继承

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

默认情况下，预设将继承“inherits”预设中的所有字段（“name”、“hidden”、“inherits”、“description”和“displayName”除外） ), 但可以根据需要覆盖它们。如果多个 inherits 预设为同一字段提供冲突的值，则 inherits 数组中较早的预设将是首选。

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

条件

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

供应商

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

显示名称

带有人性化预设名称的可选字符串。

描述

一个可选的字符串，带有对预设的人性化描述。

环境

环境变量的可选映射。键是变量名（可能不是空字符串），值是“null”或表示变量值的字符串。无论进程环境是否给它赋值，每个变量都会被设置。该字段支持宏扩展，该映射中的环境变量可以相互引用，并且可以以任意顺序列出，只要这样的引用不会导致循环（例如，如果 ENV_1 是 $env {ENV_2}，ENV_2 可能不是``$env{ENV_1}``。）

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

配置预设

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

继承配置环境

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

配置

一个可选的字符串。相当于在命令行上传递 --build-config。

覆盖配置文件

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

输出

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

shortProgress

一个可选的布尔值。如果为真，相当于在命令行上传递:option:--progress <ctest --progress>。

冗长

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

默认: 相当于在命令行上不传递详细信息标志。
冗长: 相当于在命令行上传递 --verbose。
额外的: 相当于在命令行上传递:option:--extra-verbose <ctest --extra-verbose>。

调试

一个可选的布尔值。如果为真，相当于在命令行上传递 --debug。

outputOnFailure

一个可选的布尔值。如果为真，相当于在命令行上传递:option:--output-on-failure <ctest --output-on-failure>。

安静

一个可选的布尔值。如果为真，相当于在命令行上传递 --quiet。

输出日志文件

一个可选的字符串，指定日志文件的路径。相当于在命令行上传递:option:--output-log <ctest --output-log>。该字段支持宏扩展。

outputJUnitFile

指定 JUnit 文件路径的可选字符串。相当于在命令行上传递:option:--output-junit <ctest --output-junit>。该字段支持宏扩展。这在指定版本“6”或更高版本的预设文件中是允许的。

标签摘要

一个可选的布尔值。如果为假，相当于在命令行上传递:option:--no-label-summary <ctest --no-label-summary>。

子项目摘要

一个可选的布尔值。如果为 false，相当于在命令行上传递:option:--no-subproject-summary <ctest --no-subproject-summary>。

maxPassedTestOutputSize

一个可选的整数，以字节为单位指定通过测试的最大输出。相当于在命令行上传递:option:--test-output-size-passed <ctest --test-output-size-passed>。

maxFailedTestOutputSize

一个可选的整数，以字节为单位指定失败测试的最大输出。相当于在命令行上传递:option:--test-output-size-failed <ctest --test-output-size-failed>。

testOutputTruncation

指定测试输出截断模式的可选字符串。相当于在命令行上传递:option:--test-output-truncation <ctest --test-output-truncation>。这在指定版本“5”或更高版本的预设文件中是允许的。

maxTestNameWidth

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

过滤器

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

包括

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

名字

一个可选的字符串，指定测试名称的正则表达式。相当于在命令行上传递:option:--tests-regex <ctest --tests-regex>。该字段支持宏扩展。 CMake 正则表达式语法在 string(REGEX) 下描述。

标签

一个可选的字符串，指定测试标签的正则表达式。相当于在命令行上传递:option:--label-regex <ctest --label-regex>。该字段支持宏扩展。

使用联合

一个可选的布尔值。相当于在命令行上传递 --union。

索引

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

开始: 一个可选的整数，指定开始测试的测试索引。
结束: 一个可选的整数，指定要停止测试的测试索引。
大步走: 指定增量的可选整数。
具体测试: 一个可选的整数数组，指定要运行的特定测试索引。

排除

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

名字

一个可选的字符串，指定测试名称的正则表达式。相当于在命令行上传递:option:--exclude-regex <ctest --exclude-regex>。该字段支持宏扩展。

标签

一个可选的字符串，指定测试标签的正则表达式。相当于在命令行上传递:option:--label-exclude <ctest --label-exclude>。该字段支持宏扩展。

固定装置

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

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

执行

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

stopOnFailure

一个可选的布尔值。如果为真，相当于在命令行上传递:option:--stop-on-failure <ctest --stop-on-failure>。

启用故障转移

一个可选的布尔值。如果为真，相当于在命令行上传递:option:-F <ctest -F>。

工作

一个可选的整数。相当于在命令行上传递 --parallel。

resourceSpecFile

一个可选的字符串。相当于在命令行上传递:option:--resource-spec-file <ctest --resource-spec-file>。该字段支持宏扩展。

测试负载

一个可选的整数。相当于在命令行上传递:option:--test-load <ctest --test-load>。

仅显示

一个可选的字符串。相当于在命令行上传递:option:--show-only <ctest --show-only>。该字符串必须是以下值之一：

人类

json-v1

重复

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

模式

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

直到失败

直到通过

超时后

计数

必需的整数。

交互式调试

一个可选的布尔值。如果为真，相当于在命令行上传递:option:--interactive-debug-mode 1 <ctest --interactive-debug-mode>。如果为 false，相当于在命令行上传递 --interactive-debug-mode 0。

scheduleRandom

一个可选的布尔值。如果为真，相当于在命令行上传递:option:--schedule-random <ctest --schedule-random>。

超时

一个可选的整数。相当于在命令行上传递 --timeout。

noTestsAction

如果没有找到测试，则指定行为的可选字符串。必须是以下值之一：

默认: 相当于在命令行不传递任何值。
错误: 相当于在命令行上传递 --no-tests=error。
忽略: 相当于在命令行上传递 --no-tests=ignore。

包预设 ¶

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

名字

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

隐藏

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

继承

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

默认情况下，预设将继承“inherits”预设中的所有字段（“name”、“hidden”、“inherits”、“description”和“displayName”除外） ), 但可以根据需要覆盖它们。如果多个 inherits 预设为同一字段提供冲突的值，则 inherits 数组中较早的预设将是首选。

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

条件

一个可选的“条件”对象。

供应商

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

显示名称

带有人性化预设名称的可选字符串。

描述

一个可选的字符串，带有对预设的人性化描述。

环境

环境变量的可选映射。键是变量名（可能不是空字符串），值是“null”或表示变量值的字符串。无论进程环境是否给它赋值，每个变量都会被设置。该字段支持宏扩展，该映射中的环境变量可以相互引用，并且可以以任意顺序列出，只要这样的引用不会导致循环（例如，如果 ENV_1 是 $env {ENV_2}，ENV_2 可能不是``$env{ENV_1}``。）

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

配置预设

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

继承配置环境

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

生成器

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

配置

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

变量

要传递给 CPack 的可选变量映射，相当于:option:-D <cpack -D> 参数。每个键是一个变量的名称，值是分配给该变量的字符串。

配置文件

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

输出

指定输出选项的可选对象。有效键是：

调试: 一个可选的布尔值，指定是否打印调试信息。 true 的值相当于在命令行上传递:option:--debug <cpack --debug>。
冗长: 一个可选的布尔值，指定是否详细打印。 true 的值相当于在命令行上传递:option:--verbose <cpack --verbose>。

包名

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

包版本

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

包目录

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

供应商名称

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

工作流程预设 ¶

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

名字

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

显示名称

带有人性化预设名称的可选字符串。

描述

一个可选的字符串，带有对预设的人性化描述。

步骤

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

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

健康）状况 ¶

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

类型

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

“常量”

表示条件不变。这相当于使用布尔值代替对象。条件对象将具有以下附加字段：

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

“等于”

“不等于”

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

lhs: 要比较的第一个字符串。该字段支持宏扩展。
右手边: 要比较的第二个字符串。该字段支持宏扩展。

“在列表中”

“notInList”

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

字符串: 要搜索的必需字符串。该字段支持宏扩展。
列表: 要搜索的必需字符串数组。该字段支持宏扩展，并使用短路评估。

“匹配”

“不匹配”

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

字符串: 要搜索的必需字符串。该字段支持宏扩展。
正则表达式: 要搜索的必需正则表达式。该字段支持宏扩展。

“任何”

“全部”

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

条件
必需的条件对象数组。这些条件使用短路评估。

“不是”

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

条件: 必需的条件对象。

宏扩展 ¶

上面说了一些字段支持宏扩展。宏以 $<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}

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

${生成器}

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

${hostSystemName}

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

${fileDir}

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

${美元}

文字美元符号 ($)。

${pathListSep}

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

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

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

$env{<变量名>}

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

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

$penv{<变量名>}

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

$供应商{<宏名称>}

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

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

图式 ¶

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

cmake 预设 (7)¶

介绍 ¶

格式 ¶

包括 ¶

配置预设 ¶

构建预设 ¶

测试预设 ¶

包预设 ¶

工作流程预设 ¶

健康）状况 ¶

宏扩展 ¶

图式 ¶

目录

上一主题

下一主题

本页