# 5.3 構建時運行自定義命令:Ⅰ. 使用add_custom_command
**NOTE**:*此示例代碼可以在 https://github.com/dev-cafe/cmake-cookbook/tree/v1.0/chapter-5/recipe-03 中找到,其中包含一個C++例子。該示例在CMake 3.5版(或更高版本)中是有效的,并且已經在GNU/Linux、macOS和Windows上進行過測試。*
項目的構建目標取決于命令的結果,這些命令只能在構建系統生成完成后的構建執行。CMake提供了三個選項來在構建時執行自定義命令:
1. 使用`add_custom_command`編譯目標,生成輸出文件。
2. `add_custom_target`的執行沒有輸出。
3. 構建目標前后,`add_custom_command`的執行可以沒有輸出。
這三個選項強制執行特定的語義,并且不可互換。接下來的三個示例將演示具體的用法。
## 準備工作
我們將重用第3章第4節中的C++示例,以說明如何使用`add_custom_command`的第一個選項。代碼示例中,我們了解了現有的BLAS和LAPACK庫,并編譯了一個很小的C++包裝器庫,以調用線性代數的Fortran實現。
我們將把代碼分成兩部分。` linear-algebra.cpp `的源文件與第3章、第4章沒有區別,并且將包含線性代數包裝器庫的頭文件和針對編譯庫的鏈接。源代碼將打包到一個壓縮的tar存檔文件中,該存檔文件隨示例項目一起提供。存檔文件將在構建時提取,并在可執行文件生成之前,編譯線性代數的包裝器庫。
## 具體實施
`CMakeLists.txt`必須包含一個自定義命令,來提取線性代數包裝器庫的源代碼:
1. 從CMake最低版本、項目名稱和支持語言的定義開始:
```cmake
cmake_minimum_required(VERSION 3.5 FATAL_ERROR)
project(recipe-03 LANGUAGES CXX Fortran)
```
2. 選擇C++11標準:
```cmake
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_EXTENSIONS OFF)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
```
3. 然后,在系統上查找BLAS和LAPACK庫:
```cmake
find_package(BLAS REQUIRED)
find_package(LAPACK REQUIRED)
```
4. 聲明一個變量`wrap_BLAS_LAPACK_sources`來保存`wrap_BLAS_LAPACK.tar.gz`壓縮包文件的名稱:
```cmake
set(wrap_BLAS_LAPACK_sources
${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK/CxxBLAS.hpp
${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK/CxxBLAS.cpp
${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK/CxxLAPACK.hpp
${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK/CxxLAPACK.cpp
)
```
5. 聲明自定義命令來提取`wrap_BLAS_LAPACK.tar.gz`壓縮包,并更新提取文件的時間戳。注意這個`wrap_BLAS_LAPACK_sources`變量的預期輸出:
```cmake
add_custom_command(
OUTPUT
${wrap_BLAS_LAPACK_sources}
COMMAND
${CMAKE_COMMAND} -E tar xzf ${CMAKE_CURRENT_SOURCE_DIR}/wrap_BLAS_LAPACK.tar.gz
COMMAND
${CMAKE_COMMAND} -E touch ${wrap_BLAS_LAPACK_sources}
WORKING_DIRECTORY
${CMAKE_CURRENT_BINARY_DIR}
DEPENDS
${CMAKE_CURRENT_SOURCE_DIR}/wrap_BLAS_LAPACK.tar.gz
COMMENT
"Unpacking C++ wrappers for BLAS/LAPACK"
VERBATIM
)
```
6. 接下來,添加一個庫目標,源文件是新解壓出來的:
```cmake
add_library(math "")
target_sources(math
PRIVATE
${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK/CxxBLAS.cpp
${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK/CxxLAPACK.cpp
PUBLIC
${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK/CxxBLAS.hpp
${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK/CxxLAPACK.hpp
)
target_include_directories(math
INTERFACE
${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK
)
target_link_libraries(math
PUBLIC
${LAPACK_LIBRARIES}
)
```
7. 最后,添加`linear-algebra`可執行目標。可執行目標鏈接到庫:
```cmake
add_executable(linear-algebra linear-algebra.cpp)
target_link_libraries(linear-algebra
PRIVATE
math
)
```
8. 我們配置、構建和執行示例:
```shell
$ mkdir -p build
$ cd build
$ cmake ..
$ cmake --build .
$ ./linear-algebra 1000
C_DSCAL done
C_DGESV done
info is 0
check is 4.35597e-10
```
## 工作原理
讓我們來了解一下`add_custom_command`的使用:
```cmake
add_custom_command(
OUTPUT
${wrap_BLAS_LAPACK_sources}
COMMAND
${CMAKE_COMMAND} -E tar xzf ${CMAKE_CURRENT_SOURCE_DIR}/wrap_BLAS_LAPACK.tar.gz
COMMAND
${CMAKE_COMMAND} -E touch ${wrap_BLAS_LAPACK_sources}
WORKING_DIRECTORY
${CMAKE_CURRENT_BINARY_DIR}
DEPENDS
${CMAKE_CURRENT_SOURCE_DIR}/wrap_BLAS_LAPACK.tar.gz
COMMENT
"Unpacking C++ wrappers for BLAS/LAPACK"
VERBATIM
)
```
`add_custom_command`向目標添加規則,并通過執行命令生成輸出。`add_custom_command`中聲明的任何目標,即在相同的`CMakeLists.txt`中聲明的任何目標,使用輸出的任何文件作為源文件的目標,在構建時會有規則生成這些文件。因此,源文件生成在構建時,目標和自定義命令在構建系統生成時,將自動處理依賴關系。
我們的例子中,輸出是壓縮`tar`包,其中包含有源文件。要檢測和使用這些文件,必須在構建時提取打包文件。通過使用帶有`-E`標志的CMake命令,以實現平臺獨立性。下一個命令會更新提取文件的時間戳。這樣做是為了確保沒有處理陳舊文件。`WORKING_DIRECTORY`可以指定在何處執行命令。示例中,`CMAKE_CURRENT_BINARY_DIR`是當前正在處理的構建目錄。`DEPENDS`參數列出了自定義命令的依賴項。例子中,壓縮的`tar`是一個依賴項。CMake使用`COMMENT`字段在構建時打印狀態消息。最后,`VERBATIM`告訴CMake為生成器和平臺生成正確的命令,從而確保完全獨立。
我們來仔細看看這用使用方式和打包庫的創建:
```cmake
add_library(math "")
target_sources(math
PRIVATE
${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK/CxxBLAS.cpp
${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK/CxxLAPACK.cpp
PUBLIC
${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK/CxxBLAS.hpp
${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK/CxxLAPACK.hpp
)
target_include_directories(math
INTERFACE
${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK
)
target_link_libraries(math
PUBLIC
${LAPACK_LIBRARIES}
)
```
我們聲明一個沒有源的庫目標,是因為后續使用`target_sources`填充目標的源。這里實現了一個非常重要的目標,即讓依賴于此目標的目標,了解需要哪些目錄和頭文件,以便成功地使用庫。C++源文件的目標是`PRIVATE`,因此只用于構建庫。因為目標及其依賴項都需要使用它們來成功編譯,所以頭文件是`PUBLIC`。包含目錄使用`target_include_categories`指定,其中`wrap_BLAS_LAPACK`聲明為`INTERFACE`,因為只有依賴于`math`目標的目標需要它。
`add_custom_command`有兩個限制:
* 只有在相同的`CMakeLists.txt`中,指定了所有依賴于其輸出的目標時才有效。
* 對于不同的獨立目標,使用`add_custom_command`的輸出可以重新執行定制命令。這可能會導致沖突,應該避免這種情況的發生。
第二個限制,可以使用`add_dependencies`來避免。不過,規避這兩個限制的正確方法是使用`add_custom_target`命令,我們將在下一節的示例中詳細介紹。
- 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 留下評論——讓其他讀者知道你的想法