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

一個選用的字串，提供 JSON 結構描述的 URI，用於描述此 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 都存在，即使在所有版本的格式中都沒有 include 欄位，CMakeUserPresets.json 也會隱含地包含 CMakePresets.json。

如果預設集檔案包含繼承自另一個檔案中預設集的預設集，則該檔案必須直接或間接地包含另一個檔案。檔案之間不允許包含循環。如果 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 中的預設集。

condition

一個選用的 條件 物件。在指定版本 3 或更高版本的預設集檔案中允許使用。

vendor

一個選用的地圖，包含供應商特定的資訊。CMake 不會解譯此欄位的內容，除了驗證它是否為地圖（如果存在）。但是，它應遵循與根層級 vendor 欄位相同的慣例。如果供應商使用他們自己的每個預設集 vendor 欄位，他們應在適當時以合理的方式實作繼承。

displayName

一個選用的字串，具有預設集的人類友善名稱。

description

一個選用的字串，具有預設集的人類友善描述。

generator

一個選用的字串，表示要用於預設集的產生器。如果未指定 generator，則必須從 inherits 預設集繼承（除非此預設集為 hidden）。在版本 3 或更高版本中，可以省略此欄位以回退到常規產生器探索程序。

請注意，對於 Visual Studio 產生器，與命令列 -G 引數不同，您不能在產生器名稱中包含平台名稱。請改用 architecture 欄位。

architecture、toolset

選用的欄位，分別表示支援它們的 產生器 的平台和工具組。

請參閱 cmake -A 選項以取得 architecture 的可能值，以及 cmake -T 以取得 toolset。

每個欄位可以是字串或具有以下欄位的物件

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。

uninitialized

一個選用的布林值。將其設定為 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 中的預設集。

condition

一個選用的 條件 物件。在指定版本 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，則必須從 inherits 預設集繼承（除非此預設集被隱藏）。建置目錄是從設定預設集推斷出來的，因此建置將在與設定相同的 binaryDir 中進行。

inheritConfigureEnvironment

一個選用的布林值，預設為 true。如果為 true，則在所有繼承的建置預設集環境之後，但在此建置預設集中明確指定的環境變數之前，繼承來自關聯的設定預設集的環境變數。

jobs

一個選用的整數。相當於在命令列上傳遞 --parallel 或 -j。

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

一個可選的字串陣列。相當於在命令列上在 -- 後面傳遞選項。陣列值支援巨集展開。

測試預設集

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 中的預設集。

condition

一個選用的 條件 物件。在指定版本 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，則必須從繼承的預設集繼承（除非此預設集被隱藏）。建置目錄是從設定預設集推斷出來的，因此測試將在與組態和建置相同的 binaryDir 中執行。

inheritConfigureEnvironment

一個可選的布林值，預設為 true。如果為 true，則在所有繼承的測試預設集環境變數之後，但在此測試預設集中明確指定的環境變數之前，會繼承關聯的設定預設集中的環境變數。

configuration

一個可選的字串。相當於在命令列上傳遞 --build-config。

overwriteConfigurationFile

一個可選的組態選項陣列，用於覆寫 CTest 組態檔中指定的選項。相當於為陣列中的每個值傳遞 --overwrite。陣列值支援巨集展開。

output

一個可選的物件，用於指定輸出選項。此物件可能包含以下欄位。

shortProgress

一個可選的布林值。如果為 true，則相當於在命令列上傳遞 --progress。

verbosity

一個可選的字串，指定詳細程度。必須是下列其中一項

default

相當於在命令列上不傳遞任何詳細程度旗標。

verbose

verbose

相當於在命令列上傳遞 --verbose。

extra

debug

相當於在命令列上傳遞 --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。

include

filter

name

一個可選的物件，用於指定如何篩選要執行的測試。此物件可能包含以下欄位。

include

一個可選的物件，用於指定要包含哪些測試。此物件可能包含以下欄位。

names

一個可選的字串，指定測試名稱的正規表示式。相當於在命令列上傳遞 --tests-regex。此欄位支援巨集展開。CMake 正規表示式語法在 string(REGEX) 中描述。

索引

label

一個可選的字串，指定測試標籤的正規表示式。相當於在命令列上傳遞 --label-regex。此欄位支援巨集展開。

useUnion

一個可選的布林值。相當於在命令列上傳遞 --union。

index

一個可選的物件，用於指定要依測試索引包含的測試。此物件可能包含以下欄位。也可以是一個可選的字串，指定包含 --tests-information 命令列語法的檔案。如果指定為字串，則此欄位支援巨集展開。

start

一個可選的整數，指定要開始測試的測試索引。

end

一個可選的整數，指定要停止測試的測試索引。

stride

name

一個可選的整數，指定增量。

include

specificTests

一個可選的整數陣列，指定要執行的特定測試索引。

exclude

一個可選的物件，用於指定要排除哪些測試。此物件可能包含以下欄位。

names

一個可選的字串，指定測試名稱的正規表示式。相當於在命令列上傳遞 --exclude-regex。此欄位支援巨集展開。

label

一個可選的字串，指定測試標籤的正規表示式。相當於在命令列上傳遞 --label-exclude。此欄位支援巨集展開。

fixtures

一個可選的物件，用於指定要從新增測試中排除哪些 fixtures。此物件可能包含以下欄位。

any

一個可選的字串，指定要從排除新增任何測試的文字 fixtures 的正規表示式。相當於 --fixture-exclude-any 命令列選項。此欄位支援巨集展開。

setup

一個可選的字串，指定要從排除新增設定測試的文字 fixtures 的正規表示式。相當於 --fixture-exclude-setup 命令列選項。此欄位支援巨集展開。

cleanup

jobs

一個可選的字串，指定要從排除新增清除測試的文字 fixtures 的正規表示式。相當於 --fixture-exclude-cleanup 命令列選項。此欄位支援巨集展開。

execution

一個可選的物件，用於指定測試執行的選項。此物件可能包含以下欄位。

stopOnFailure

一個可選的布林值。如果為 true，則相當於在命令列上傳遞 --stop-on-failure。

enableFailover

一個可選的布林值。如果為 true，則相當於在命令列上傳遞 -F。

human

json-v1

parallelLevel

一個可選的整數。相當於在命令列上傳遞 --parallel。

mode

resourceSpecFile

一個可選的字串。相當於在命令列上傳遞 --resource-spec-file。此欄位支援巨集展開。

testLoad

一個可選的整數。相當於在命令列上傳遞 --test-load。

showOnly

一個可選的字串。相當於在命令列上傳遞 --show-only。字串必須是下列其中一個值

none

names

files

estimated-time

output

repeat

一個可選的物件，用於指定如何重複測試。相當於在命令列上傳遞 --repeat。此物件必須包含以下欄位。

mode

default

一個必要的字串。必須是下列其中一個值

until-fail

until-pass

after-timeout

count

times

一個必要的整數。

name

interactiveDebugging

hidden

一個可選的布林值。如果為 true，則相當於在命令列上傳遞 --interactive-debug-mode 1。如果為 false，則相當於在命令列上傳遞 --interactive-debug-mode 0。

inherits

一個選用的字串陣列，表示要繼承的預設集名稱。此欄位也可以是一個字串，相當於包含一個字串的陣列。

預設集將預設繼承來自 inherits 預設集的所有欄位（除了 name、hidden、inherits、description 和 displayName），但可以根據需要覆寫它們。如果多個 inherits 預設集為同一個欄位提供衝突的值，則 inherits 陣列中較早的預設集將優先。

預設集只能繼承自定義在同一個檔案或其包含的檔案之一（直接或間接）中的另一個預設集。CMakePresets.json 中的預設集不得繼承自 CMakeUserPresets.json 中的預設集。

condition

scheduleRandom

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

一個可選的布林值。如果為 true，則相當於在命令列上傳遞 --schedule-random。

inheritConfigureEnvironment

timeout

一個可選的整數。相當於在命令列上傳遞 --timeout。

noTestsAction

一個可選的字串，指定在找不到測試時的行為。必須是下列其中一個值

default

相當於不在命令列上傳遞任何值。

error

相當於在命令列上傳遞 --no-tests=error。

ignore

output

相當於在命令列上傳遞 --no-tests=ignore。

debug

封裝預設集

verbose

封裝預設集可用於結構描述版本 6 或更高版本。packagePresets 陣列的每個條目都是一個 JSON 物件，可能包含以下欄位

一個必要的字串，代表預設集的機器可讀名稱。此識別符用於 cpack --preset 選項中。CMakePresets.json 和 CMakeUserPresets.json 的聯集中，在同一個目錄下不得有兩個同名的封裝預設集。但是，封裝預設集可以與設定、建置、測試或工作流程預設集同名。

一個可選的布林值，指定是否應隱藏預設集。如果預設集被隱藏，則無法在 --preset 參數中使用，並且即使從繼承而來，也不必具有有效的 configurePreset。hidden 預設集旨在用作其他預設集透過 inherits 欄位繼承的基礎。

一個可選的 條件 物件。

一個可選的字串，指定要與此封裝預設集關聯的設定預設集名稱。如果未指定 configurePreset，則必須從繼承的預設集繼承（除非此預設集被隱藏）。建置目錄是從設定預設集推斷出來的，因此封裝將在與組態和建置相同的 binaryDir 中執行。

一個可選的布林值，預設為 true。如果為 true，則在所有繼承的封裝預設集環境變數之後，但在此封裝預設集中明確指定的環境變數之前，會繼承關聯的設定預設集中的環境變數。

generators

一個可選的字串陣列，代表 CPack 要使用的產生器。

configurations

一個可選的字串陣列，代表 CPack 要封裝的建置組態。

variables

name

一個可選的變數地圖，用於傳遞給 CPack，相當於 -D 參數。每個鍵是變數的名稱，值是要指派給該變數的字串。

vendor

configFile

displayName

一個選用的字串，具有預設集的人類友善名稱。

description

一個選用的字串，具有預設集的人類友善描述。

一個可選的字串，代表 CPack 要使用的組態檔。

output

type

一個可選的物件，用於指定輸出選項。有效的鍵為

name

debug

一個可選的布林值，指定是否要列印偵錯資訊。true 值相當於在命令列上傳遞 --debug。

verbose

type

一個可選的布林值，指定是否要詳細列印。true 值相當於在命令列上傳遞 --verbose。

packageName

一個可選的字串，代表套件名稱。

value

packageVersion

一個可選的字串，代表套件版本。

packageDirectory

一個可選的字串，代表放置套件的目錄。

vendorName

一個可選的字串，代表供應商名稱。

工作流程預設集

工作流程預設集可用於結構描述版本 6 或更高版本。workflowPresets 陣列的每個條目都是一個 JSON 物件，可能包含以下欄位

一個必要的字串，代表預設集的機器可讀名稱。此識別符用於 cmake --workflow --preset 選項中。CMakePresets.json 和 CMakeUserPresets.json 的聯集中，在同一個目錄下不得有兩個同名的工作流程預設集。但是，工作流程預設集可以與設定、建置、測試或封裝預設集同名。

vendor

一個可選的地圖，包含供應商特定的資訊。CMake 不會解譯此欄位的內容，除非驗證它是否為地圖（如果存在）。但是，它應遵循與根層級 vendor 欄位相同的慣例。

steps

一個必要的物件陣列，描述工作流程的步驟。第一個步驟必須是設定預設集，而所有後續步驟都必須是非設定預設集，其 configurePreset 欄位與起始設定預設集相符。每個物件可能包含以下欄位

type

一個必要的字串。第一個步驟必須是 configure。後續步驟必須是 build、test 或 package。

name

一個必要的字串，代表要作為此工作流程步驟執行的設定、建置、測試或封裝預設集的名稱。

條件

steps

在指定版本為 3 或更高版本的預設集檔案中允許使用的預設集 condition 欄位，用於判斷是否啟用預設集。例如，這可以用於在 Windows 以外的平台上停用預設集。condition 可以是布林值、null 或物件。如果它是布林值，則布林值表示是否啟用或停用預設集。如果它是 null，則啟用預設集，但 null 條件不會被任何可能從預設集繼承的預設集繼承。子條件（例如在 not、anyOf 或 allOf 條件中）不能為 null。如果它是物件，則具有以下欄位

type

一個必要的字串，具有下列其中一個值

"const"

表示條件是常數。這相當於使用布林值來代替物件。條件物件將具有以下其他欄位

value

一個必要的布林值，為條件的評估提供常數值。

"equals"

"notEquals"

表示條件比較兩個字串，以查看它們是否相等（或不相等）。條件物件將具有以下其他欄位

condition

lhs

要比較的第一个字串。此欄位支援巨集展開。

rhs

要比較的第二個字串。此欄位支援巨集展開。

"inList"

"notInList"

表示條件在字串列表中搜尋字串。條件物件將具有以下其他欄位

string

要搜尋的必要字串。此欄位支援巨集展開。

list

要搜尋的必要字串陣列。此欄位支援巨集展開，並使用短路求值。

"matches"

"notMatches"

表示條件在字串中搜尋正規表示式。條件物件將具有以下其他欄位

string

要搜尋的必要字串。此欄位支援巨集展開。

表示條件在字串中搜尋正規表示式。條件物件將具有以下其他欄位

regex

要搜尋的必要正規表示式。此欄位支援巨集展開。

"anyOf"

"allOf"

表示條件是零或多個巢狀條件的聚合。條件物件將具有以下其他欄位

conditions

必要的條件物件陣列。這些條件使用短路求值。

"not"

表示條件是另一個條件的反轉。條件物件將具有以下其他欄位

這在指定版本 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 結構描述。