# 1.1 將單個源文件編譯為可執行文件
**NOTE**:*此示例代碼可以在 https://github.com/dev-cafe/cmake-cookbook/tree/v1.0/chapter-01/recipe-01 中找到,包含C++、C和Fortran示例。該示例在CMake 3.5版(或更高版本)中是有效的,并且已經在GNU/Linux、macOS和Windows上進行過測試。*
本節示例中,我們將演示如何運行CMake配置和構建一個簡單的項目。該項目由單個源文件組成,用于生成可執行文件。我們將用C++討論這個項目,您在GitHub示例庫中可以找到C和Fortran的例子。
## 準備工作
我們希望將以下源代碼編譯為單個可執行文件:
```c++
#include <cstdlib>
#include <iostream>
#include <string>
std::string say_hello() { return std::string("Hello, CMake world!"); }
int main() {
std::cout << say_hello() << std::endl;
return EXIT_SUCCESS;
}
```
## 具體實施
除了源文件之外,我們還需要向CMake提供項目配置描述。該描述使用CMake完成,完整的文檔可以在 https://cmake.org/cmake/help/latest/ 找到。我們把CMake指令放入一個名為`CMakeLists.txt`的文件中。
**NOTE**:*文件的名稱區分大小寫,必須命名為`CMakeLists.txt`,CMake才能夠解析。*
具體步驟如下:
1. 用編輯器打開一個文本文件,將這個文件命名為`CMakeLists.txt`。
2. 第一行,設置CMake所需的最低版本。如果使用的CMake版本低于該版本,則會發出致命錯誤:
```cmake
cmake_minimum_required(VERSION 3.5 FATAL_ERROR)
```
3. 第二行,聲明了項目的名稱(`recipe-01`)和支持的編程語言(CXX代表C++):
```cmake
project(recipe-01 LANGUAGES CXX)
```
4. 指示CMake創建一個新目標:可執行文件`hello-world`。這個可執行文件是通過編譯和鏈接源文件`hello-world.cpp`生成的。CMake將為編譯器使用默認設置,并自動選擇生成工具:
```cmake
add_executable(hello-world hello-world.cpp)
```
5. 將該文件與源文件`hello-world.cpp`放在相同的目錄中。記住,它只能被命名為`CMakeLists.txt`。
6. 現在,可以通過創建`build`目錄,在`build`目錄下來配置項目:
```shell
$ mkdir -p build
$ cd build
$ cmake ..
-- The CXX compiler identification is GNU 8.1.0
-- Check for working CXX compiler: /usr/bin/c++
-- Check for working CXX compiler: /usr/bin/c++ -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Configuring done
-- Generating done
-- Build files have been written to: /home/user/cmake-cookbook/chapter-01/recipe-01/cxx-example/build
```
7. 如果一切順利,項目的配置已經在`build`目錄中生成。我們現在可以編譯可執行文件:
```shell
$ cmake --build .
Scanning dependencies of target hello-world
[ 50%] Building CXX object CMakeFiles/hello-world.dir/hello-world.cpp.o
[100%] Linking CXX executable hello-world
[100%] Built target hello-world
```
## 工作原理
示例中,我們使用了一個簡單的`CMakeLists.txt`來構建“Hello world”可執行文件:
```cmake
cmake_minimum_required(VERSION 3.5 FATAL_ERROR)
project(recipe-01 LANGUAGES CXX)
add_executable(hello-world hello-world.cpp)
```
**NOTE**:*CMake語言不區分大小寫,但是參數區分大小寫。*
**TIPS**:*CMake中,C++是默認的編程語言。不過,我們還是建議使用`LANGUAGES`選項在`project`命令中顯式地聲明項目的語言。*
要配置項目并生成構建器,我們必須通過命令行界面(CLI)運行CMake。CMake CLI提供了許多選項,`cmake -help`將輸出以顯示列出所有可用選項的完整幫助信息,我們將在書中對這些選項進行更多地了解。正如您將從`cmake -help`的輸出中顯示的內容,它們中的大多數選項會讓你您訪問CMake手冊,查看詳細信息。通過下列命令生成構建器:
```shell
$ mkdir -p build
$ cd build
$ cmake ..
```
這里,我們創建了一個目錄`build`(生成構建器的位置),進入`build`目錄,并通過指定`CMakeLists.txt`的位置(本例中位于父目錄中)來調用CMake。可以使用以下命令行來實現相同的效果:
```shell
$ cmake -H. -Bbuild
```
該命令是跨平臺的,使用了`-H`和`-B`為CLI選項。`-H`表示當前目錄中搜索根`CMakeLists.txt`文件。`-Bbuild`告訴CMake在一個名為`build`的目錄中生成所有的文件。
**NOTE**:*`cmake -H. -Bbuild`也屬于CMake標準使用方式: https://cmake.org/pipermail/cmake-developers/2018-January/030520.html 。不過,我們將在本書中使用傳統方法(創建一個構建目錄,進入其中,并通過將CMake指向`CMakeLists.txt`的位置來配置項目)。*
運行`cmake`命令會輸出一系列狀態消息,顯示配置信息:
```shell
$ cmake ..
-- The CXX compiler identification is GNU 8.1.0
-- Check for working CXX compiler: /usr/bin/c++
-- Check for working CXX compiler: /usr/bin/c++ -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Configuring done
-- Generating done
-- Build files have been written to: /home/user/cmake-cookbook/chapter-01/recipe-01/cxx-example/build
```
**NOTE**:*在與`CMakeLists.txt`相同的目錄中執行`cmake .`,原則上足以配置一個項目。然而,CMake會將所有生成的文件寫到項目的根目錄中。這將是一個源代碼內構建,通常是不推薦的,因為這會混合源代碼和項目的目錄樹。我們首選的是源外構建。*
CMake是一個構建系統生成器。將描述構建系統(如:Unix Makefile、Ninja、Visual Studio等)應當如何操作才能編譯代碼。然后,CMake為所選的構建系統生成相應的指令。默認情況下,在GNU/Linux和macOS系統上,CMake使用Unix Makefile生成器。Windows上,Visual Studio是默認的生成器。在下一個示例中,我們將進一步研究生成器,并在第13章中重新討論生成器。
GNU/Linux上,CMake默認生成Unix Makefile來構建項目:
* `Makefile`: `make`將運行指令來構建項目。
* `CMakefile`:包含臨時文件的目錄,CMake用于檢測操作系統、編譯器等。此外,根據所選的生成器,它還包含特定的文件。
* `cmake_install.cmake`:處理安裝規則的CMake腳本,在項目安裝時使用。
* `CMakeCache.txt`:如文件名所示,CMake緩存。CMake在重新運行配置時使用這個文件。
要構建示例項目,我們運行以下命令:
```shell
$ cmake --build .
```
最后,CMake不強制指定構建目錄執行名稱或位置,我們完全可以把它放在項目路徑之外。這樣做同樣有效:
```shell
$ mkdir -p /tmp/someplace
$ cd /tmp/someplace
$ cmake /path/to/source
$ cmake --build .
```
## 更多信息
官方文檔 https://cmake.org/runningcmake/ 給出了運行CMake的簡要概述。由CMake生成的構建系統,即上面給出的示例中的Makefile,將包含為給定項目構建目標文件、可執行文件和庫的目標及規則。`hello-world`可執行文件是在當前示例中的唯一目標,運行以下命令:
```shell
$ cmake --build . --target help
The following are some of the valid targets for this Makefile:
... all (the default if no target is provided)
... clean
... depend
... rebuild_cache
... hello-world
... edit_cache
... hello-world.o
... hello-world.i
... hello-world.s
```
CMake生成的目標比構建可執行文件的目標要多。可以使用`cmake --build . --target <target-name>`語法,實現如下功能:
* **all**(或Visual Studio generator中的ALL_BUILD)是默認目標,將在項目中構建所有目標。
* **clean**,刪除所有生成的文件。
* **rebuild_cache**,將調用CMake為源文件生成依賴(如果有的話)。
* **edit_cache**,這個目標允許直接編輯緩存。
對于更復雜的項目,通過測試階段和安裝規則,CMake將生成額外的目標:
* **test**(或Visual Studio generator中的**RUN_TESTS**)將在CTest的幫助下運行測試套件。我們將在第4章中詳細討論測試和CTest。
* **install**,將執行項目安裝規則。我們將在第10章中討論安裝規則。
* **package**,此目標將調用CPack為項目生成可分發的包。打包和CPack將在第11章中討論。
- Introduction
- 前言
- 第0章 配置環境
- 0.1 獲取代碼
- 0.2 Docker鏡像
- 0.3 安裝必要的軟件
- 0.4 測試環境
- 0.5 上報問題并提出改進建議
- 第1章 從可執行文件到庫
- 1.1 將單個源文件編譯為可執行文件
- 1.2 切換生成器
- 1.3 構建和鏈接靜態庫和動態庫
- 1.4 用條件句控制編譯
- 1.5 向用戶顯示選項
- 1.6 指定編譯器
- 1.7 切換構建類型
- 1.8 設置編譯器選項
- 1.9 為語言設定標準
- 1.10 使用控制流
- 第2章 檢測環境
- 2.1 檢測操作系統
- 2.2 處理與平臺相關的源代碼
- 2.3 處理與編譯器相關的源代碼
- 2.4 檢測處理器體系結構
- 2.5 檢測處理器指令集
- 2.6 為Eigen庫使能向量化
- 第3章 檢測外部庫和程序
- 3.1 檢測Python解釋器
- 3.2 檢測Python庫
- 3.3 檢測Python模塊和包
- 3.4 檢測BLAS和LAPACK數學庫
- 3.5 檢測OpenMP的并行環境
- 3.6 檢測MPI的并行環境
- 3.7 檢測Eigen庫
- 3.8 檢測Boost庫
- 3.9 檢測外部庫:Ⅰ. 使用pkg-config
- 3.10 檢測外部庫:Ⅱ. 自定義find模塊
- 第4章 創建和運行測試
- 4.1 創建一個簡單的單元測試
- 4.2 使用Catch2庫進行單元測試
- 4.3 使用Google Test庫進行單元測試
- 4.4 使用Boost Test進行單元測試
- 4.5 使用動態分析來檢測內存缺陷
- 4.6 預期測試失敗
- 4.7 使用超時測試運行時間過長的測試
- 4.8 并行測試
- 4.9 運行測試子集
- 4.10 使用測試固件
- 第5章 配置時和構建時的操作
- 5.1 使用平臺無關的文件操作
- 5.2 配置時運行自定義命令
- 5.3 構建時運行自定義命令:Ⅰ. 使用add_custom_command
- 5.4 構建時運行自定義命令:Ⅱ. 使用add_custom_target
- 5.5 構建時為特定目標運行自定義命令
- 5.6 探究編譯和鏈接命令
- 5.7 探究編譯器標志命令
- 5.8 探究可執行命令
- 5.9 使用生成器表達式微調配置和編譯
- 第6章 生成源碼
- 6.1 配置時生成源碼
- 6.2 使用Python在配置時生成源碼
- 6.3 構建時使用Python生成源碼
- 6.4 記錄項目版本信息以便報告
- 6.5 從文件中記錄項目版本
- 6.6 配置時記錄Git Hash值
- 6.7 構建時記錄Git Hash值
- 第7章 構建項目
- 7.1 使用函數和宏重用代碼
- 7.2 將CMake源代碼分成模塊
- 7.3 編寫函數來測試和設置編譯器標志
- 7.4 用指定參數定義函數或宏
- 7.5 重新定義函數和宏
- 7.6 使用廢棄函數、宏和變量
- 7.7 add_subdirectory的限定范圍
- 7.8 使用target_sources避免全局變量
- 7.9 組織Fortran項目
- 第8章 超級構建模式
- 8.1 使用超級構建模式
- 8.2 使用超級構建管理依賴項:Ⅰ.Boost庫
- 8.3 使用超級構建管理依賴項:Ⅱ.FFTW庫
- 8.4 使用超級構建管理依賴項:Ⅲ.Google Test框架
- 8.5 使用超級構建支持項目
- 第9章 語言混合項目
- 9.1 使用C/C++庫構建Fortran項目
- 9.2 使用Fortran庫構建C/C++項目
- 9.3 使用Cython構建C++和Python項目
- 9.4 使用Boost.Python構建C++和Python項目
- 9.5 使用pybind11構建C++和Python項目
- 9.6 使用Python CFFI混合C,C++,Fortran和Python
- 第10章 編寫安裝程序
- 10.1 安裝項目
- 10.2 生成輸出頭文件
- 10.3 輸出目標
- 10.4 安裝超級構建
- 第11章 打包項目
- 11.1 生成源代碼和二進制包
- 11.2 通過PyPI發布使用CMake/pybind11構建的C++/Python項目
- 11.3 通過PyPI發布使用CMake/CFFI構建C/Fortran/Python項目
- 11.4 以Conda包的形式發布一個簡單的項目
- 11.5 將Conda包作為依賴項發布給項目
- 第12章 構建文檔
- 12.1 使用Doxygen構建文檔
- 12.2 使用Sphinx構建文檔
- 12.3 結合Doxygen和Sphinx
- 第13章 選擇生成器和交叉編譯
- 13.1 使用CMake構建Visual Studio 2017項目
- 13.2 交叉編譯hello world示例
- 13.3 使用OpenMP并行化交叉編譯Windows二進制文件
- 第14章 測試面板
- 14.1 將測試部署到CDash
- 14.2 CDash顯示測試覆蓋率
- 14.3 使用AddressSanifier向CDash報告內存缺陷
- 14.4 使用ThreadSaniiser向CDash報告數據爭用
- 第15章 使用CMake構建已有項目
- 15.1 如何開始遷移項目
- 15.2 生成文件并編寫平臺檢查
- 15.3 檢測所需的鏈接和依賴關系
- 15.4 復制編譯標志
- 15.5 移植測試
- 15.6 移植安裝目標
- 15.7 進一步遷移的措施
- 15.8 項目轉換為CMake的常見問題
- 第16章 可能感興趣的書
- 16.1 留下評論——讓其他讀者知道你的想法