cmake-presets(7)¶

介绍 ¶

3.19 版本新增。

CMake 用户经常面临的一个问题是如何与他人共享项目配置的常用设置。这可能是为了支持 CI 构建，或者是为了方便频繁使用相同构建方式的用户。CMake 支持两个主要文件，CMakePresets.json 和 CMakeUserPresets.json，允许用户指定常用的配置选项并与他人共享。

在预设版本 4 中添加：CMake 还支持通过 include 字段包含的文件。详情请参阅包含 (Includes)。

CMakePresets.json 和 CMakeUserPresets.json 位于项目的根目录下。它们的格式完全相同，且均为可选（但如果指定了 --preset，则至少必须存在其中一个）。CMakePresets.json 旨在指定项目范围的构建细节，而 CMakeUserPresets.json 旨在让开发人员指定其本地构建细节。

CMakePresets.json 可以提交到版本控制系统，而 CMakeUserPresets.json 不应提交。例如，如果项目使用 Git，则可以跟踪 CMakePresets.json，并将 CMakeUserPresets.json 添加到 .gitignore 中。

在版本 4.4 中添加：CMake 还支持通过 --presets-file 选项指定读取预设的文件。如果指定了此选项，则不需要存在 CMakePresets.json 或 CMakeUserPresets.json，且定义在这些文件中的任何预设将被忽略/不可用。

格式 ¶

这些文件是以对象为根的 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: 在预设版本 8 中添加。

一个可选字符串，提供一个 URI，指向描述此 JSON 文档结构的 JSON 架构 (schema)。此字段用于支持 JSON 架构的编辑器中的验证和自动补全。它不影响文档本身的行为。如果未指定此字段，JSON 文档仍然有效，但使用 JSON 架构进行验证和自动补全的工具可能无法正常工作。

版本: 一个必填整数，代表 JSON 架构的版本。关于支持的版本及其对应的 CMake 添加版本，请参阅版本 (Versions)。

cmakeMinimumRequired

一个可选对象，代表构建此项目所需的 CMake 最低版本。该对象包含以下字段

主要版本: 一个可选整数，代表主版本号。

次要版本: 一个可选整数，代表次版本号。

patch: 一个可选整数，代表修订版本号。

include: 在预设版本 4 中添加。

一个可选的字符串数组，代表要包含的文件。如果文件名不是绝对路径，则被视为相对于当前文件的路径。关于包含文件的约束，请参阅包含 (Includes)。

vendor: 一个可选的映射 (map)，包含供应商特定信息。CMake 不解析此字段的内容，仅在存在时验证其是否为映射。然而，键应为供应商特定的域名，后接由 / 分隔的路径。例如，Example IDE 1.0 可以使用 example.com/ExampleIDE/1.0。每个字段的值可以是供应商需要的任何内容，但通常是一个映射。

configurePresets: 一个可选的配置预设 (Configure Preset) 对象数组。

buildPresets: 在预设版本 2 中添加。

一个可选的构建预设 (Build Preset) 对象数组。

testPresets: 在预设版本 2 中添加。

一个可选的测试预设 (Test Preset) 对象数组。

packagePresets: 在预设版本 6 中添加。

一个可选的打包预设 (Package Preset) 对象数组。

workflowPresets: 在预设版本 6 中添加。

一个可选的工作流预设 (Workflow Preset) 对象数组。

包含 ¶

在预设版本 4 中添加。

CMake 预设文件可以使用 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 中更改：include 字段支持宏展开，但 $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 中添加。

一个可选的条件 (Condition) 对象。

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

displayName: 一个可选字符串，为预设提供人类友好的名称。

描述: 一个可选字符串，为预设提供人类友好的描述。

generator

一个可选字符串，代表该预设要使用的 generator (生成器)。

在预设版本 3 中更改：如果省略，CMake 将回退到常规的生成器发现程序。在之前的版本中，如果未指定，此字段必须从 inherits 预设中继承（除非此预设是 hidden）。

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

architecture

可选字段，代表支持它的 generators 的平台。

可能的值请参阅 cmake -A。

architecture 可以是一个字符串，也可以是一个包含以下字段的对象

value: 一个可选字符串，代表值。

strategy

一个可选字符串，告知 CMake 如何处理该字段。有效值为

"set": 设置相应的值。对于不支持相应字段的生成器，这将导致错误。
"external": 即使生成器支持，也不设置该值。这在例如预设使用 Ninja 生成器，且 IDE 知道如何根据 architecture 和 toolset 字段设置 Visual C++ 环境时非常有用。在这种情况下，CMake 将忽略该字段，但 IDE 可以在调用 CMake 之前使用它们来设置环境。

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

toolset

可选字段，代表支持它的 generators 的工具集 (toolset)。

可能的值请参阅 cmake -T。

toolset 可以是一个字符串，也可以是一个包含以下字段的对象

value: 一个可选字符串，代表值。

strategy

一个可选字符串，告知 CMake 如何处理该字段。有效值为

"set": 设置相应的值。对于不支持相应字段的生成器，这将导致错误。
"external": 即使生成器支持，也不设置该值。这在例如预设使用 Ninja 生成器，且 IDE 知道如何根据 architecture 和 toolset 字段设置 Visual C++ 环境时非常有用。在这种情况下，CMake 将忽略该字段，但 IDE 可以在调用 CMake 之前使用它们来设置环境。

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

toolchainFile: 在预设版本 3 中添加。

一个可选字符串，表示工具链文件的路径。此字段支持宏展开。如果指定了相对路径，则相对于构建目录计算；如果未找到，则相对于源目录计算。此字段的优先级高于任何 CMAKE_TOOLCHAIN_FILE 的值。

graphviz

在 presets 版本 10 中添加。

一个可选字符串，表示 graphviz 输入文件的路径，该文件将包含项目中所有的库和可执行文件依赖项。详见 cmake --graphviz 的文档以获取更多详情。

此字段支持宏展开。如果指定了相对路径，则相对于当前工作目录计算。

binaryDir: 一个可选字符串，表示输出二进制目录的路径。此字段支持宏展开。如果指定了相对路径，则相对于源目录计算。

在 presets 版本 3 中更改：如果省略，CMake 将使用常规方法计算路径。在之前的版本中，如果未指定，此字段必须从 inherits 预设中继承（除非此预设是 hidden）。

installDir: 在预设版本 3 中添加。

一个可选字符串，表示安装目录的路径，该路径将用作 CMAKE_INSTALL_PREFIX 变量。此字段支持宏展开。如果指定了相对路径，则相对于源目录计算。

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

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

author: 在 presets 版本 12 中添加。

一个可选布尔值。等同于在命令行传递 -Wauthor 或 -Wno-author。如果 errors.author 被设置为 true，则此项不能设置为 false。

已弃用: 一个可选布尔值。等同于在命令行传递 -Wdeprecated 或 -Wno-deprecated。如果 errors.deprecated 被设置为 true，则此项不能设置为 false。

开发: 在 presets 版本 12 中移除。

一个可选布尔值。等同于在命令行传递 -Wdev 或 -Wno-dev。如果 errors.dev 被设置为 true，则此项不能设置为 false。

experimental: 在 presets 版本 12 中添加。

一个可选布尔值。等同于在命令行传递 -Wexperimental 或 -Wno-experimental。如果 errors.experimental 被设置为 true，则此项不能设置为 false。

installAbsoluteDestination: 在 presets 版本 12 中添加。

一个可选布尔值。等同于在命令行传递 -Winstall-absolute-destination 或 -Wno-install-absolute-destination。如果 errors.installAbsoluteDestination 被设置为 true，则此项不能设置为 false。

policy: 在 presets 版本 12 中添加。

一个可选布尔值。等同于在命令行传递 -Wpolicy 或 -Wno-policy。如果 errors.policy 被设置为 true，则此项不能设置为 false。

uninitialized: 一个可选布尔值。等同于在命令行传递 -Wuninitialized 或 -Wno-uninitialized。如果 errors.uninitialized 被设置为 true，则此项不能设置为 false。

unusedCli: 一个可选布尔值。等同于在命令行传递 -Wunused-cli 或 -Wno-unused-cli。如果 errors.unusedCli 被设置为 true，则此项不能设置为 false。

systemVars: 一个可选布尔值。将其设置为 true 等同于在命令行传递 --check-system-vars。

errors

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

author: 在 presets 版本 12 中添加。

一个可选布尔值。等同于在命令行传递 -Werror=author 或 -Wno-error=author。如果 warnings.author 被设置为 false，则此项不能设置为 true。

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

开发: 在 presets 版本 12 中移除。

一个可选布尔值。等同于在命令行传递 -Werror=dev 或 -Wno-error=dev。如果 warnings.dev 被设置为 false，则此项不能设置为 true。

experimental: 在 presets 版本 12 中添加。

一个可选布尔值。等同于在命令行传递 -Werror=experimental 或 -Wno-error=experimental。如果 warnings.experimental 被设置为 false，则此项不能设置为 true。

installAbsoluteDestination: 在 presets 版本 12 中添加。

一个可选布尔值。等同于在命令行传递 -Werror=install-absolute-destination 或 -Wno-error=install-absolute-destination。如果 warnings.installAbsoluteDestination 被设置为 false，则此项不能设置为 true。

policy: 在 presets 版本 12 中添加。

一个可选布尔值。等同于在命令行传递 -Werror=policy 或 -Wno-error=policy。如果 warnings.policy 被设置为 false，则此项不能设置为 true。

uninitialized: 在 presets 版本 12 中添加。

一个可选布尔值。等同于在命令行传递 -Werror=uninitialized 或 -Wno-error=uninitialized。如果 warnings.uninitialized 被设置为 false，则此项不能设置为 true。

unusedCli: 在 presets 版本 12 中添加。

一个可选的布尔值。相当于在命令行中传递 -Werror=unused-cli 或 -Wno-error=unused-cli。如果 warnings.unusedCli 被设置为 false，则此项不能设置为 true。

debug

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

output: 一个可选的布尔值。将其设置为 true 相当于在命令行中传递 --debug-output。

tryCompile: 一个可选的布尔值。将其设置为 true 相当于在命令行中传递 --debug-trycompile。

find: 一个可选的布尔值。将其设置为 true 相当于在命令行中传递 --debug-find。

trace

在 presets 版本 7 中添加。

一个可选的对象，用于指定追踪选项。该对象可包含以下字段

mode

一个可选的字符串，用于指定追踪模式。有效值为

on: 导致打印所有调用及其来源的追踪记录。相当于在命令行中传递 --trace。
off: 不打印所有调用的追踪记录。
expand: 导致打印所有调用及其来源的追踪记录，并展开变量。相当于在命令行中传递 --trace-expand。

format

一个可选的字符串，用于指定追踪记录的输出格式。有效值为

人工: 以人类可读的格式打印每行追踪记录。这是默认格式。相当于在命令行中传递 --trace-format=human。
json-v1: 将每行作为单独的 JSON 文档打印。相当于在命令行中传递 --trace-format=json-v1。

源: 一个可选的字符串数组，表示要追踪的源文件路径。此字段也可以是一个字符串，相当于包含一个字符串的数组。相当于在命令行中传递 --trace-source。

redirect: 一个可选的字符串，指定追踪输出文件的路径。相当于在命令行中传递 --trace-redirect。

构建预设 (Build Preset)¶

在预设版本 2 中添加。

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

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

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

inherits

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

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

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

condition: 在预设版本 3 中添加。

一个可选的条件 (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 会导致该变量不被设置，即使它从另一个预设中继承了值。

注意

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

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

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

jobs: 一个可选的整数。相当于在命令行中传递 --parallel 或 -j。如果值为 0，则相当于传递 --parallel 但省略了 <jobs>；或者，可以使用 environment 字段将环境变量 CMAKE_BUILD_PARALLEL_LEVEL 定义为空字符串。

在版本 4.3 中更改：无论 presets 文件的版本如何，此字段均不接受负整数值。

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

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

cleanFirst: 一个可选的布尔值。如果为 true，相当于在命令行中传递 --clean-first。

resolvePackageReferences

在预设版本 4 中添加。

一个可选的字符串，用于指定包解析模式。

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

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

注意

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

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

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

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

测试预设 (Test Preset)¶

在预设版本 2 中添加。

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

名称: 一个必需的字符串，表示该预设的机器友好名称。此标识符用于 ctest --preset 选项。在同一目录下的 CMakePresets.json 和 CMakeUserPresets.json 的并集中，不得有两个同名的测试预设。但是，测试预设可以与配置 (configure)、构建 (build)、打包 (package) 或工作流 (workflow) 预设同名。

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

inherits

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

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

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

condition: 在预设版本 3 中添加。

一个可选的条件 (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，则在所有继承的测试预设环境之后，但在本测试预设中明确指定的环境变量之前，继承来自相关配置预设的环境变量。

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: 在预设版本 6 中添加。

一个可选的指定 JUnit 文件路径的字符串。相当于在命令行中传递 --output-junit。此字段支持宏展开。

labelSummary: 一个可选的布尔值。如果为 false，相当于在命令行中传递 --no-label-summary。

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

maxPassedTestOutputSize: 一个可选的整数，指定通过测试的最大输出字节数。相当于在命令行中传递 --test-output-size-passed。

maxFailedTestOutputSize: 一个可选的整数，指定失败测试的最大输出字节数。相当于在命令行中传递 --test-output-size-failed。

testOutputTruncation

在预设版本 5 中添加。

一个可选的指定测试输出截断模式的字符串。相当于在命令行中传递 --test-output-truncation。必须是以下值之一

tail
middle
head

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

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

any: 一个可选的指定文本固定装置正则表达式的字符串，以排除添加任何测试。相当于在命令行中传递 --fixture-exclude-any。此字段支持宏展开。

setup: 一个可选的指定文本固定装置正则表达式的字符串，以排除添加设置（setup）测试。相当于在命令行中传递 --fixture-exclude-setup。此字段支持宏展开。

cleanup: 一个可选的指定文本固定装置正则表达式的字符串，以排除添加清理（cleanup）测试。相当于在命令行中传递 --fixture-exclude-cleanup。此字段支持宏展开。

execution

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

stopOnFailure: 一个可选的布尔值。如果为 true，相当于在命令行中传递 --stop-on-failure。

enableFailover: 一个可选的布尔值。如果为 true，相当于在命令行中传递 -F。

jobs: 一个可选的整数。相当于在命令行中传递 --parallel。如果值为 0，则相当于无限制的并行度。

在预设版本 11 中更改：此字段也可以是一个字符串，在这种情况下它必须为空，相当于传递 --parallel 但省略 <jobs>。

在版本 4.3 中更改：无论 presets 文件的版本如何，此字段均不接受负整数值。

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。

testPassthroughArguments

在 presets 版本 12 中添加。

一个可选的字符串数组。每个元素都被转发为每个测试可执行文件的参数，相当于在命令行中在 ctest -- 之后传递参数。

当同时指定了预设传递参数和命令行传递参数时，预设参数首先出现，随后是命令行参数。

包预设 (Package Preset)¶

在预设版本 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: 一个可选的条件 (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: 一个可选字符串，用于指定要与此包预设（package preset）关联的配置预设（configure preset）名称。如果未指定 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: 一个可选字符串，代表供应商名称。

工作流预设 (Workflow Preset)¶

在预设版本 6 中添加。

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

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

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

displayName: 一个可选字符串，为预设提供人类友好的名称。

描述: 一个可选字符串，为预设提供人类友好的描述。

steps

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

type: 一个必需的字符串。第一步必须是 configure。后续步骤必须是 build、test 或 package。

名称: 一个必需的字符串，代表作为此工作流步骤要运行的配置、构建、测试或包预设的名称。

条件 (Condition)¶

在预设版本 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"

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

condition: 一个必需的条件对象。

宏展开 (Macro Expansion)¶

如上所述，某些字段支持宏展开。宏的识别形式为 $<macro-namespace>{<macro-name>}。

通常，宏在所使用的预设上下文中求值，即使该宏位于从另一个预设继承的字段中。例如，如果 Base 预设将变量 PRESET_NAME 设置为 ${presetName}，且 Derived 预设继承自 Base，那么 PRESET_NAME 将被设置为 Derived。从预设版本 12 开始，${fileDir} 宏是此规则的一个例外。

如果在宏名称末尾没有放置闭合括号，则会报错。例如，${sourceDir 是无效的。美元符号 ($) 后面跟随除左花括号 ({)（可能带有命名空间）以外的任何内容，都将被解释为字面量美元符号。

识别的宏包括

${sourceDir}

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

${sourceParentDir}

${sourceDirName}

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

${presetName}

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

这是一个预设特定的宏。

${generator}

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

这是一个预设特定的宏。

${hostSystemName}: 在预设版本 3 中添加。

宿主操作系统的名称。包含与 CMAKE_HOST_SYSTEM_NAME 相同的值。

${fileDir}

在预设版本 4 中添加。

包含定义当前所用预设的预设文件的目录路径。

在预设版本 12 中更改：无论使用哪个预设，此宏始终展开为包含该宏的当前预设文件所在的目录。

例如，考虑以下场景。

/path/to/CMakePresets.json 包含了 /path/to/subdir/CMakePresets.json。
/path/to/subdir/CMakePresets.json 定义了预设 Base，它将变量 MY_DIR 设置为 ${fileDir}。
/path/to/CMakePresets.json 定义了预设 Derived，且 Derived 继承自 Base。

在预设版本 4-11 中，使用 Derived 预设时 MY_DIR 将被设置为 /path/to/，而使用 Base 预设时为 /path/to/subdir/。

当 /path/to/subdir/CMakePresets.json 指定版本为 12 或更高时，无论使用哪个预设，MY_DIR 始终将被设置为 /path/to/subdir/。

注意

由于版本 12 中的 ${fileDir} 宏是在当前预设文件的上下文中展开的，因此是由当前文件的版本（而不是包含所用预设的根文件版本）决定此行为的。

${dollar}

一个字面量美元符号 ($)。

${pathListSep}

在预设版本 5 中添加。

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

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

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

版本 (Versions)¶

CMake 预设文件的 JSON 模式遵循一种版本方案，其中新版本会被添加并允许在更新版本的 CMake 中使用。

下面给出了支持的版本列表，以及它们被引入的 CMake 版本，以及新功能和更改的摘要。

1

3.19 版本新增。

初始版本支持配置预设 (Configure Presets) 和宏展开 (Macro Expansion)。

2

在 3.20 版本中添加。

新增了构建预设 (Build Presets)。

新增了测试预设 (Test Presets)。

3

3.21 版本新增。

为配置 (Configure)、构建 (Build) 和测试预设 (Test Presets) 新增了 Condition 对象。

配置预设 (Configure Presets) 的变更

新增了 installDir 字段。

新增了 toolchainFile 字段。

binaryDir 字段现在变为可选。

generator 字段现在变为可选。

宏展开 (Macro Expansion) 的变更

新增了 ${hostSystemName} 宏。

4

在版本 3.23 中添加。

新增了包含 (Includes) 功能，以支持在 CMakePresets.json 和 CMakeUserPresets.json 中包含其他 JSON 文件。

构建预设 (Build Presets) 的变更

新增了 resolvePackageReferences 字段。

宏展开 (Macro Expansion) 的变更

新增了 ${fileDir} 宏。

5

在 3.24 版本中添加。

测试预设 (Test Presets) 的变更

在 output 对象中新增了 testOutputTruncation 字段。

宏展开 (Macro Expansion) 的变更

新增了 ${pathListSep} 宏。

6

在 3.25 版本中新增。

新增了包预设 (Package Presets)。

新增了工作流预设 (Workflow Presets)。

测试预设 (Test Presets) 的变更

在 output 对象中新增了 outputJUnitFile 字段。

7

在 3.27 版本中新增。

配置预设 (Configure Presets) 的变更

新增了 trace 字段。

包含 (Includes) 的变更

include 字段现在支持 $penv{} 宏展开。

8

版本 3.28 新增。

在根对象中新增了 $schema 字段。

9

3.30 版本新增。

包含 (Includes) 的变更

include 字段现在支持其他类型的宏展开。

10

在版本 3.31 中添加。

新增了可选的 $comment 字段，以支持在 CMakePresets.json 和 CMakeUserPresets.json 全文中添加文档注释。

配置预设 (Configure Presets) 的变更

新增了 graphviz 字段。

11

Added in version 4.3.

测试预设 (Test Presets) 的变更

jobs 字段现在接受空字符串，代表省略 <jobs> 参数的 --parallel。

12

4.4 版本新增。

配置预设 (Configure Presets) 的变更

在 warnings 和 errors 中，dev 字段重命名为 author。

在 errors 中新增了 uninitialized 和 unusedCli 字段。

在 warnings 和 errors 中新增了 installAbsoluteDestination 字段。

宏展开 (Macro Expansion) 的变更

${fileDir} 宏现在始终展开为包含该 ${fileDir} 宏的预设文件所在的目录，无论它是否被不同目录下的另一个预设继承。

测试预设 (Test Presets) 的变更

新增了 testPassthroughArguments 字段，用于将参数转发给测试可执行文件。

Schema ¶

此文件 为 CMake 预设文件格式提供了一个机器可读的 JSON schema。

cmake-presets(7)¶

介绍 ¶

格式 ¶

包含 ¶

配置预设 ¶

构建预设 (Build Preset)¶

测试预设 (Test Preset)¶

包预设 (Package Preset)¶

工作流预设 (Workflow Preset)¶

条件 (Condition)¶

宏展开 (Macro Expansion)¶

版本 (Versions)¶

Schema ¶

目录

上一主题

下一主题

本页