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 都存在，則 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 物件，可能包含以下欄位

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

可選欄位，分別代表支援它們的 generators 的平台和工具集。

請參閱 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，則必須從繼承的預設中繼承（除非此預設已隱藏）。建置目錄是從組態預設推斷出來的，因此建置將在與組態相同的 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 物件，可能包含以下欄位：

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。
額外資訊: 等同於在命令列上傳遞 --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

一個可選的物件，指定要包含的測試。該物件可能包含以下欄位。

name

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

label

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

useUnion

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

索引

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

start: 一個可選的整數，指定開始測試的測試索引。
end: 一個可選的整數，指定停止測試的測試索引。
stride: 一個可選的整數，指定增量。
specificTests: 一個可選的整數陣列，指定要執行的特定測試索引。

exclude

一個可選的物件，指定要排除的測試。該物件可能包含以下欄位。

name

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

label

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

fixtures

一個可選的物件，指定要排除在新增測試之外的 fixture。該物件可能包含以下欄位。

any: 一個可選的字串，指定要排除新增任何測試的文字 fixture 的正規表示式。等同於命令列上的 --fixture-exclude-any。此欄位支援巨集擴展。
setup: 一個可選的字串，指定要排除新增設定測試的文字 fixture 的正規表示式。等同於命令列上的 --fixture-exclude-setup。此欄位支援巨集擴展。
cleanup: 一個可選的字串，指定要排除新增清除測試的文字 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。該字串必須為以下其中一個值

human

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。

套件預設 ¶

套件預設可以在 schema 版本 6 或以上中使用。 packagePresets 陣列的每個項目都是一個 JSON 物件，可能包含以下欄位

name

一個必要的字串，表示預設的機器可讀名稱。此識別符號用於 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

一個可選的字串，表示預設值的人性化名稱。

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，則在所有繼承的套件預設環境變數之後，但在此套件預設設置中明確指定的環境變數之前，會繼承關聯的組態預設設置中的環境變數。

generators

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

configurations

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

variables

一個可選的變數對應表，用於傳遞給 CPack，等同於 -D 參數。每個鍵是變數的名稱，而值是要賦予該變數的字串。

configFile

一個可選的字串，表示 CPack 要使用的設定檔。

output

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

debug: 一個可選的布林值，指定是否印出偵錯資訊。值為 true 等同於在命令列上傳遞 --debug。
verbose: 一個可選的布林值，指定是否印出詳細資訊。值為 true 等同於在命令列上傳遞 --verbose。

packageName

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

packageVersion

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

packageDirectory

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

vendorName

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

工作流程預設設置 ¶

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

name

一個必填的字串，表示預設設置的機器友善名稱。此識別符號用於 cmake --workflow --preset 選項中。在同一個目錄中，CMakePresets.json 和 CMakeUserPresets.json 的聯集中，不得有兩個具有相同名稱的工作流程預設設置。但是，工作流程預設設置的名稱可能與組態、建置、測試或套件預設設置的名稱相同。

vendor

一個可選的對應表，其中包含供應商特定的資訊。CMake 不會解讀此欄位的內容，除非驗證它是否為對應表。但是，它應該遵循與根層級 vendor 欄位相同的慣例。

displayName

一個可選的字串，表示預設值的人性化名稱。

description

一個可選的字串，表示預設值的人性化描述。

steps

一個必填的物件陣列，描述工作流程的步驟。第一個步驟必須是組態預設設置，而所有後續步驟必須是不屬於組態預設設置的預設設置，其 configurePreset 欄位與起始組態預設設置匹配。每個物件可能包含以下欄位

type: 一個必填的字串。第一個步驟必須是 configure。後續步驟必須是 build、test 或 package。
name: 一個必填的字串，表示要作為此工作流程步驟執行的組態、建置、測試或套件預設設置的名稱。

條件 ¶

預設設置的 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 個字元）廠商識別字首，後面跟一個 .，然後是巨集名稱。例如，範例 IDE 可以有 $vendor{xide.ideInstallDir}。

綱要 ¶

此檔案 為 CMakePresets.json 格式提供機器可讀的 JSON 綱要。

cmake-presets(7)¶

簡介 ¶

格式 ¶

包含 ¶

組態預設 ¶

建置預設 ¶

測試預設 ¶

套件預設 ¶

工作流程預設設置 ¶

條件 ¶

巨集展開 ¶

綱要 ¶

目錄

上一個主題

下一個主題

本頁