# CMake 專案建置
###### tags: `NTOU CSE C++ Programming` `CMake`

> 教學文件和作業說明文件： https://hackmd.io/@kogiokka/ntou-cse-cpp-nav

> 範例程式和範例專案：[Google Drive](
https://drive.google.com/drive/folders/100YvcqccLgY_27mJnubRSuPALrMAghJQ?usp=sharing)

CMake 是一個跨平台的建置自動化軟體，用於軟體的建置、測試和包裝。CMake 會依照你撰寫的腳本產生平台上原生建置系統的設定檔（例如：Makefile），再使用原生建置系統編譯你的專案。

CMake專案的建置流程：
1. 配置CMake快取（Configure Step）
2. 產生原生建置系統的設定檔（Generate Step）
3. 編譯並執行（Compile & Run）

參考資料：https://cgold.readthedocs.io/en/latest/tutorials/cmake-stages.html

## 環境配置

### Windows

> 如果你想在 Visual Studio 中使用 CMake 設定專案，請直接到「**搭配 Visual Studio**」的章節。

* CMake：https://cmake.org/download/
* TDM-GCC：https://jmeubank.github.io/tdm-gcc/
* Ninja: https://github.com/ninja-build/ninja/releases

CMake 版本選擇 **Latest Release**，TDM-GCC 版本選擇 **MinGW-w64 based**（64位元）。Ninja 壓縮檔內為單一檔案的可執行檔，解壓縮後將`ninja.exe`放置在`C:/dev/bin`目錄下。並且將`"C:\dev\bin"`加入系統環境變數（**設定→關於→進階系統設定→環境變數**）。

1. 在終端機輸入指令測試是否正確安裝：

### macOS

使用[Homebrew](https://brew.sh/)套件管理工具（必須先下載XCode）。開啟終端機後執行下列指令安裝Homebrew：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

腳本跑完後請依照最後的提示訊息把 `brew` 指令加到 `PATH` 環境變數中。

安裝所需軟體：

brew install cmake
brew install gcc
brew install ninja

### Linux

Debian/Ubuntu

apt install gcc g++ cmake ninja-build

CentOS/Fedora

dnf install gcc gcc-c++ cmake ninja-build

## 範例〇、簡單的CMake專案

專案目錄結構

Project0
├── CMakeLists.txt
└── main.cpp

CMakeLists.txt

cmake_minimum_required(VERSION 3.16) # CMake_最低版本_需求

project("Hello World") # 建立一個CMake專案，並給予專案名稱

add_executable(hello-world) # 建立一個CMake目標，目標為可執行檔

target_sources(hello-world PRIVATE "main.cpp") # 指定建置該CMake目標時所使用的來源檔案

main.cpp

#include <iostream>

int main()
{
    std::cout << "Hello, world!" << std::endl;
    return 0;
}

## 範例一、多個原始碼檔案的CMake專案

專案目錄結構

Project1
├── CMakeLists.txt
├── f1.cpp
├── f1.h
├── f2.cpp
├── f2.h
└── main.cpp

CMakeLists.txt

cmake_minimum_required(VERSION 3.16)

project("Project 01")

# 新增一個 CMake 目標，目標型態為可執行檔。
add_executable(project-01)

# 指定建置該 CMake 目標時所使用的來源檔案，不必包含標頭檔。
# PRIVATE之後列出來的檔案路徑是從 CMakeLists.txt 所在的目錄起始的相對
# 路徑。以空格區隔即可，換行加縮排是為了可讀性和方便編輯。
target_sources(project-01
    PRIVATE
        "main.cpp"
        "f1.cpp"
        "f2.cpp"
        # "f3.cpp"
        # "f4.cpp"
        # ...
)

## 範例二、建立和使用靜態函式庫

專案目錄結構

Project2
├── CMakeLists.txt
├── libstatic1
│   ├── CMakeLists.txt
│   ├── f1.cpp
│   ├── f1.h
│   ├── f2.cpp
│   └── f2.h
└── main.cpp

CMakeLists.txt

cmake_minimum_required(VERSION 3.16)

project("Project 02")

# 新增一個 CMake 目標，目標型態為可執行檔。
add_executable(project-02)
target_sources(project-02
    PRIVATE
        "main.cpp"
)
# 新增目標 project-02 的 Include 目錄
target_include_directories(project-02
    PRIVATE
        "libstatic1/"
)

# 將指定資料夾的 CMake 專案（含有 CMakeLists.txt）一起加入建置。
add_subdirectory("libstatic1/")

# 新增目標 project-02 所連結的函式庫。函式庫名稱為其他 CMake 專案的目標名稱。通常來自
# find_package 或 add_subdirectory。以這個範例來說，libstatic1 函式庫是來自
# add_subdirectory 指令所加入的 CMake 專案。
target_link_libraries(project-02
    PRIVATE
        libstatic1
)

libstatic1/CMakeLists.txt

# 新增一個 CMake 目標，目標型態為靜態函式庫。
add_library(libstatic1 STATIC)

target_sources(libstatic1
    PRIVATE
        "f1.cpp"
        "f2.cpp"
)

## 搭配 Visual Studio Code

Visual Studio Code 的使用者介面（[官方文件](https://code.visualstudio.com/docs/getstarted/userinterface)）：


### 安裝

Visual Studio Code下載頁面：https://code.visualstudio.com/download

使用到的延伸模組：
* [C/C++](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools)
* [CMake Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools)

在左側**活動列**點選**延伸模組**按鈕，在 Marketplace 中搜尋上面列出來的模組並安裝。

### 設定檔

在 CMake 專案的根目錄建立`.vscode`資料夾，並在裡面新增[工作區設定檔](https://code.visualstudio.com/docs/getstarted/settings#_workspace-settings)，`settings.json`。開啟設定檔中請將`cmake.generator` 設成 `Ninja`。如下列原始碼：

`.vscode/settings.json`

{
    // 設定CMake產生器
    "cmake.generator": "Ninja",
    // 設定CMake變數
    "cmake.configureSettings": {
        // 例:
        // CMAKE_C_COMPILER: "C:/TDM-GCC-64/bin/gcc.exe"
        // CMAKE_CXX_COMPILER: "C:/TDM-GCC-64/bin/g++.exe"
        // CMAKE_PREFIX_PATH: "<list-of-search-paths>"
        // CMAKE_INSTALL_PREFIX: "<prefix-of-installation-path>"
        // ......
    },
}

`cmake.configureSettings` 是設定 CMake 的變數，可以指定C/C++編譯器路徑，可執行檔的安裝路徑等等。可以先留空。

### 開啟 CMake 專案

**檔案→開啟資料夾**，開啟 CMake 專案的根目錄。

VSCode 會提示是否要執行 CMake 配置，選擇 Yes。


在上方出現的選單中選擇GCC。VSCode會自動開始CMake配置，配置完成後你會在輸出的方框內看到完成配置和完成產生的訊息。


完成配置後，按下方狀態列的播放鍵編譯並執行。

## 搭配 Visual Studio

近年來微軟已經把 CMake 整合進 Visual Studio 的 C++ 工作負載中，現在在 Visual Studio 中建立和開啟 CMake 專案已經是再簡單不過的事。

### 開啟 CMake 專案

在**開始視窗**點選**開啟本機資料夾**，或是在主視窗的選單點擊**檔案→開啟→資料夾**。在開啟的對話視窗選擇 CMake 專案的根目錄，也就是最上層的`CMakeLists.txt`資料夾。開啟後請稍微等一下，Visual Studio會自動開始配置CMake的快取。如果在配置期沒有出現問題，Visual Studio會在輸出面板回報「已完成 CMake 的產生」。


在選取啟動項目的下拉選單選取 CMake 目標就可以編譯並執行。


### 建立 CMake 專案

在**開始視窗**點選**建立新的專案→CMake 專案**，或是在主視窗的選單點擊**檔案→新增→專案→CMake 專案**。一樣勾選「將解決方案與專案置於相同目錄中」簡化目錄結構。


> Visual Studio 2017
>
> 檔案→新增→專案→已安裝→Visual C++→跨平台→CMake→CMake 專案
> 取消勾選「為方案建立目錄」。

## 搭配 KDevelop


### 安裝

Windows和macOS使用者請到此下載：https://www.kdevelop.org/download

Linux上可以直接由發行版的套件管理工具安裝：

# Debian/Ubuntu
apt install kdevelop

# Fedora
dnf install kdevelop

# openSUSE
zypper install kdevelop5

### 建立專案

**專案 → 由樣本建立...** 開啟「建立新專案」的視窗。選擇專案模板：**Standard → Terminal**，右欄選單選擇`CMake C++`。

### 開啟專案

**專案 → 開啟/匯入專案...**，選擇 CMake 專案的根目錄（`CMakeListst.txt`所在的位置）。開啟後你會看見 Project Manager 欄位顯示為 `CMakeListst.txt (CMake Project Manager)`，按完成。


接下來進到專案的初始設定。KDevelop把建置目錄（Build directory）預設在`<CMake專案根目錄>/build`，但我們希望編譯產生的檔案會依照編譯型態（Debug 或 Release）分成不同資料夾。所以請在建置目錄的`.../build`之後接一個依照編譯型態命名的資料夾。簡而言之，Debug組態的建置目錄變成`<CMake專案根目錄>/build/Debug`，而待會提到的Release組態的建置目錄會變成`<CMake專案根目錄>/build/Release`。


開啟專案後，等待 CMake 執行配置。如果看到下方輸出訊息顯示「Configuring done」和「Generating done」表示 CMake 成功產生快取。在側邊欄點擊專案分頁就可以開始瀏覽和撰寫程式碼囉！


### 編譯

如果你的 CMake 專案依照上述的步驟有成功產生快取的話，就可以開始編譯了。按左上角工作列的「編譯」，或是按`F8`。

### 執行

按下工作列的執行，或是 `Shift+F9`。

#### 設定啟動器

當編譯完成後你按下工作列上的執行，KDevelop 會跳出一個**啟動設定**的視窗，尋問你應該如何啟動你的專案。在左上角**新增**選單中選擇我們專案中的 **CMake 目標**。以 `Project02` 為例，在選單中你會看到透過 `add_executable` 加入的 `project-02`，還有 `add_library` 加入的 `libstatic1`。因為我們想要「啟動」的是 `project-02` 這個可執行檔，所以選擇它。


新增完成後，你會看到右側面板有一欄**專案目標**顯示「Project02/project-02」。這就是你預設要啟動的目標了，按 OK。

> 為何要多一個這樣的設定而不是直接執行？假設未來在開發大型應用程式時，一個專案可能包含好幾個部件，有主程式相依於其他可執行檔或函式庫。那這時你就會需要指定每個部件的執行順序。

#### 多個啟動器

上方「執行選單 → 設定啟動器...」可以再新增啟動方式。啟動器一次只能選擇一個，也就是當你按下`Shift+F9`時會代入的設定。到「執行選單 → 目前的啟動設定」做切換。

### 新增編譯組態

在開啟專案時，我們設定了Debug組態。現在來新增Release組態。在主選單點擊**專案 → 開啟設定...**，進到「設定專案」的頁面後點擊右上角的「+」按鈕。


又是剛剛設定建置目錄的頁面。編譯型態選擇`Release`，建置目錄請記得設為`<CMake專案根目錄>/build/Release`。


上述設定完成後按 OK → Apply，你就可以在設定專案的頁面選擇 Debug 或 Release：


## 使用 Command Line

將終端機的工作目錄切換到專案的根目錄，再用 `cmake` 產生 CMake 快取，最後執行建置。在命令列使用 `cmake` 指令產生CMake快取時，用到的參數種類主要有下列四種：

 cmake -S <專案目錄>
       -B <建置目錄>
       -G <產生器>
       -D <變數>=<值>

1. `-S`，指定原始碼目錄。通常是專案的根目錄。如果沒有此選項，預設是終端機當下的**工作目錄**。
2. `-B`，指定建置目錄。通常會在專案根目錄之下多一個 `build/` 或 `out/` 資料夾存放 CMake 快取和建置期產生的檔案（例如可執行檔）。
4. `-G`，指定用來生成原生建置系統檔案的 [CMake 產生器](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html)。常用的是 `Makefile` 或 `Ninja`，有支援 CMake 專案的 IDE 通常也是搭配上述其中一個。
3. `-D`，定義 CMake 變數。例如 [`CMAKE_BUILD_TYPE`](https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html) 和 [`CMAKE_MAKE_PROGRAM`](https://cmake.org/cmake/help/latest/variable/CMAKE_MAKE_PROGRAM.html)。

將參數換行可以增加可讀性，但必須要用跳脫字元來接續。

### 產生 CMake 快取

#### Linux

# 類Unix系統的殼層（shell）中跳脫字元為反斜線（backslash）：「\」。
# Debug
cmake -B build/Debug -G Ninja \
-D CMAKE_BUILD_TYPE=Debug 

# Release
cmake -B build/Release -G Ninja \
-D CMAKE_BUILD_TYPE=Release

#### macOS

# 類Unix系統的殼層（shell）中跳脫字元為反斜線（backslash）：「\」。
# Debug
cmake -B build/Debug -G Ninja \
-D CMAKE_BUILD_TYPE=Debug 

# Release
cmake -B build/Release -G Ninja \
-D CMAKE_BUILD_TYPE=Release

#### Windows
終端機建議到微軟商店下載 Windows Terminal 使用。

PowerShell

# 如果電腦上有安裝多個C/C++編譯器，可以透過設定CC/CXX環境變數指定編譯器。
$Env:CC = "C:/TDM-GCC-64/bin/gcc.exe";
$Env:CXX = "C:/TDM-GCC-64/bin/g++.exe";

# PowerShell的跳脫字元為反引號（backtick）：「`」
# Debug
cmake -B build/Debug -G Ninja `
-D CMAKE_MAKE_PROGRAM="C:/dev/bin/ninja.exe" `
-D CMAKE_BUILD_TYPE=Debug 

# Release
cmake -B build/Release -G Ninja `
-D CMAKE_MAKE_PROGRAM="C:/dev/bin/ninja.exe" `
-D CMAKE_BUILD_TYPE=Release

CMD（命令提示字元）

:: 如果電腦上有安裝多個C/C++編譯器，可以透過設定CC/CXX環境變數指定編譯器。
set CC="C:/TDM-GCC-64/bin/gcc.exe";
set CXX="C:/TDM-GCC-64/bin/g++.exe";

:: CMD的跳脫字元為脫字符（caret）：「^」。
:: Debug
cmake -B build/Debug -G Ninja ^
-D CMAKE_MAKE_PROGRAM="C:/dev/bin/ninja.exe" ^
-D CMAKE_BUILD_TYPE=Debug 

:: Release
cmake -B build/Release -G Ninja ^
-D CMAKE_MAKE_PROGRAM="C:/dev/bin/ninja.exe" ^
-D CMAKE_BUILD_TYPE=Release

### 編譯

`cmake --build` 後面接剛才 CMake 產生快取的位置。

# Debug
cmake --build build/Debug

# Release
cmake --build build/Release

### 執行

產生出的可執行檔會放在 CMake 快取資料夾中，名稱會是 CMake 目標名稱。例如 `build/Debug/<target-name>.exe`。可以在終端機用相對路徑的方式執行它，如果終端機的目錄在專案根目錄，執行的方式就是`./build/Debug/<target-name>.exe`。

## 安裝

CMake 提供 `install` 指令來指示一個專案應該怎麼安裝。簡單來說，是把專案編譯後產生的執行檔、函式庫和各式資源複製到每個作業系統上預設的安裝路徑，例如 Windows 上的 `C:\Program Files` 或 Linux 上的 `/usr`。開發者也能夠藉由設定 CMake 變數來指定安裝路徑。

### 為何需要安裝專案

程式開啟時都有所謂的「**工作目錄（Working directory）**」，通常就是可執行檔所在的位置。當程式在讀取外部檔案時，找尋檔案的路徑是從工作目錄開始算起。所以如果程式碼中你要讀取一個路徑為`TestData/hello.txt`的測試檔案，當程式編譯完成要執行時，`hello.txt` 就必須放在可執行檔所在資料夾之下的`TestData/`資料夾。

工作目錄不一定都是可執行檔所在的資料夾，如果你是從終端機（例：命令提示字元）執行程式，則工作目錄會是你終端機所在的目錄。假設現在有一個可執行檔 `a.exe` 位於`<專案根目錄>/build/Debug/`資料夾中。如果你終端機進到`<專案根目錄>`並透過輸入`./build/Debug/a.exe` 執行程式，那麼依剛才的範例，`a.exe`找的檔案路徑就會是`<專案根目錄>/TestData/hello.txt`。

一般的整合開發環境（IDE）在執行你的程式時預設的工作目錄會是可執行檔的目錄。因此，若`hello.txt`放在專案的`TestData` 資料夾之下（即`<專案根目錄>/TestData/hello.txt`），那麼位於 `<專案根目錄>/build/Debug/` 的`a.exe`在執行時就會找不到它。CMake的`install`指令可把建置出的 CMake 目標（可執行檔）和程式的資源（例如範例的`hello.txt`）安裝到同一個資料夾下。但這個資料夾的預設路徑會是系統安裝應用程式的地方，例如`C:/Program Files/`。如果我們不希望讓自己測試的東西就這樣安裝在系統上，就可以透過定義 `CMAKE_INSTALL_PREFIX` 變數來改變安裝的路徑。

### 開發工具設定

#### Visual Studio

不需額外設定變數，在**選取啟動項目**的選單中選擇「`<可執行檔名稱>.exe (安裝)`」的選項即可。

#### Visual Studio Code

在工作區設定檔（`.vscode/settings.json`）中的 `cmake.configureSettings` 加入`CMAKE_INSTALL_PREFIX` 變數。並加入`cmake.debugConfig`的設定，如下：

`.vscode/settings.json`

{
    "cmake.generator": "Ninja",
    "cmake.debugConfig": {
        "cwd": "${workspaceFolder}/installed"
    },
    "cmake.configureSettings": {
        "CMAKE_INSTALL_PREFIX": "${workspaceFolder}/installed"
    }
}

請在 CMake Tools 下方的工具列把預設的建置目標從`[all]`改成`[install]`，再執行 `Build`，你就會看到專案根目錄多了一個 `install/` 資料夾。這時就可以按執行了。

#### KDevelop

在建立專案時的 `Extra arguments` 欄位輸入 `-DCMAKE_INSTALL_PREFIX=<專案根目錄>/install`。若是已經建立的專案，請到**專案→設定專案→顯示進階→Extra arguments**修改。

在設定啟動器的視窗中，請將上方執行檔的路徑指向`install/`資料夾中的可執行檔。還有在下方相依性的部分，把動作欄位改成編譯並安裝。

#### Command Line

產生 CMake 快取時，在 `cmake` 的參數的部分加上 `-D CMAKE_INSTALL_PREFIX=<專案根目錄>/install`。例如：

cmake -B build/Debug -G Ninja \
-D CMAKE_BUILD_TYPE=Debug \
-D CMAKE_INSTALL_PREFIX=<專案根目錄>/install

編譯並安裝

cmake --build build/Debug --target install

進到 `install/` 資料夾，讓工作目錄位於 `<專案根目錄>/install/` 再執行。

cd install/
./<target-name>.exe

## VCPKG

### VSCode

{
    "cmake.buildDirectory": "${workspaceFolder}/build",
    "cmake.generator": "Ninja",
    "cmake.configureSettings": {
        "CMAKE_TOOLCHAIN_FILE": "<path-to-vcpkg.cmake>",
        "VCPKG_TARGET_TRIPLET": "x64-windows",
        "CMAKE_RC_COMPILER": "<path-to-windres.exe>"
    }
}