入門指南

在您的電腦上取得並安裝 CMake

在使用 CMake 之前，您需要在您的系統上安裝或建置 CMake 二進制檔。在許多系統上，您可能會發現 CMake 已經安裝，或者可以使用系統的標準套件管理工具進行安裝。Cygwin、Debian、FreeBSD、OS X MacPorts、Mac OS X Fink 和許多其他系統都有 CMake 發行版。

如果您的系統沒有 CMake 套件，您可以在 CMake 下載頁面上找到針對許多常見架構預先編譯的 CMake。選擇所需的版本並按照下載說明進行操作。CMake 可以安裝到任何目錄，因此安裝不需要 root 權限。

如果您找不到適用於您系統的預編譯二進制檔，則可以從原始碼建置 CMake。要建置 CMake，您需要一個現代的 C++ 編譯器和來自 CMake 下載頁面或 Kitware 的 GitLab 實例的原始碼發行版。要建置 CMake，請按照原始碼樹頂部的 README.rst 中的說明進行操作。

目錄結構

CMake 在建置專案時會使用兩個主要目錄：原始碼目錄和二進制目錄。原始碼目錄是專案原始碼所在的位置。這也是 CMakeLists 檔案所在的位置。二進制目錄有時稱為建置目錄，是 CMake 將放置產生的物件檔案、函式庫和可執行檔的位置。CMake 不會將任何檔案寫入原始碼目錄，只會寫入二進制目錄。

強烈建議使用來源外部建置，其中原始碼和二進制目錄不同。支援來源內部建置，其中原始碼和二進制目錄相同，但應盡可能避免。來源外部建置使維護乾淨的原始碼樹變得非常容易，並允許快速刪除建置產生所有檔案。讓建置樹與原始碼樹不同，也使得支援單一原始碼樹的多個建置變得容易。當您想要使用不同的選項進行多次建置，但只需要一份原始碼副本時，這很有用。

基本 CMake 用法

CMake 接收一個或多個 CMakeLists 檔案作為輸入，並產生專案檔案或 Makefiles，以便與各種原生開發工具一起使用。

典型的 CMake 流程如下

  1. 專案定義在一個或多個 CMakeLists 檔案中

  2. CMake 配置並產生專案

  3. 使用者使用他們喜歡的原生開發工具建置專案

以下章節將詳細說明流程的每個步驟。

CMakeLists 檔案

CMakeLists 檔案（實際上是 CMakeLists.txt，但通常會省略副檔名）是純文字檔案，其中包含 CMake 語言的專案描述。 cmake-language 表示為一系列註解、命令和變數。您可能想知道為什麼 CMake 決定擁有自己的語言，而不是使用現有的語言，例如 Python、Java 或 Tcl。主要原因是 CMake 開發人員不想讓 CMake 需要額外的工具才能執行。透過要求使用這些其他語言之一，CMake 的所有使用者都需要安裝該語言，並且可能需要該語言的特定版本。這是在效能和功能考量下，執行某些 CMake 工作所需的語言擴充功能之上。

CMake 的 Hello World

首先，讓我們考慮最簡單的 CMakeLists 檔案。要從一個原始碼檔案編譯一個可執行檔，CMakeLists 檔案將包含三行

cmake_minimum_required(VERSION 3.20)
project(Hello)
add_executable(Hello Hello.c)

頂層 CMakeLists 檔案的第一行應始終為 cmake_minimum_required。這允許專案要求給定的 CMake 版本，此外，也允許 CMake 向後相容。

任何頂層 CMakeLists 檔案的下一行都應該是 project 命令。此命令設定專案的名稱，並且可以指定其他選項，例如語言或版本。

對於專案中 CMakeLists.txt 檔案調用 project 命令的每個目錄，CMake 會產生一個頂層 Makefile 或 IDE 專案檔。專案將包含 CMakeLists.txt 檔案中的所有目標，以及 add_subdirectory 命令指定的任何子目錄。如果在 add_subdirectory 命令中使用 EXCLUDE_FROM_ALL 選項，則產生的專案將不會出現在頂層 Makefile 或 IDE 專案檔中；這對於產生不適合作為主要建置流程一部分的子專案很有用。考慮到具有許多範例的專案可以使用此功能，透過執行一次 CMake 來產生每個範例的建置檔案，但不要將範例作為正常建置流程的一部分進行建置。

最後，使用 add_executable 命令將可執行檔新增至專案，使用給定的原始碼檔案。

在此範例中，原始碼目錄中有兩個檔案：CMakeLists.txt 和 Hello.c。

下一節將描述如何使用 CMake GUI 和命令列介面配置和建置專案。

配置和產生

在建立 CMakeLists 檔案後，CMake 會處理文字檔案並在快取檔案中建立條目。使用者可以使用 CMake gui 或 ccmake 編輯 CMakeLists 檔案或指定快取值，然後重新配置。接下來，CMake 使用快取條目在使用者所需的建置系統（例如 Makefile 或 Visual Studio 解決方案）中產生專案。

執行 CMake GUI

CMake 包含一個基於 Qt 的使用者介面，可以在大多數平台（包括 UNIX、Mac OS X 和 Windows）上使用。 cmake-gui 包含在 CMake 原始碼中，但您需要在您的系統上安裝 Qt 才能建置它。

../_images/QtbasedCMakeGUI.png

圖 1：基於 Qt 的 CMake GUI

在 Windows 上，可執行檔名為 cmake-gui.exe，它應該在「開始」選單的「程式檔案」下。您的桌面上也可能有一個快捷方式，或者如果您是從原始碼建置 CMake，它將在建置目錄中。對於 UNIX 和 Mac 使用者，可執行檔名為 cmake-gui，可以在您安裝 CMake 可執行檔的位置找到。將會出現一個與圖 1 所示相似的 GUI。頂部的兩個欄位是原始碼和二進制目錄。它們允許您指定要編譯的原始碼所在的位置，以及應放置產生的二進制檔案的位置。您應該先設定這兩個值。如果您指定的二進制目錄不存在，系統會為您建立它。如果二進制目錄之前已由 CMake 配置過，它將自動設定原始碼樹。

執行 ccmake Curses 介面

在大多數 UNIX 平台上，如果支援 curses 函式庫，CMake 會提供一個名為 ccmake 的可執行檔。這個介面是一個基於終端的文字應用程式，與 cmake-gui 非常相似。要執行 ccmake，請將目錄變更為您要放置二進制檔的目錄。然後在命令列上執行 ccmake，並帶上原始碼目錄的路徑。這將啟動文字介面，如圖 2 所示。

../_images/ccmakerunningonUNIX.png

圖 2：在 UNIX 上執行的 ccmake

簡要說明顯示在視窗底部。如果您按下「c」鍵，它將配置專案。您應該始終在變更快取中的值後進行配置。若要變更值，請使用方向鍵選擇快取條目，然後按下 Enter 鍵進行編輯。布林值將透過 Enter 鍵切換。一旦您將所有值都設定好，您可以按下「g」鍵來產生 Makefiles 並退出。您也可以按下「h」鍵獲取說明、「q」鍵退出，以及「t」鍵切換檢視進階快取條目。

從命令列執行 CMake

從命令列中，可以使用 cmake 執行檔來產生專案建置系統。這最適合用於選項很少或沒有選項的專案。對於像 VTK 這樣較大的專案，建議使用 ccmake，或 cmake-gui。若要使用 cmake 建置專案，首先建立並切換目錄到您想要放置二進位檔案的位置。執行 cmake，指定原始碼樹的路徑，並使用 -D 旗標傳入任何選項。與 ccmake 或 cmake-gui 不同的是，當使用 cmake 執行檔時，組態和產生步驟會合併為一個。

指定編譯器給 CMake

在某些系統上，您可能有不只一個編譯器可供選擇，或者您的編譯器可能位於非標準的位置。在這些情況下，您需要向 CMake 指定您所需的編譯器所在的位置。有三種方法可以指定：產生器可以指定編譯器；可以設定環境變數；或者可以設定快取條目。某些產生器與特定的編譯器綁定；例如，Visual Studio 19 產生器始終使用 Microsoft Visual Studio 19 編譯器。對於基於 Makefile 的產生器，CMake 將嘗試一系列常用的編譯器，直到找到可用的編譯器為止。

可以在執行 CMake 之前設定環境變數來搶佔這些列表。CC 環境變數指定 C 編譯器，而 CXX 指定 C++ 編譯器。您可以透過使用 -DCMAKE_CXX_COMPILER=cl 等方式直接在命令列上指定編譯器。一旦 cmake 執行並選擇了一個編譯器，如果您想要更改編譯器，請從空的二進位目錄重新開始。

編譯器和連結器的旗標也可以透過設定環境變數來更改。設定 LDFLAGS 將會初始化連結旗標的快取值，而 CXXFLAGS 和 CFLAGS 將分別初始化 CMAKE_CXX_FLAGS 和 CMAKE_C_FLAGS。

建置組態

建置組態允許專案以不同的方式建置，例如除錯、最佳化或任何其他特殊旗標組合。CMake 預設支援 Debug、Release、MinSizeRel 和 RelWithDebInfo 組態。Debug 啟用基本除錯旗標。Release 啟用基本最佳化。MinSizeRel 具有產生最小物件程式碼的旗標，但不一定是速度最快的程式碼。RelWithDebInfo 建置最佳化組建，同時包含除錯資訊。

CMake 處理組態的方式略有不同，具體取決於使用的產生器。在可能的情況下，會遵循原生建置系統的慣例。這表示當使用 Makefiles 與使用 Visual Studio 專案檔案時，組態會以不同的方式影響建置。

Visual Studio IDE 支援建置組態的概念。Visual Studio 中的預設專案通常具有 Debug 和 Release 組態。從 IDE 中，您可以選擇建置 Debug，檔案將以 Debug 旗標建置。IDE 會將所有二進位檔案放入具有活動組態名稱的目錄中。這為需要在建置過程中從自訂命令執行的程式帶來了額外的複雜性。有關如何處理此問題的更多資訊，請參閱 CMAKE_CFG_INTDIR 變數和自訂命令章節。變數 CMAKE_CONFIGURATION_TYPES 用於告知 CMake 要在工作區中放入哪些組態。

對於基於 Makefile 的產生器，一次只能有一個組態處於活動狀態，並且使用 CMAKE_BUILD_TYPE 變數指定。如果變數為空，則不會將任何旗標添加到建置中。如果變數設定為組態的名稱，則會將適當的變數和規則 (例如 CMAKE_CXX_FLAGS_<ConfigName>) 添加到編譯行中。Makefiles 不會使用特殊的組態子目錄來存放物件檔案。若要建置除錯和發行樹，使用者應使用 CMake 的來源外建置功能建立多個建置目錄，並將 CMAKE_BUILD_TYPE 設定為每個建置所需的選擇。例如

# With source code in the directory MyProject
# to build MyProject-debug create that directory, cd into it and
ccmake ../MyProject -DCMAKE_BUILD_TYPE=Debug
# the same idea is used for the release tree MyProject-release
ccmake ../MyProject -DCMAKE_BUILD_TYPE=Release

建置您的專案

在您執行 CMake 之後，您的專案將準備好建置。如果您的目標產生器是基於 Makefiles，那麼您可以將目錄變更為您的二進位樹，並輸入 make (或 gmake 或 nmake，視情況而定) 來建置您的專案。如果您為 IDE (例如 Visual Studio) 產生了檔案，則可以啟動您的 IDE，將專案檔案載入其中，並像平常一樣建置。

另一個選項是從命令列使用 cmake 的 --build 選項。此選項只是一個方便的功能，可讓您從命令列建置您的專案，即使這需要啟動 IDE。

這就是安裝和執行 CMake 來進行簡單專案的全部內容。在接下來的章節中，我們將更詳細地探討 CMake，並說明如何在更複雜的軟體專案中使用它。