`CMakeSettings.json` 架構參考

發行項
11/21/2024

Visual Studio 2017 和更新版本中支援 CMake 專案。

檔案 CMakeSettings.json 包含 Visual Studio 用於 IntelliSense 的資訊，以及建構它針對指定組態和編譯程式環境傳遞至 CMake 的命令行自變數。組態會指定套用至特定平台和組建類型的屬性，例如 x86-Debug 或 Linux-Release。每個組態都會指定環境，其會封裝編譯程式工具組的相關信息，例如 MSVC、GCC 或 Clang。 CMake 會使用命令行自變數來重新產生專案的根 CMakeCache.txt 檔案和其他項目檔。這些值可以在檔案中 CMakeLists.txt 覆寫。

您可以在 IDE 中新增或移除組態，然後直接在 JSON 檔案中編輯它們，或使用 CMake 設定編輯器 （Visual Studio 2019 和更新版本）。您可以在 IDE 中輕鬆地切換組態，以產生各種項目檔。如需詳細資訊，請參閱在Visual Studio中自定義 CMake 組建設定。

組態

數位包含 configurations CMake 專案的所有組態。如需預先定義組態的詳細資訊，請參閱 CMake 預先定義的組態參考。您可以將任意數目的預先定義或自訂組態新增至檔案。

configuration 有這些屬性：

addressSanitizerEnabled：如果 true為，請使用 AddressSanitizer 編譯程式。在 Linux 上，使用 -fno-omit-frame-pointer 和編譯程式優化層級 -Os 進行編譯，或 -Oo 取得最佳結果。
addressSanitizerRuntimeFlags：傳遞至環境變數中 AddressSanitizer 的 ASAN_OPTIONS 運行時間旗標。格式：flag1=value：flag2=value2。
buildCommandArgs：指定在之後 --build --傳遞至 CMake 的原生組建參數。例如，在使用 Ninja 產生器時傳遞 -v 會強制 Ninja 輸出命令列。如需 Ninja 命令的詳細資訊，請參閱 Ninja 命令行自變數。
buildRoot：指定 CMake 為所選取器產生組建文稿的目錄。對應至 -DCMAKE_BINARY_DIR 切換，並指定建立的位置 CMakeCache.txt 。如果資料夾不存在，則會建立該資料夾。支援的巨集包括 ${workspaceRoot}、${workspaceHash}、${projectFile}、${projectDir}、${thisFile}、${thisFileDir}、${name}、${generator}、${env.VARIABLE}。
cacheGenerationCommand：指定命令行工具和自變數，例如 gencache.bat debug 產生快取。當用戶明確要求重新產生或 CMakeLists.txt 修改或 CMakeSettings.json 檔案時，命令會從指定環境中的殼層執行。
cacheRoot：指定 CMake 快取的路徑。此目錄應該包含現有的 CMakeCache.txt 檔案。
clangTidyChecks：傳遞至 clang-tidy 的警告逗號分隔清單;允許通配符，且 '-' 前置詞會移除檢查。
cmakeCommandArgs：指定要在叫用以產生項目檔時傳遞至 CMake 的任何額外命令行選項。
cmakeToolchain：指定工具鏈檔案。它會使用 -DCMAKE_TOOLCHAIN_FILE傳遞至 CMake。
codeAnalysisRuleset：指定執行程式代碼分析時要使用的規則集。您可以使用 Visual Studio 所安裝之規則集檔案的完整路徑或檔案名。
configurationType：指定所選取器的組建類型組態。可能是下列其中之一：
- Debug
- Release
- MinSizeRel
- RelWithDebInfo
ctestCommandArgs：指定要在執行測試時傳遞至 CTest 的任何額外命令列選項。
description：此組態的描述會出現在功能表中。
enableClangTidyCodeAnalysis：使用 Clang-Tidy 進行程式碼分析。
enableMicrosoftCodeAnalysis：使用Microsoft程式代碼分析工具進行程式碼分析。
generator：指定要用於此組態的 CMake 產生器。可能是下列其中之一：

僅限 Visual Studio 2019：
- Visual Studio 16 2019
- Visual Studio 16 2019 Win64
- Visual Studio 16 2019 ARM
Visual Studio 2017 及更新版本：
- Visual Studio 15 2017
- Visual Studio 15 2017 Win64
- Visual Studio 15 2017 ARM
- Visual Studio 14 2015
- Visual Studio 14 2015 Win64
- Visual Studio 14 2015 ARM
- Unix Makefiles
- Ninja

由於 Ninja 是專為加快建置速度 (而不是彈性和功能) 所設計，因此會成爲預設設定。不過，有些 CMake 專案可能無法使用 Ninja 正確地建置。如果發生建置失敗，您可以指示 CMake 改為產生 Visual Studio 專案。

若要在 Visual Studio 2017 中指定 Visual Studio 產生器，請藉由選擇 CMake 從主功能表開啟設定編輯器 |變更 CMake 設定。刪除「Ninja」，然後輸入「V」。。這項變更會啟動 IntelliSense，讓您選擇您想要的產生器。

若要在 Visual Studio 2019 中指定 Visual Studio 產生器，請以滑鼠右鍵按兩下方案總管中的檔案，然後選擇 [顯示進階設定 CMake 產生器] 專案的>[CMake 設定]。> CMakeLists.txt

根據預設，當使用中組態指定 Visual Studio 產生器時，它會使用自變數叫用 -m -v:minimal MSBuild。若要自定義組建，請使用 buildCommandArgs 檔案內的 CMakeSettings.json 屬性。您可以在這裡指定要傳遞至建置系統的 MSBuild 命令行自變數：

"buildCommandArgs": "-m:8 -v:minimal -p:PreferredToolArchitecture=x64"

installRoot：指定 CMake 產生所選取器安裝目標的目錄。支援的巨集包括 ${workspaceRoot}、${workspaceHash}、${projectFile}、${projectDir}、${thisFile}、${thisFileDir}、${name}、${generator}、${env.VARIABLE}。
inheritEnvironments：指定此組態相依的一或多個編譯程序環境。可以是任何自訂的環境，或預先定義的環境之一。如需詳細資訊，請參閱環境。
intelliSenseMode：指定用於計算 Intellisense 資訊的模式。此值可能是下列其中一項：
- windows-msvc-x86
- windows-msvc-x64
- windows-msvc-arm
- windows-msvc-arm64
- android-clang-x86
- android-clang-x64
- android-clang-arm
- android-clang-arm64
- ios-clang-x86
- ios-clang-x64
- ios-clang-arm
- ios-clang-arm64
- windows-clang-x86
- windows-clang-x64
- windows-clang-arm
- windows-clang-arm64
- linux-gcc-x86
- linux-gcc-x64
- linux-gcc-arm
name：命名組態。如需預先定義組態的詳細資訊，請參閱 CMake 預先定義的組態參考。
wslPath：Windows 子系統 Linux 版實例啟動器的路徑。

CMake Linux 項目的設定

remoteMachineName：指定裝載 CMake、組建和調試程式的遠端 Linux 計算機名稱。使用連線管理員新增新的 Linux 電腦。支援的巨集包括 ${defaultRemoteMachineName}。
remoteCopySourcesOutputVerbosity：指定來源複製作業的詳細資訊層級至遠端計算機。可能是、 Verbose或 Diagnostic的Normal其中一個。
remoteCopySourcesConcurrentCopies：指定要在同步處理來源到遠端計算機時使用的並行複本（僅限 sftp）。
remoteCopySourcesMethod：指定將檔案複製到遠端計算機的方法。 rsync可以是或 sftp。
remoteCMakeListsRoot：指定遠端電腦上的目錄，其中包含 CMake 專案。支援的巨集包括 ${workspaceRoot}、、${workspaceHash}、、${thisFile}${projectFile}${projectDir}、${thisFileDir}、${name}、、 ${generator}和。${env.VARIABLE}
remoteBuildRoot：指定 CMake 產生所選取器組建文稿之遠端電腦上的目錄。支援的巨集包括 ${workspaceRoot}、${workspaceHash}、${projectFile}、${projectDir}、${thisFile}、${thisFileDir}、${name}、${generator}、${env.VARIABLE}。
remoteInstallRoot：指定 CMake 產生所選取器安裝目標的遠端電腦上的目錄。支援的巨集包括 ${workspaceRoot}、${workspaceHash}、${projectDir}${thisFile}${projectFile}${thisFileDir}、${name}、 ${generator}和 ${env.VARIABLE}，其中 VARIABLE 是已在系統、使用者或會話層級定義的環境變數。
remoteCopySourcesboolean：，指定 Visual Studio 是否應該將來源檔案複製到遠端電腦。預設值為 True。如果自行管理檔案同步處理，請設定為 false。
remoteCopyBuildOutputboolean：，指定是否要從遠端系統複製組建輸出。
remoteCopyAdditionalIncludeDirectories：要從遠端計算機複製的其他包含目錄，以支援 IntelliSense。格式為 “/path1;/path2...”。
remoteCopyExcludeDirectories：包含目錄 NOT 從遠端電腦複製。格式為 “/path1;/path2...”。
remoteCopyUseCompilerDefaults：指定是否要使用編譯程式的預設定義和包含 IntelliSense 的路徑。只有當編譯程式用來不支援 gcc 樣式自變數時，才應為 false。
rsyncCommandArgs：指定傳遞至 rsync 的一組命令行選項。
remoteCopySourcesExclusionListarray：指定複製來源檔案時要排除的路徑清單：路徑可以是檔案/目錄的名稱，或是複製根目錄中的相對路徑。通配符 * 和 ? 可用於 glob 模式比對。
cmakeExecutable：指定 CMake 程式可執行檔的完整路徑，包括檔名和擴展名。
remotePreGenerateCommand：指定要在執行 CMake 之前執行的命令來剖析 CMakeLists.txt 檔案。
remotePrebuildCommand：指定要在遠端電腦上執行，再建置的命令。
remotePostbuildCommand：指定要在建置後於遠端電腦上執行的命令。
variables：包含傳 -D name=value 給 CMake 的 CMake 變數名稱/值組。如果您的 CMake 專案建置指示會指定將任何變數直接新增至 CMakeCache.txt 檔案，建議您改為在這裡新增變數。此範例示範如何指定名稱/值組，以使用 14.14.26428 MSVC 工具組：

"variables": [
    {
      "name": "CMAKE_CXX_COMPILER",
      "value": "C:/Program Files (x86)/Microsoft Visual Studio/157/Enterprise/VC/Tools/MSVC/14.14.26428/bin/HostX86/x86/cl.exe",
      "type": "FILEPATH"
    },
    {
      "name": "CMAKE_C_COMPILER",
      "value": "C:/Program Files (x86)/Microsoft Visual Studio/157/Enterprise/VC/Tools/MSVC/14.14.26428/bin/HostX86/x86/cl.exe",
      "type": "FILEPATH"
    }
  ]

如果您未定義 "type"，則 "STRING" 預設會假設類型。

remoteCopyOptimizations： Visual Studio 2019 16.5 版或更新版本 屬性，用於控制來源複製到遠端目標。默認會啟用優化。包含 remoteCopyUseOptimizations、 rsyncSingleDirectoryCommandArgs與 remoteCopySourcesMaxSmallChange。

環境

環境會封裝Visual Studio用來叫用 CMake 程式中設定的環境變數。針對 MSVC 專案，它會擷取特定平台開發人員命令提示字元中設定的變數。例如，msvc_x64_x64環境與使用 -arch=amd64 -host_arch=amd64 自變數執行 VS {version} 的開發人員命令提示字元相同。您可以使用 env.{<variable_name>} 中的 CMakeSettings.json 語法來參考個別環境變數，例如建構資料夾的路徑。提供下列預先定義的環境：

linux_arm：遠端目標 ARM Linux。
linux_x64：遠端鎖定 x64 Linux。
linux_x86：從遠端鎖定 x86 Linux。
msvc_arm：以 MSVC 編譯程式為目標的 ARM Windows。
msvc_arm_x64：以64位 MSVC 編譯程式為目標的ARM Windows。
msvc_arm64：以 MSVC 編譯程式為目標的 ARM64 Windows。
msvc_arm64_x64：以64位 MSVC 編譯程式為目標的ARM64 Windows。
msvc_arm64ec：以 MSVC 編譯程式ARM64EC Windows 為目標。
msvc_arm64ec_x64：以64位 MSVC 編譯程式為目標ARM64EC Windows。
msvc_x64：以 MSVC 編譯程式為目標的 x64 Windows。
msvc_x64_x64：以64位 MSVC 編譯程式為目標的 x64 Windows。
msvc_x86：以 MSVC 編譯程式為目標的 x86 Windows。
msvc_x86_x64：以 64 位 MSVC 編譯程式為目標的 x86 Windows。

從存取環境變數 `CMakeLists.txt`

CMakeLists.txt從檔案中，語法會參考$ENV{variable_name}所有環境變數。若要檢視環境的可用變數，請開啟對應的命令提示字元並輸入 SET。環境變數中的一些資訊也可透過 CMake 系統內省變數取得，但您可能會發現使用環境變數更方便。例如，您可以透過環境變數輕鬆地擷取 MSVC 編譯程式版本或 Windows SDK 版本。

自訂環境變數

在中 CMakeSettings.json，您可以在陣列中 environments 全域或個別組態定義自定義環境變數。自定義環境是將一組屬性分組的便利方式。您可以使用它取代預先定義的環境，或擴充或修改預先定義的環境。 environments 陣列中的每個項目都包含：

namespace：將環境命名為，以便從格式 namespace.variable的組態參考其變數。預設的環境物件稱為 env，以特定的系統環境變數填入，包括 %USERPROFILE%。
environment：唯一識別此變數群組。稍後在 inheritEnvironments 項目中允許繼承該群組。
groupPriority：整數，指定評估這些變數時的優先順序。先評估數值較高的項目。
inheritEnvironments：值陣列，指定這個群組繼承的環境集合。此功能可讓您繼承預設環境，並建立自定義環境變數，以在 CMake 執行時傳遞至 CMake。

Visual Studio 2019 16.4 版和更新版本： 偵錯目標會隨著您在中指定的 CMakeSettings.json環境自動啟動。您可以在和 tasks.vs.json中launch.vs.json覆寫或新增每個目標或每個工作上的環境變數。

下列範例會定義一個全域變數， BuildDir其繼承於 x86-Debug 和 x64-Debug 組態中。每個組態都會使用變數來指定該組態的 buildRoot 屬性值。另請注意，每個組態 inheritEnvironments 如何使用屬性來指定僅適用於該組態的變數。

{
  // The "environments" property is an array of key-value pairs of the form
  // { "EnvVar1": "Value1", "EnvVar2": "Value2" }
  "environments": [
    {
      "BuildDir": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}\\build",
    }
  ],

  "configurations": [
    {
      "name": "x86-Debug",
      "generator": "Ninja",
      "configurationType": "Debug",
      // Inherit the defaults for using the MSVC x86 compiler.
      "inheritEnvironments": [ "msvc_x86" ],
      "buildRoot": "${env.BuildDir}\\${name}"    },
    {
      "name": "x64-Debug",
      "generator": "Ninja",
      "configurationType": "Debug",
      // Inherit the defaults for using the MSVC x64 compiler.
      "inheritEnvironments": [ "msvc_x64" ],
      "buildRoot": "${env.BuildDir}\\${name}"
    }
  ]
}

在下一個範例中，x86-Debug 組態會針對 BuildDir 屬性定義其自身的值。此值會覆寫全域 BuildDir 屬性設定的值，使 BuildRoot 的評估結果為 D:\custom-builddir\x86-Debug。

{
  "environments": [
    {
      "BuildDir": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}",
    }
  ],

  "configurations": [
    {
      "name": "x86-Debug",

      // The syntax for this property is the same as the global one above.
      "environments": [
        {
          // Replace the global property entirely.
          "BuildDir": "D:\\custom-builddir"
          // This environment does not specify a namespace, hence by default "env" is assumed.
          // "namespace" : "name" would require that this variable be referenced with "${name.BuildDir}".
        }
      ],

      "generator": "Ninja",
      "configurationType": "Debug",
      "inheritEnvironments": [ "msvc_x86" ],
      // Evaluates to "D:\custom-builddir\x86-Debug"
      "buildRoot": "${env.BuildDir}\\${name}"
    },
    {
      "name": "x64-Debug",

      "generator": "Ninja",
      "configurationType": "Debug",
      "inheritEnvironments": [ "msvc_x64" ],
      // Since this configuration doesn't modify BuildDir, it inherits
      // from the one defined globally.
      "buildRoot": "${env.BuildDir}\\${name}"
    }
  ]
}

巨集

下列巨集可用於 CMakeSettings.json：

${workspaceRoot} – 工作區資料夾的完整路徑
${workspaceHash} - 工作區位置的雜湊；適用於建立目前工作區的唯一識別碼 (例如用於資料夾路徑)
${projectFile} – 根 CMakeLists.txt 檔案的完整路徑
${projectDir} – 包含根 CMakeLists.txt 檔案的資料夾完整路徑
${projectDirName} – 包含根 CMakeLists.txt 檔案的資料夾名稱
${thisFile}– 檔案的完整路徑CMakeSettings.json
${name} - 組態的名稱
${generator} - 用於此組態之 CMake 產生器的名稱

中 CMakeSettings.json 巨集和環境變數的所有參考都會展開，再傳遞至 CMake 命令行。

Ninja 命令行自變數

如果未指定目標，Ninja 會建置「預設」目標。

C:\Program Files (x86)\Microsoft Visual Studio\Preview\Enterprise>ninja -?
ninja: invalid option -- `-?'
usage: ninja [options] [targets...]

選項	描述
`--version`	列印忍者版本（“1.7.1”）
`-C DIR`	在執行任何其他動作之前變更為 DIR
`-f FILE`	指定輸入組建檔案（default=`build.ninja`）
`-j N`	平行執行 `N` 作業（default=14，衍生自可用的 CPU）
`-k N`	繼續工作直到 `N` 作業失敗（default=1）
`-l N`	如果負載平均大於，請勿啟動新的作業 `N`
`-n`	試運行（不執行命令，但運作方式就像成功一樣）
`-v`	建置時顯示所有命令行
`-d MODE`	開啟偵錯（用來 `-d list` 列出模式）
`-t TOOL`	執行子工具（用來 `-t list` 列出子工具）。結束任何最上層選項;進一步旗標會傳遞至工具
`-w FLAG`	調整警告（用來 `-w list` 列出警告）

共用方式為

`CMakeSettings.json` 架構參考

組態

CMake Linux 項目的設定

環境

從存取環境變數 `CMakeLists.txt`

自訂環境變數

巨集

Ninja 命令行自變數

意見反應

其他資源

共用方式為

CMakeSettings.json 架構參考

組態

CMake Linux 項目的設定

環境

從存取環境變數 CMakeLists.txt

自訂環境變數

巨集

Ninja 命令行自變數

意見反應

其他資源

`CMakeSettings.json` 架構參考

從存取環境變數 `CMakeLists.txt`