自訂 CMake 建置設定

發行項
10/18/2023

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 設定編輯器，請選取 主要工具列中的 [組態 ] 下拉式清單，然後選擇 [ 管理組態 ]。

Screenshot of the CMake configuration drop-down. Manage Configurations is highlighted.

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

Screenshot of the CMake settings editor.

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

組建根

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

命令引數

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

CMake 命令引數

對應於 cmakeCommandArgs。指定再傳遞至 CMake 的命令列選項。

組建命令引數

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

CTest 命令引數

對應至 ctestCommandArgs 。指定要在執行測試時傳遞至 CTest 的更多命令列選項。

遠端組建的一般設定

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

`rsync` 命令引數

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

CMake 變數和快取

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

對應至變數。包含傳遞至 -D name=value CMake 之 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 檔案：

Screenshot of the CMake JSON IntelliSense pop-up in the editor.

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

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

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

Screenshot of Manage configurations selected in the drop-down.

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

Add Configuration to CMake Settings dialog list of predefined configurations.

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

若要新增另一個設定，請以滑鼠右鍵按一下 CMakeSettings.json 並選擇 [ 新增組態 ]。

Screenshot of the shortcut menu with Add configuration selected.

您也可以使用 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 檔案：

Screenshot of the CMake JSON IntelliSense pop-up in the editor.

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

另請參閱

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

Share via

自訂 CMake 建置設定

CMake 一般設定

設定名稱

組態類型