Visual Studio 中的 CMake 專案

CMake 是可在多個平台上執行之定義建置程序的跨平台開放原始碼工具。 本文假設您已熟悉 CMake。 如需 CMake 的詳細資訊，請參閱 CMake 文件。 CMake 教學課程是深入了解的良好起點。

注意

在過去幾個版本中，CMake 已越來越與 Visual Studio 整合。 若要查看您慣用 Visual Studio 版本的文件，請使用版本選取器控制項。 其位於此頁面目錄頂端。

Visual Studio 對 CMake 的原生支援可讓您在 Windows 上編輯、建置和偵錯 CMake 專案、Windows 子系統 Linux 版 (WSL)，以及來自相同 Visual Studio 執行個體的遠端系統。 CMake 專案檔 (例如 CMakeLists.txt) 會直接由 Visual Studio 取用，以供 IntelliSense 和瀏覽之用。 cmake.exe 會直接由 Visual Studio 叫用以用於 CMake 設定和建置。

安裝

適用於 Windows 的 C++ CMake 工具會安裝為使用 C++ 進行桌面開發，以及使用 C++ 進行 Linux 開發工作負載的一部分。 跨平台 CMake 開發需要適用於 Windows 的 C++ CMake 工具和 使用 C++ 進行 Linux 開發。

在安裝程式中，已選取 [使用 C++ 進行桌面開發] 下拉式清單，並選取 [適用於 Windows 的 C++ CMake 工具]。」

如需詳細資訊，請參閱在 Visual Studio 中安裝 C++ Linux 工作負載。

IDE 整合

當您開啟包含 CMakeLists.txt 檔案的資料夾時，會發生下列情況。

對話方塊提供下列選項：複製存放庫、開啟專案或方案、開啟本機資料夾，或建立新的專案。 螢幕擷取畫面中會呼叫開啟本機資料夾。

• Visual Studio 會將 CMake 項目新增至 [專案] 功能表，以及用來檢視和編輯 CMake 指令碼的命令。

• [方案總管] 會顯示資料夾結構和檔案。

• Visual Studio 會執行 CMake，並針對預設組態產生 CMake 快取檔案 (CMakeCache.txt)。 CMake 命令列會連同 CMake 的其他輸出一起顯示在輸出視窗中。

• Visual Studio 會在背景開始編製原始程式檔的索引，以啟用 IntelliSense、瀏覽資訊、重構等。 Visual Studio 會在您工作時，監視編輯器和磁碟上的變更，以確保其索引與來源同步。

注意

從 Visual Studio 2022 17.1 版 Preview 2 開始，如果您的最上層 CMakeLists.txt 存在於子資料夾中，而不是位於工作區根目錄，則系統會提示您是否要啟用 CMake 整合。 如需詳細資訊，請參閱 CMake 部分啟用。

一旦 CMake 快取產生成功，您也可以依目標以邏輯方式檢視組織的專案。 選擇 [方案總管] 工具列上的 [選取檢視] 按鈕。 從 [方案總管 - 檢視] 清單中，選取 [CMake 目標檢視]，然後按 Enter 以開啟目標檢視：

選擇 [方案總管] 頂端的 [顯示所有檔案] 按鈕，以查看 out/build/<config> 資料夾中所有 CMake 產生的輸出。

使用每個專案資料夾中的 CMakeLists.txt 檔案，就像在任何 CMake 專案中一樣。 您可以指定來源檔案、尋找程式庫、設定編譯器和連結器選項，以及指定其他建置系統相關資訊。 如需 Visual Studio 所提供 CMake 語言服務的詳細資訊，請參閱編輯 CMakeLists.txt 檔案。

Visual Studio 會使用 CMake 組態檔來驅動 CMake 快取產生和建置。 如需詳細資訊，請參閱設定 CMake 專案和建置 CMake 專案。

如果您需要在偵錯時將引數傳遞給可執行檔，您可以使用稱為 launch.vs.json 的另一個檔案。 如需在 Visual Studio 中偵錯跨平台 CMake 專案的詳細資訊，請參閱偵錯 CMake 專案。

Visual Studio 中的 CMake 專案支援大部分的 Visual Studio 和 C++ 語言功能。 範例包含：

• CMake 專案的編輯後繼續
• CMake 專案的 Incredibuild 整合
• CMake 專案的 AddressSanitizer 支援
• Clang/LLVM 支援

注意

對於其他類型的「開啟資料夾」專案，會使用額外的 JSON 檔案 CppProperties.json。 此檔案與 CMake 專案無關。

設定 CMake 專案

CMake 設定步驟會產生專案建置系統。 這相當於從命令列叫用 cmake.exe。 如需 CMake 設定步驟的詳細資訊，請參閱 CMake 文件。

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 適用於使用舊版 Visual Studio 的客戶。 如需 CMakeSettings.json 的詳細資訊，請參閱自訂 CMake 組建設定。

當您對 CMake 組態檔或 CMakeLists.txt 檔案進行重大變更時，Visual Studio 會自動執行 CMake 設定步驟。 您可以手動叫用設定步驟：從工具列選取 [項目 > 設定快取]。 您也可以在 [工具]>[選項]>[CMake]>[一般]中變更組態喜好設定。

系統會呼叫 CMake 設定。顯示已選取 CMake 快取通知。 在 [快取過期時：] 底下，已選取 [永不自動執行設定步驟] 選項。

如果設定步驟完成且沒有錯誤，則可用的資訊會驅動 C++ IntelliSense 和語言服務。 它也用於建置和偵錯作業。

您也可以在 Visual Studio 中開啟現有的 CMake 快取。 如需詳細資訊，請參閱開啟現有的快取。

自訂設定意見反應和通知

根據預設，除非發生錯誤，否則會隱藏大部分的組態訊息。 若要查看所有訊息，請選取 [工具]>[選項]>[CMake]>[啟用詳細資訊 CMake 診斷輸出]。

您也可以取消選取 [顯示 CMake 快取通知] 來停用所有 CMake 快取通知 (金色列)。

針對 CMake 快取錯誤進行疑難排解

如果您需要 CMake 快取狀態的詳細資訊以診斷問題，請開啟 [專案] 主功能表，或在 [方案總管] 中開啟CMakeLists.txt 捷徑功能表，執行下列其中一個命令：

• 檢視 CMakeCache.txt 會從編輯器的組建目錄中開啟 CMakeCache.txt 檔案。 如果您清除快取，您在此對 CMakeCache.txt 所做的任何編輯都會遭到抹除。 若要在清除快取之後進行保存的變更，請參閱自訂 CMake 設定或使用 CMake 預設進行設定和建置。

• 刪除快取並重新設定會刪除組建目錄，並從清除的快取重新設定。

• [設定快取] 會強制執行產生步驟，即使 Visual Studio 認為環境處於最新狀態也一樣。

建置 CMake 專案

CMake 建置步驟會建置已產生的專案二進位樹狀目錄。 這相當於從命令列叫用 cmake --build。 如需 CMake 建置步驟的詳細資訊，請參閱 CMake 文件。

若要建置 CMake 專案，您有下列選項：

1. 在工具列中，尋找 [啟動專案] 下拉式清單。 選取慣用的目標，然後按 F5，或選擇工具列上的 [執行] 按鈕。 專案會先自動建置，如同 Visual Studio 方案一樣。

2. 以滑鼠右鍵按一下 CMake 目標，並在 [方案總管] 中使用 [CMake 目標檢視]，然後從捷徑功能表中選取 [建置]。

3. 從主功能表中，選取 [建置 > 全部建置]。 確定已在工具列的 [啟動項目] 下拉式清單中選取 CMake 目標。

如您所預期，建置結果會顯示在 [輸出] 視窗和 [錯誤清單] 中。

CMake 會建置有關轉換的警告，這可能會導致可見的資料遺失，例如從浮點數轉換成整數。 :::image-end:::

編輯組建設定

Visual Studio 會使用 CMake 組態檔來驅動 CMake 組建。 CMake 組態檔會封裝組建選項，例如原生建置工具參數和環境變數。 如果 CMakePresets.json 是您的使用中組態檔，請參閱使用 CMake 預設進行設定和建置。 如果 CMakeSettings.json 是您的使用中組態檔，請參閱自訂 CMake 組建設定。 CMakePresets.json 適用於 Visual Studio 2019 16.10 版或更新版本，而且是建議的 CMake 組態檔。

偵錯 CMake 專案

工具列的 [啟動項目] 下拉式清單中會顯示所有可執行的 CMake 目標。 若要開始偵錯，請選取其中一個，然後按工具列中的 [偵錯 > 開始偵錯] 按鈕。 在 CMake 專案中，[目前文件] 選項僅適用於 .cpp 檔案。

下拉式清單具有下列選項：顯示/隱藏偵錯目標、目前文件、範例 (醒目提示)、box2d_tests 和 samples-noGUI。

如果自上次建置以來已有所變更，則 [偵錯] 或 F5 命令會先建置專案。 CMake 組態檔 (CMakePresets.json 或 CMakeSettings.json) 或 CMakeLists.txt 的變更會導致重新產生 CMake 快取。

您可以在 launch.vs.json 檔案中設定屬性，自訂 CMake 偵錯工作階段。 若要自訂特定目標的偵錯設定，請在 [啟動項目] 下拉式清單中選取目標，然後按 [偵錯 > 針對<作用中目標>偵錯和啟動設定]。 如需 CMake 偵錯工作階段的詳細資訊，請參閱設定 CMake 偵錯工作階段。

適用於 CMake 專案的 Just My Code

當您使用 MSVC 編譯器針對 Windows 建置時，CMake 專案支援 Just My Code 偵錯。 若要變更 Just My Code 設定，請移至 [工具]>[選項]>[偵錯]>[一般]。

CMake 專案的編輯後繼續

當您使用 MSVC 編譯器針對 Windows 建置時，CMake 專案支援 [編輯後繼續]。 將下列程式碼新增至您的 CMakeLists.txt 檔案，以啟用 [編輯後繼續]。

if(MSVC)
  target_compile_options(<target> PUBLIC "/ZI")
  target_link_options(<target> PUBLIC "/INCREMENTAL")
endif()

附加至在 Linux 上執行的 CMake 專案

Visual Studio 可讓您對遠端 Linux 系統或 WSL 上執行的處理程序進行偵錯，並使用 GDB 偵錯工具進行偵錯。 若要開始使用，請選取 [偵錯]>[附加至處理程序...]，將 [連線類型] 設定 為 [SSH]，然後從 [連線管理員] 的連線清單中選取您的 [連線目標]。 從可用的處理程序清單中選取處理程序，然後按 [附加]。 GDB 必須安裝在 Linux 電腦上。 如需 SSH 連線的詳細資訊，請參閱連線管理員

對話方塊提供下列選項：連線類型 (設定為 SSH)、連線目標 (設定為 demo@172.20.60.6)，以及您可以附加的可用處理程序清單。」

CMake 部分啟用

在 Visual Studio 2022 17.1 版和更新版本中，如果您的根資料夾不包含 CMakeLists.txt 檔案，CMake 功能將不會自動啟用。 相反地，對話方塊會提示您是否要為專案啟用 CMake 功能。 如果您拒絕，CMake 快取產生將不會啟動，且 CMake 組態 (來自 CMakeSettings.json 或 CMakePresets.json) 不會出現在組態下拉式清單中。 如果您接受，系統會將您導向至工作區層級組態檔 CMakeWorkspaceSettings.json (儲存在 .vs 目錄中)，以指定您想要啟用 CMake 的資料夾。 (這些資料夾包含您的根目錄 CMakeLists.txt 檔案)。

接受的屬性如下：

屬性	說明
enableCMake	啟用此工作區的 Visual Studio 整合。
sourceDirectory	使用 CMakeLists.txt 指定一或多個目錄的字串或字串陣列。 允許巨集 (例如 ${workspaceRoot})。 相對路徑是以工作區根目錄為基礎。 系統將會忽略目前工作區以外的目錄。

您可以隨時透過 [專案]>[CMake 工作區設定] 功能表命令連絡 CMakeWorkspaceSettings.json，即使目前已停用 CMake 功能也一樣。

開啟現有的快取

當您開啟現有的 CMake 快取檔案 (CMakeCache.txt)，Visual Studio 不會嘗試為您管理快取和組建樹狀結構。 您的自訂或慣用工具可完全控制 CMake 設定您專案的方式。

您可以將現有的 CMake 快取新增至開啟的專案。 其完成方式與新增組態的方式相同。 如需詳細資訊，請參閱我們在Visual Studio 中開啟現有快取的部落格文章。

注意

預設現有的快取體驗依賴於 cmake-server，其已從 3.20 版的 CMake 中移除。 若要在 Visual Studio 2019 16.10 版和更新版本中繼續使用現有的快取功能，請執行下列步驟之一：

• 手動安裝 CMake 3.19 版或更低版本。 然後，將現有快取組態中的 cmakeExecutable 屬性設定為使用該版本的 CMake。
• 在現有的快取組態中，設定 cacheGenerationCommand 屬性，讓 Visual Studio 要求必要的 CMake 檔案型 API 檔案。 如需該屬性的詳細資訊，請參閱 CMakeSettings.json 參考。
• 在 Visual Studio 中產生並開啟快取之前，使用查詢檔案來要求 CMake 檔案型 API 檔案。 如需查詢檔案指示，請參閱下一節進階 CMake 快取疑難排解。

進階 CMake 快取疑難排解

Visual Studio 會使用 CMake 檔案型 API (在 3.14 版和更新版本中)，將專案結構特有的資訊填入編輯器。 如需詳細資訊，請參閱多根工作區和檔案型 API 上的C++ 小組部落格文章。

在產生 CMake 快取之前，您的自訂或慣用工具可能需要在組建輸出資料夾 (包含 CMakeCache.txt 的資料夾) 中建立名為 .cmake/api/v1/query/client-MicrosoftVS/query.json 的查詢檔案。 查詢檔案應包含此內容：

{"requests":[{"kind":"cache","version":2},{"kind":"cmakeFiles","version":1},{"kind":"codemodel","version":2}]}

當您的自訂或慣用工具產生快取時，CMake 會將檔案放在 .cmake/api/v1/response 底下，Visual Studio 會使用該資訊以專案結構特有的資訊填入編輯器。

編輯 CMakeLists.txt 檔案

若要編輯 CMakeLists.txt 檔案，請在 [方案總管] 中以滑鼠右鍵按一下該檔案，然後選擇 [開啟]。 如果您對檔案進行變更，則會顯示黃色狀態列，並通知您 IntelliSense 將會更新。 它可讓您取消更新作業。 如需 CMakeLists.txt 的相關資訊，請參閱 CMake 文件。

它包含行專案 (hello-cmake)、add_subdirectory (測試)、add_executable (hello hello.cpp)，以及安裝 (TARGETS hello DESTINATION hello/bin)。 視窗頂端的訊息表示，C++ IntelliSense 資訊會在 C Make 完成產生快取之後重新整理。

一旦您儲存檔案，設定步驟會自動再次執行，並在 [輸出] 視窗中顯示資訊。 錯誤和警告會顯示在 [錯誤清單] 或 [輸出] 視窗中。 按兩下 [錯誤清單] 中的錯誤，即可瀏覽至 CMakeLists.txt 中有問題的那一行。

醒目提示 CMakeLists.txt 中行 3 上的 CMake 錯誤訊息。 詳細資料是 CMake 找不到 sqlite3 所提供的套件組態檔。 CMake 已在 CMAKE_MODULE_PATH 中尋找，但找不到。 建議將安裝前置詞「sqlite3」新增至 CMAKE_PREFIX_PATH，或將 sqlite3_DIR 設定為包含 sqlite3Config.cmake 和/或 sqlitet3-config.cmake 的目錄。

CMake 的語言服務

CMake 的語言服務可在 Visual Studio 2019 16.5 版或更新版本中取得。 它支援程式碼瀏覽功能，例如移至定義、瞄核定義，以及針對 CMake 指令碼檔案中的 CMake 變數、函式和目標尋找所有參考。 如需詳細資訊，請參閱 CMake 指令碼的程式碼瀏覽。

顯示找到 SUPERTUX_SOURCES_CXX 位置的結果。 例如，在 list(SORT SSUPERTUX_SOURCES_CXX)、file(GLOB SUPERTUX_SOURCES_CXX) 等等。

CMake 專案操作

Visual Studio 2019 16.5 版或更新版本提供 CMake 專案操作。 專案操作可讓您在 CMake 專案中新增、移除和重新命名來源檔案和目標，而不需手動編輯 CMake 指令碼。 當您從 [方案總管] 新增或移除檔案時，Visual Studio 會自動編輯您的 CMake 專案。 可能有多個地方新增或移除 CMake 指令碼的參考。 如果是，Visual Studio 會詢問您想要變更的位置，並顯示建議變更的預覽。 如需逐步指示，請參閱在 CMake 專案中新增、移除和重新命名檔案和目標。

樹狀檢視會顯示 CMakeLists.txt，其底下有兩個項目：add_executable 和設定。 已核取 [設定]。 預覽視窗會顯示將進行變更的位置。 行集 (PROJECT_SRC “CmakeProject4.cpp” “CMakeProject4.h” 會顯示右括弧前醒目提示的 “Demo.cpp”。 [套用] 按鈕接受變更，或者您可以按 [取消]。

CMake 專案的 IntelliSense

根據預設，Visual Studio 會使用符合使用中 CMake 組態所指定編譯器和目標架構的 IntelliSense 模式。

如果 CMakePresets.json 是作用中的 CMake 組態檔，您可以使用 Visual Studio 設定廠商對應中的 intelliSenseMode 和 intelliSenseOptions 來指定 IntelliSense 選項。 如需詳細資訊，請參閱 Visual Studio 設定廠商對應參考。

如果 CMakeSettings.json 是使用中的 CMake 組態檔，您可以在 CMakeSettings.json 中使用 intelliSenseMode 來指定 IntelliSense 選項。 如需詳細資訊，請參閱 CMakeSettings.json 參考。

使用 CMake 工具鏈檔案設定 IntelliSense

在 Visual Studio 2019 16.9 版和更新版本中，當您使用 CMake 工具鏈檔案時，Visual Studio 會在 CMake 專案中根據 CMake 變數自動設定 IntelliSense。 如需詳細資訊，請參閱使用 CMake 工具鏈檔案設定 IntelliSense。

Vcpkg 整合

在 Visual Studio 中開啟的 CMake 專案會與跨平台 C/C++ 相依性管理員 vcpkg 整合。 在搭配 Visual Studio 使用 vcpkg 之前，您必須執行 vcpkg integrate install。 如需 vcpkg 的指示和詳細資訊，請參閱：

• 在 Visual Studio 中搭配 CMake 安裝和使用套件
• CMake 專案中的 vcpkg

如果 CMakeSettings.json 是使用中的組態檔，Visual Studio 會自動將 vcpkg 工具鏈檔案 (vcpkg.cmake) 傳遞至 CMake。 當您在 CMake 設定組態中指定任何其他工具鏈時，會自動停用此行為。

如果 CMakePresets.json 是使用的組態檔，您將必須在 CMakePresets.json 中將路徑設定為 vcpkg.cmake。 我們建議使用 VCPKG_ROOT 環境變數，而不是絕對路徑來保留檔案可共用。 如需詳細資訊，請參閱啟用 vcpkg 與 CMake 預設的整合。 CMakePresets.json 適用於 Visual Studio 2019 16.10 版或更新版本，而且是建議的 CMake 組態檔。

從命令列執行 CMake

如果 CMakePresets.json 是作用中的 CMake 組態檔，則您可以輕鬆地在 Visual Studio 外部重現本機組建。 如需詳細資訊，請參閱從命令列或 CI 管線執行 CMake。 CMakePresets.json 受 Visual Studio 2019 16.10 版或更新版本支援，而且是建議的 CMake 組態檔。

如果 CMakeSettings.json 是作用中的 CMake 組態檔，則您必須手動將 CMakeSettings.json 檔案中編碼的引數傳遞至 CMake。 如果您已從 Visual Studio 安裝程式安裝 CMake，則可以遵循下列步驟從命令列執行：

1. 執行適當的 vsdevcmd.bat 檔案 (x86/x64)。 如需詳細資訊，請參閱在命令列上建置。

2. 切換至您的輸出資料夾。

3. 執行 CMake 以建置或設定您的應用程式。

另請參閱

教學課程：在 Visual Studio 中建立 C++ 跨平台專案
設定 Linux CMake 專案
連線到遠端 Linux 電腦
自訂 CMake 建置設定
CMakeSettings.json 結構描述參考
設定 CMake 偵錯工作階段
部署、執行及偵錯 Linux 專案
CMake 預先定義組態參考
CMake 專案中的 vcpkg
在 Visual Studio 中搭配 CMake 安裝和使用套件