自訂 CMake 建置設定

發行項
07/17/2024

Visual Studio 會使用 CMake 組態檔來驅動 CMake 產生和建置。 CMakePresets.json 受 Visual Studio 2019 16.10 版或更新版本支援，而且是建議的 CMake 組態檔。 CMakePresets.json 受 CMake 直接支援，可用來從 Visual Studio、VS Code、在持續整合管線中，以及從 Windows、Linux 和 Mac 的命令列驅動 CMake 產生和建置。如需 CMakePresets.json 的詳細資訊，請參閱使用 CMake 預設設定和建置。

如果您維護使用 CMakeSettings.json 檔案進行 CMake 組建組態的專案，Visual Studio 2019 和更新版本會提供 CMake 設定編輯器。編輯器可讓您新增 CMake 組態，並輕鬆地自訂其設定。這是比手動編輯 CMakeSettings.json 檔案更簡單的替代方案。不過，如果您想要直接編輯檔案，您可以在編輯器右上角選取 [編輯 JSON] 連結。

若要開啟 CMake 設定編輯器，請選取主要工具列中的 [組態] 下拉式清單，然後選擇 [管理組態]。

[CMake 設定] 下拉式清單的螢幕擷取畫面。已醒目提示 [管理組態]。

此時您會看到設定編輯器，且左側會顯示已安裝的組態。

CMake 設定編輯器的螢幕擷取畫面。

根據預設，Visual Studio 會提供一個 x64-Debug 組態。您可以選擇綠色加號來新增更多組態。您在編輯器中看到的設定可能會根據選取的組態而有所不同。

您在編輯器中選擇的選項會寫入至名為 CMakeSettings.json 的檔案。此檔案會提供在您建置專案時會傳至 CMake 的命令列引數和環境變數。 Visual Studio 不會自動修改 CMakeLists.txt；藉由使用 CMakeSettings.json，您可以透過 Visual Studio 自訂組建，同時將 CMake 專案檔案保持原狀，讓小組的其他成員可以使用他們選擇的任何工具加以取用。

CMake 一般設定

以下是 [一般] 標題下提供的設定：

設定名稱

對應於 name 設定。這個名稱會出現在 C++ 組態下拉式清單中。您可以使用 ${name} 巨集來撰寫其他屬性值，例如路徑。

組態類型

對應於 configurationType 設定。定義所選產生器的組建組態類型。目前支援的值為 "Debug"、"MinSizeRel"、"Release" 和 "RelWithDebInfo"。它會對應至 CMAKE_BUILD_TYPE。

工具組

對應於 inheritedEnvironments 設定。定義將用來建置所選組態的編譯器環境。支援的值取決於組態的類型。若要建立自訂環境，請選擇「設定」編輯器右上角中的 [編輯 JSON] 連結，並直接編輯 CMakeSettings.json 檔案。

CMake 工具鏈檔案

CMake 工具鏈檔案的路徑。此路徑會作爲 "-DCMAKE_TOOLCHAIN_FILE = <filepath> 傳遞至 CMake。工具鏈檔案會指定編譯器和工具鏈公用程式的位置，以及其他目標平台和編譯器相關的資訊。根據預設，如果未指定此設定，Visual Studio 會使用 vcpkg 工具鏈檔案。

組建根

對應於 buildRoot。對應至 CMAKE_BINARY_DIR，並指定要建立 CMake 快取的位置。如果指定的資料夾不存在即會建立。

命令引數

以下是 [命令引數] 標題下提供的設定：

CMake 命令引數

對應於 cmakeCommandArgs。指定傳遞至 CMake 的更多命令行選項。

組建命令引數

對應至 buildCommandArgs。指定要傳遞到基礎建置系統的更多參數。例如，在使用 Ninja 產生器時傳遞 -v 會強制 Ninja 輸出命令列。

CTest 命令引數

對應至 buildCommandArgs。指定執行測試時會傳遞到 CTest 的其他命令列選項。

遠端組建的一般設定

在設定像是使用遠端組建的 Linux 時，也可以使用下列設定：

`rsync` 命令引數

傳遞給 rsync 的額外命令列選項，快速又多功能的檔案複製工具。

CMake 變數和快取

這些設定可讓您設定 CMake 變數，並將其儲存在 CMakeSettings.json 中。它們會在建置階段傳遞至 CMake，並覆寫 CMakeLists.txt 檔案中的任何值。您可以比照您使用 CMakeGUI 的相同方式來使用這個部分，以檢視所有可用於編輯的 CMake 變數清單。選擇 [儲存並產生快取] 按鈕，以檢視所有可用於編輯的 CMake 變數清單，包括進階變數 (依據 CMakeGUI)。您可以依變數名稱篩選清單。

對應至變數。包含成對的 CMake 變數名稱和值，會以 -D name=value 形式傳遞至 CMake。如果您的 CMake 專案建置指示指定直接將任何變數新增至 CMake 快取檔案，建議您改為在此新增。

進階設定

CMake 產生器

對應至產生器。對應至 CMake -G 參數，並指定要使用的 CMake 產生器。此屬性也可以在撰寫其他屬性值時用來作為巨集 ${generator}。 Visual Studio 目前支援下列 CMake 產生器：

"Ninja"
"Unix Makefiles"
"Visual Studio 16 2019"
"Visual Studio 16 2019 Win64"
"Visual Studio 16 2019 ARM"
"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"

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

IntelliSense 模式

IntelliSense 引擎所使用的 IntelliSense 模式。如果未選取任何模式，Visual Studio 會從指定的工具組繼承模式。

安裝目錄

CMake 安裝目標的目錄。對應到 CMAKE_INSTALL_PREFIX。

CMake 可執行檔

CMake 程式可執行檔的完整路徑，包括檔案名稱與副檔名。它可讓您搭配 Visual Studio 使用 CMake 的自訂版本。對於遠端組建，請指定遠端機器上的 CMake 位置。

在設定像是使用遠端組建的 Linux 時，也可以使用下列設定：

遠端 CMakeLists.txt 根目錄

遠端機器上包含根 CMakeLists.txt 檔案的目錄。

遠端安裝根目錄

CMake 在遠端機器上安裝目標的目錄。對應到 CMAKE_INSTALL_PREFIX。

遠端複製來源

指定是否要將來源檔案複製到遠端機器，並讓您指定要使用 rsync 還是 sftp。

直接編輯 CMakeSettings.json

您也可以直接編輯 CMakeSettings.json 以建立自訂組態。 設定編輯器的右上方有 [編輯 JSON] 按鈕可開啟檔案以進行編輯。

下列範例顯示範例組態，可供您作為作業起點：

    {
      "name": "x86-Debug",
      "generator": "Ninja",
      "configurationType": "Debug",
      "inheritEnvironments": [ "msvc_x86" ],
      "buildRoot": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}\\build\\${name}",
      "installRoot": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}\\install\\${name}",
      "cmakeCommandArgs": "",
      "buildCommandArgs": "-v",
      "ctestCommandArgs": ""
    },

JSON IntelliSense 會協助您編輯 CMakeSettings.json 檔案：

編輯器中 CMake JSON IntelliSense 快顯的螢幕擷取畫面。

JSON 編輯器也會在您選擇了不相容的設定時通知您。

如需檔案中每個屬性的詳細資訊，請參閱 CMakeSettings.json 結構描述參考。

Visual Studio 2017 提供數種 CMake 組態，定義如何叫用 CMake 來建立指定專案的 CMake 快取。若要新增新組態，請選取工具列中的 [組態] 下拉式清單，然後選擇 [管理組態]：

下拉式清單中選取 [管理設定] 的螢幕擷取畫面。

您可以從預先定義組態的清單中選擇：

將 [組態] 新增至 [CMake 設定] 對話方塊清單的預先定義組態。

當您第一次選取組態時，Visual Studio 會在您專案的根資料夾中建立一個 CMakeSettings.json 檔案。此檔案會用來重新建立 CMake 快取檔案，例如在清除作業之後。

若要新增其他組態，請以滑鼠右鍵按一下 CMakeSettings.json，然後選擇 [新增組態]。

已選取 [新增設定] 的快顯功能表的螢幕擷取畫面。

您也可以使用 CMake 設定編輯器來編輯檔案。請以滑鼠右鍵在 [方案總管] 中按一下 CMakeSettings.json，然後選擇 [編輯 CMake 設定]。或者，從編輯器視窗頂端的 [組態] 下拉式清單，選取 [管理組態]。

您也可以直接編輯 CMakeSettings.json 以建立自訂組態。下列範例顯示範例組態，可供您作為作業起點：

    {
      "name": "x86-Debug",
      "generator": "Ninja",
      "configurationType": "Debug",
      "inheritEnvironments": [ "msvc_x86" ],
      "buildRoot": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}\\build\\${name}",
      "installRoot": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}\\install\\${name}",
      "cmakeCommandArgs": "",
      "buildCommandArgs": "-v",
      "ctestCommandArgs": ""
    },

JSON IntelliSense 會協助您編輯 CMakeSettings.json 檔案：

編輯器中 CMake JSON IntelliSense 快顯的螢幕擷取畫面。

如需檔案中每個屬性的詳細資訊，請參閱 CMakeSettings.json 結構描述參考。

另請參閱

CMake Projects in Visual Studio (Visual Studio 中的 CMake 專案)
設定 Linux CMake 專案
 連線到遠端 Linux 電腦
 設定 CMake 偵錯工作階段
 部署、執行及偵錯 Linux 專案
 CMake 預先定義組態參考

共用方式為

自訂 CMake 建置設定

CMake 一般設定

設定名稱

組態類型