Cmake封神之作：cmake-presets
章建木
简介¶
在使用 CMake 过程中，我们经常面临的一个问题是如何与其他人共享设置以获取配置项目的常用方法。这样做可以更好的支持 CI 构建，也可以使大多编译项目的人可以便捷的使用相同配置进行构建。 CMake （译者注：v3.19以上版本）支持两个主要配置文件： CMakePresets.json 和 CMakeUserPresets.json，用来支持用户指定常用配置选项并与他人共享。CMake 还支持包含在 include 字段中的文件（译者注：比如一个 presets 可以 include 另一个 presets 文件，需要注意的是 CMakeUserPresets.json 隐式包含 CMakePresets.json，且禁止循环包含，具体查看下文文档）。
CMakePresets.json 与 CMakeUserPresets.json 位于项目的根目录中。它们都具有完全相同的格式，并且都是可选的（尽管如果指定了 --preset 则二者至少必须存在一个）。 CMakePresets.json 旨在指定项目范围的构建细节，而 CMakeUserPresets.json 旨在让开发人员自定义他们自己的本地构建细节。
CMakePresets.json 可能会被检入版本控制系统（译者注：通常应该检入，这样CI可以使用默认配置，团队其他成员也一样），而 CMakeUserPresets.json 不应被检入。例如，如果项目正在使用 Git，则可能会跟踪 CMakePresets.json，并且应将 CMakeUserPresets.json 添加到 .gitignore .
presets相关的更新记录
-
cmake-presets(7)文件现在支持架构版本4。cmake-presets(7)文件现在有一个可选include字段，允许文件包含其他文件。cmake-presets(7)文件现在支持${fileDir}宏，其中包含包含预设文件的目录。cmake-presets(7)resolvePackageReferences获得了对在构建预设中指定命令行选项的支持，以控制来自外部包管理器的包引用的恢复行为。目前，这仅受 Visual Studio 生成器支持，以支持从 NuGet 还原包。其他生成器忽略此选项。
-
cmake-presets(7)获得了在配置预设中指定安装前缀的支持。cmake-presets(7)获得了对预设条件启用的支持。cmake-presets(7)获得了对${hostSystemName}宏的支持。cmake-presets(7)获得了省略generator和binaryDir字段的支持。
-
cmake-presets(7)获得了对构建和测试预设的支持。
-
cmake(1)cmake-gui(1)现在识别并归档（参见 参考资料CMakePresets.json）。CMakeUserPresets.jsoncmake-presets(7)
格式¶
这些文件是一个以对象为根的 JSON 文档：
{
"version": 4,
"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}
}
],
"vendor": {
"example.com/ExampleIDE/1.0": {
"autoFormat": false
}
}
}
根对象识别以下字段：
version
表示 JSON 模式版本的必需整数。支持的版本是`1`、`2`、`3`和`4`。
cmakeMinimumRequired
一个可选对象，表示构建此项目所需的最低 CMake 版本。该对象由以下字段组成：
`major`
表示主要版本的可选整数。
`minor`
表示次要版本的可选整数。
`patch`
表示补丁版本的可选整数。
include
表示要包含的文件的可选字符串数组。如果文件名不是绝对的，则它们被认为是相对于当前文件的。`4`这在指定版本或更高版本的预设文件中是允许的。有关包含文件的约束的讨论，请参见[包含。](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#includes)
vendor
包含供应商特定信息的可选映射。CMake 不解释此字段的内容，除非它确实存在验证它是否是一个映射。但是，密钥应该是供应商特定的域名，后跟 - 分隔的`/`路径。例如，示例 IDE 1.0 可以使用`example.com/ExampleIDE/1.0`. 每个字段的值可以是供应商所需的任何值，但通常是地图。
configurePresets
可选的[配置预设](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#configure-preset)对象数组。`1`这在指定版本或更高版本的预设文件中是允许的。
buildPresets
可选的[构建预设](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#build-preset)对象数组。`2`这在指定版本或更高版本的预设文件中是允许的。
testPresets
一个可选的[测试预设](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#test-preset)对象数组。`2`这在指定版本或更高版本的预设文件中是允许的。
包括¶
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可能包括来自任何地方的文件。
配置预设¶
数组的每个条目configurePresets都是一个 JSON 对象，可能包含以下字段：
name
表示预设的机器友好名称的必需字符串。此标识符用于[cmake --preset](https://cmake.org/cmake/help/latest/manual/cmake.1.html#cmake-options)选项。不能有两个配置预设在同名的并集`CMakePresets.json` 和`CMakeUserPresets.json`同一个目录下。但是，配置预设可能与构建或测试预设具有相同的名称。
hidden
一个可选的布尔值，指定是否应隐藏预设。如果预设是隐藏的，则不能在`--preset=`参数中使用，也不会显示在[`CMake GUI`](https://cmake.org/cmake/help/latest/manual/cmake-gui.1.html#manual:cmake-gui(1) "cmake-gui(1)"), 并且不必具有有效的`generator`or `binaryDir`, 甚至来自继承。`hidden`预设旨在用作其他预设通过`inherits`字段继承的基础。
inherits
一个可选的字符串数组，表示要继承的预设名称。该字段也可以是字符串，相当于一个包含一个字符串的数组。
默认情况下，预设将继承预设中的所有字段`inherits` （除了`name`、`hidden`、`inherits`、 `description`和`displayName`），但可以根据需要覆盖它们。如果多个`inherits`预设为同一字段提供冲突的值，则`inherits`列表中较早的预设将是首选。
预设只能从在同一文件或它包含的文件之一（直接或间接）中定义的另一个预设继承。中的预设`CMakePresets.json`可能不会从 中的预设继承 `CMakeUserPresets.json`。
condition
一个可选的[条件](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#condition)对象。`3`这在指定版本或更高版本的预设文件中是允许的。
vendor
包含供应商特定信息的可选映射。CMake 不解释此字段的内容，除非它确实存在验证它是否是一个映射。`vendor`但是，它应该遵循与根级别字段相同的约定。如果供应商使用他们自己的预置 `vendor`字段，他们应该在适当的时候以合理的方式实现继承。
displayName
具有人性化预设名称的可选字符串。
description
带有对预设的人性化描述的可选字符串。
generator
一个可选字符串，表示用于预设的生成器。如果 `generator`未指定，则必须继承自 `inherits`预设（除非此预设为`hidden`）。在版本`3` 或更高版本中，可以省略此字段以退回到常规生成器发现过程。
请注意，对于 Visual Studio 生成器，与命令行`-G` 参数不同，您不能在生成器名称中包含平台名称。请改用该`architecture`字段。
architecture,toolset
分别代表平台和工具集的可选字段，用于支持它们的生成器。每个都可以是字符串或具有以下字段的对象：
`value`
表示值的可选字符串。
`strategy`
一个可选字符串，告诉 CMake 如何处理`architecture`or `toolset`字段。有效值为：
`"set"`
设置相应的值。对于不支持相应字段的生成器，这将导致错误。
`"external"`
即使生成器支持，也不要设置该值。例如，如果预设使用 Ninja 生成器，并且 IDE 知道如何从 `architecture`和`toolset`字段设置 Visual C++ 环境，这将非常有用。在这种情况下，CMake 将忽略该字段，但 IDE 可以在调用 CMake 之前使用它们来设置环境。
toolchainFile
表示工具链文件路径的可选字符串。该字段支持[宏扩展](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#macro-expansion)。如果指定了相对路径，则相对于构建目录进行计算，如果未找到，则相对于源目录进行计算。该字段优先于任何 [`CMAKE_TOOLCHAIN_FILE`](https://cmake.org/cmake/help/latest/variable/CMAKE_TOOLCHAIN_FILE.html#variable:CMAKE_TOOLCHAIN_FILE "CMAKE_TOOLCHAIN_FILE")价值。在指定版本`3`或更高版本的预设文件中允许。
binaryDir
一个可选字符串，表示输出二进制目录的路径。该字段支持[宏扩展](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#macro-expansion)。如果指定了相对路径，则相对于源目录计算。如果`binaryDir`未指定，则必须继承自`inherits`预设（除非此预设为`hidden`）。在版本`3`或更高版本中，该字段可以省略。
installDir
表示安装目录路径的可选字符串。该字段支持[宏扩展](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#macro-expansion)。如果指定了相对路径，则相对于源目录计算。`3`这在指定版本或更高版本的预设文件中是允许的。
cmakeExecutable
一个可选字符串，表示用于此预设的 CMake 可执行文件的路径。这保留给 IDE 使用，CMake 本身不使用。使用此字段的 IDE 应扩展其中的所有宏。
cacheVariables
缓存变量的可选映射。键是变量名（可能不是空字符串），值是要么`null`，布尔值（相当于`"TRUE"`or的值`"FALSE"`和类型`BOOL`），表示变量值的字符串（支持[宏扩展](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#macro-expansion))，或具有以下字段的对象：
`type`
表示变量类型的可选字符串。
`value`
表示变量值的必需字符串或布尔值。布尔值等价于`"TRUE"`or `"FALSE"`。该字段支持[宏扩展](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#macro-expansion)。
缓存变量是通过`inherits`字段继承的，预设的变量将是它自己的`cacheVariables`并集，`cacheVariables`来自它所有的父母。如果此联合中的多个预设定义了相同的变量，`inherits`则应用标准规则。将变量设置为`null`会导致它不被设置，即使一个值是从另一个预设继承的。
environment
环境变量的可选映射。键是变量名（可能不是空字符串），值是或者`null`表示变量值的字符串。无论进程的环境是否给它一个值，都会设置每个变量。该字段支持[宏扩展](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#macro-expansion)，并且该map中的环境变量可以相互引用，并且可以以任意顺序列出，只要这样的引用不引起循环即可（例如，如果`ENV_1`是`$env{ENV_2}`，`ENV_2`可能不是`$env{ENV_1}`。）
环境变量是通过`inherits`字段继承的，预设的环境将是其自身`environment`和`environment`所有父级的并集。如果此联合中的多个预设定义了相同的变量，`inherits`则应用标准规则。将变量设置为`null`会导致它不被设置，即使一个值是从另一个预设继承的。
warnings
一个可选对象，指定要启用的警告。该对象可能包含以下字段：
`dev`
一个可选的布尔值。相当于通过`-Wdev`或`-Wno-dev` 在命令行上。`false`如果设置为 ，则可能不会`errors.dev` 设置为`true`。
`deprecated`
一个可选的布尔值。相当于通过`-Wdeprecated`或 `-Wno-deprecated`在命令行上。`false`如果设置为 ，则可能不会 `errors.deprecated`设置为`true`。
`uninitialized`
一个可选的布尔值。将此设置`true`为等效 `--warn-uninitialized`于在命令行上传递。
`unusedCli`
一个可选的布尔值。将此设置`false`为等效 `--no-warn-unused-cli`于在命令行上传递。
`systemVars`
一个可选的布尔值。将此设置`true`为等效 `--check-system-vars`于在命令行上传递。
errors
一个可选对象，指定要启用的错误。该对象可能包含以下字段：
`dev`
一个可选的布尔值。相当于通过`-Werror=dev`或 `-Wno-error=dev`在命令行上。`true` 如果设置为 ，则可能不会`warnings.dev`设置为`false`。
`deprecated`
一个可选的布尔值。相当于通过`-Werror=deprecated`或 `-Wno-error=deprecated`在命令行上。`true`如果设置为 ，则可能不会 `warnings.deprecated`设置为`false`。
debug
指定调试选项的可选对象。该对象可能包含以下字段：
`output`
一个可选的布尔值。将此设置`true`为等效 `--debug-output`于在命令行上传递。
`tryCompile`
一个可选的布尔值。将此设置`true`为等效 `--debug-trycompile`于在命令行上传递。
`find`
一个可选的布尔值。将此设置`true`为等效 `--debug-find`于在命令行上传递。
构建预设¶
数组的每个条目buildPresets都是一个 JSON 对象，可能包含以下字段：
name
表示预设的机器友好名称的必需字符串。此标识符用于 [cmake --build --preset](https://cmake.org/cmake/help/latest/manual/cmake.1.html#build-tool-mode)选项。同名目录`CMakePresets.json` 下不能有两个构建预设。`CMakeUserPresets.json`但是，构建预设可能与配置或测试预设具有相同的名称。
hidden
一个可选的布尔值，指定是否应隐藏预设。如果预设是隐藏的，则它不能在`--preset`参数中使用，并且不必具有有效的`configurePreset`，即使来自继承。`hidden`预设旨在用作其他预设通过`inherits`字段继承的基础。
inherits
一个可选的字符串数组，表示要继承的预设名称。该字段也可以是字符串，相当于一个包含一个字符串的数组。
默认情况下，预设将继承预设中的所有字段 `inherits`（除了`name`、`hidden`、 `inherits`、`description`和`displayName`），但可以根据需要覆盖它们。如果多个`inherits`预设为同一字段提供冲突的值，则`inherits`列表中较早的预设将是首选。
预设只能从在同一文件或它包含的文件之一（直接或间接）中定义的另一个预设继承。中的预设`CMakePresets.json`可能不会从 中的预设继承 `CMakeUserPresets.json`。
condition
一个可选的[条件](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#condition)对象。`3`这在指定版本或更高版本的预设文件中是允许的。
vendor
包含供应商特定信息的可选映射。CMake 不解释此字段的内容，除非它确实存在验证它是否是一个映射。`vendor`但是，它应该遵循与根级别字段相同的约定。如果供应商使用他们自己的预置 `vendor`字段，他们应该在适当的时候以合理的方式实现继承。
displayName
具有人性化预设名称的可选字符串。
description
带有对预设的人性化描述的可选字符串。
environment
环境变量的可选映射。键是变量名（可能不是空字符串），值是或者`null`表示变量值的字符串。无论进程的环境是否给它一个值，都会设置每个变量。该字段支持宏扩展，该map中的环境变量可以相互引用，并且可以按任意顺序列出，只要这样的引用不引起循环即可（例如，如果 `ENV_1`是`$env{ENV_2}`，`ENV_2`可能不是`$env{ENV_1}`。）
环境变量是通过`inherits`字段继承的，预设的环境将是其自身`environment` 和`environment`所有父级的并集。如果此联合中的多个预设定义了相同的变量，`inherits` 则应用标准规则。将变量设置为`null`会导致它不被设置，即使一个值是从另一个预设继承的。
笔记
对于使用 ExternalProject 的 CMake 项目，其配置预设具有 ExternalProject 中所需的环境变量，请使用继承该配置预设的构建预设，否则 ExternalProject 将不会在配置预设中设置环境变量。示例：假设主机默认使用一个编译器（例如 Clang），而用户希望使用另一个编译器（例如 GCC）。设置配置预设环境变量`CC`并`CXX`使用继承该配置预设的构建预设。否则，ExternalProject 可能使用与顶级 CMake 项目不同的（系统默认）编译器。
configurePreset
一个可选字符串，指定与此构建预设关联的配置预设的名称。如果`configurePreset`未指定，则必须继承自 inherits 预设（除非此预设被隐藏）。构建目录是从配置预设中推断出来的，因此构建将在与`binaryDir`配置相同的情况下进行。
inheritConfigureEnvironment
一个可选的布尔值，默认为 true。如果为 true，则关联配置预设中的环境变量在所有继承的构建预设环境之后继承，但在此构建预设中明确指定的环境变量之前。
jobs
一个可选的整数。相当于通过`--parallel`或`-j`在命令行上。
targets
可选字符串或字符串数组。相当于通过 `--target`或`-t`在命令行上。供应商可能会忽略目标属性或隐藏明确指定目标的构建预设。该字段支持宏扩展。
configuration
可选字符串。相当于`--config`在命令行上传递。
cleanFirst
一个可选的布尔值。如果为 true，则相当于`--clean-first`在命令行中传递。
resolvePackageReferences
指定包解析模式的可选字符串。`4`这在指定版本或更高版本的预设文件中是允许的。
包引用用于定义来自外部包管理器的包的依赖关系。目前仅支持 NuGet 与 Visual Studio 生成器的组合。如果没有定义包引用的目标，则此选项不执行任何操作。有效值为：
`on`
导致在尝试构建之前解析包引用。
`off`
包引用将不会被解析。请注意，这可能会在某些构建环境中导致错误，例如 .NET SDK 样式项目。
`only`
仅解析包引用，但不执行构建。
笔记
命令行参数`--resolve-package-references`将优先于此设置。如果未提供命令行参数并且未指定此设置，则将评估特定于环境的缓存变量以决定是否应执行包还原。
使用 Visual Studio 生成器时，包引用是使用[`VS_PACKAGE_REFERENCES`](https://cmake.org/cmake/help/latest/prop_tgt/VS_PACKAGE_REFERENCES.html#prop_tgt:VS_PACKAGE_REFERENCES "VS_PACKAGE_REFERENCES")财产。使用 NuGet 恢复包引用。可以通过将 `CMAKE_VS_NUGET_PACKAGE_RESTORE`变量设置为 来禁用它`OFF`。这也可以在配置预设中完成。
verbose
一个可选的布尔值。如果为 true，则相当于`--verbose`在命令行中传递。
nativeToolOptions
一个可选的字符串数组。相当于`--` 在命令行上传递选项。数组值支持宏扩展。
测试预设¶
数组的每个条目testPresets都是一个 JSON 对象，可能包含以下字段：
name
表示预设的机器友好名称的必需字符串。此标识符用于[ctest --preset](https://cmake.org/cmake/help/latest/manual/ctest.1.html#ctest-options)选项。同名目录`CMakePresets.json` 下不能有两个测试预设。`CMakeUserPresets.json`但是，测试预设可能与配置或构建预设具有相同的名称。
hidden
一个可选的布尔值，指定是否应隐藏预设。如果预设是隐藏的，则它不能在`--preset`参数中使用，并且不必具有有效的`configurePreset`，即使来自继承。`hidden`预设旨在用作其他预设通过`inherits`字段继承的基础。
inherits
一个可选的字符串数组，表示要继承的预设名称。该字段也可以是字符串，相当于一个包含一个字符串的数组。
默认情况下，预设将继承预设中的所有字段 `inherits`（除了`name`、`hidden`、 `inherits`、`description`和`displayName`），但可以根据需要覆盖它们。如果多个`inherits`预设为同一字段提供冲突的值，则`inherits`列表中较早的预设将是首选。
预设只能从在同一文件或它包含的文件之一（直接或间接）中定义的另一个预设继承。中的预设`CMakePresets.json`可能不会从 中的预设继承 `CMakeUserPresets.json`。
condition
一个可选的[条件](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#condition)对象。`3`这在指定版本或更高版本的预设文件中是允许的。
vendor
包含供应商特定信息的可选映射。CMake 不解释此字段的内容，除非它确实存在验证它是否是一个映射。`vendor`但是，它应该遵循与根级别字段相同的约定。如果供应商使用他们自己的预置 `vendor`字段，他们应该在适当的时候以合理的方式实现继承。
displayName
具有人性化预设名称的可选字符串。
description
带有对预设的人性化描述的可选字符串。
environment
环境变量的可选映射。键是变量名（可能不是空字符串），值是或者`null`表示变量值的字符串。无论进程的环境是否给它一个值，都会设置每个变量。该字段支持宏扩展，该map中的环境变量可以相互引用，并且可以按任意顺序列出，只要这样的引用不引起循环即可（例如，如果 `ENV_1`是`$env{ENV_2}`，`ENV_2`可能不是`$env{ENV_1}`。）
环境变量是通过`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`在命令行上传递。该字段支持宏扩展。
`labelSummary`
一个可选的布尔值。如果为 false，则相当于 `--no-label-summary`在命令行中传递。
`subprojectSummary`
一个可选的布尔值。如果为 false，则相当于 `--no-subproject-summary`在命令行中传递。
`maxPassedTestOutputSize`
一个可选整数，指定通过测试的最大输出（以字节为单位）。相当于`--test-output-size-passed`在命令行上传递。
`maxFailedTestOutputSize`
一个可选整数，以字节为单位指定失败测试的最大输出。相当于`--test-output-size-failed`在命令行上传递。
`maxTestNameWidth`
一个可选整数，指定要输出的测试名称的最大宽度。相当于`--max-width`在命令行上传递。
filter
一个可选对象，指定如何过滤要运行的测试。该对象可能包含以下字段。
`include`
一个可选对象，指定要包含的测试。该对象可能包含以下字段。
`name`
一个可选字符串，指定测试名称的正则表达式。相当于`--tests-regex`在命令行上传递。该字段支持宏扩展。CMake 正则表达式语法在 [string(REGEX)](https://cmake.org/cmake/help/latest/command/string.html#regex-specification)下描述。
`label`
一个可选字符串，指定测试标签的正则表达式。相当于`--label-regex`在命令行上传递。该字段支持宏扩展。
`useUnion`
一个可选的布尔值。相当于`--union`在命令行上传递。
`index`
一个可选对象，指定要按测试索引包含的测试。该对象可能包含以下字段。也可以是一个可选字符串，指定一个文件，其命令行语法为 `--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，则相当于 在命令行中传递。如果为 false，则相当于在命令行中传递。`--interactive-debug-mode 1``--interactive-debug-mode 0`
`scheduleRandom`
一个可选的布尔值。如果为 true，则相当于`--schedule-random` 在命令行中传递。
`timeout`
一个可选的整数。相当于`--timeout`在命令行上传递。
`noTestsAction`
如果未找到测试，则指定行为的可选字符串。必须是以下值之一：
`default`
相当于在命令行中不传递任何值。
`error`
相当于`--no-tests=error`在命令行上传递。
`ignore`
相当于`--no-tests=ignore`在命令行上传递。
条件¶
condition在指定版本或更高版本的预设文件中允许的预设字段 用于3确定是否启用预设。例如，这可用于在 Windows 以外的平台上禁用预设。 condition可以是布尔值null、 或对象。如果是布尔值，则布尔值指示预设是启用还是禁用。如果是null，则启用预设，但null条件不会被任何可能从预设继承的预设继承。子条件（例如在 a 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}
${sourceParentDir}
项目源目录的父目录的路径。
${sourceDirName}
的最后一个文件名组件`${sourceDir}`。例如，如果 `${sourceDir}`是`/path/to/source`，这将是`source`。
${presetName}
在预设`name`字段中指定的名称。
${generator}
在预设`generator`字段中指定的生成器。对于构建和测试预设，这将评估为由 `configurePreset`.
${hostSystemName}
${fileDir}
包含包含宏的预设文件的目录的路径。`4`这在指定版本或更高版本的预设文件中是允许的。
${dollar}
文字美元符号 ( `$`)。
$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 个字符）供应商标识符前缀，后跟 a `.`，然后是宏名称。例如，示例 IDE 可以具有`$vendor{xide.ideInstallDir}`.
架构¶
This file为该CMakePresets.json格式提供机器可读的 JSON 模式。
PS：其实也没有什么神不神的，就是觉得深得我心。
类似资料：