8.1 使用超級構建模式 · cmake-cookbook

# 8.1 使用超級構建模式 **NOTE**:*此示例代碼可以在 https://github.com/dev-cafe/cmake-cookbook/tree/v1.0/chapter-8/recipe-01 中找到，其中有一個C++示例。該示例在CMake 3.5版(或更高版本)中是有效的，并且已經在GNU/Linux、macOS和Windows上進行過測試。* 本示例通過一個簡單示例，介紹超級構建模式。我們將展示如何使用`ExternalProject_Add`命令來構建一個的“Hello, World”程序。 ## 準備工作本示例將從以下源代碼(`Hello-World.cpp`)構建“Hello, World”可執行文件: ```c++ #include <cstdlib> #include <iostream> #include <string> std::string say_hello() { return std::string("Hello, CMake superbuild world!"); } int main() { std::cout << say_hello() << std::endl; return EXIT_SUCCESS; } ``` 項目結構如下: ```shell . ├── CMakeLists.txt └── src ├── CMakeLists.txt └── hello-world.cpp ``` ## 具體實施讓我們看一下根目錄下的CMakeLists.txt： 1. 聲明一個C++11項目，以及CMake最低版本: ```cmake cmake_minimum_required(VERSION 3.5 FATAL_ERROR) project(recipe-01 LANGUAGES CXX) set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_EXTENSIONS OFF) set(CMAKE_CXX_STANDARD_REQUIRED ON) ``` 2. 為當前目錄和底層目錄設置`EP_BASE`目錄屬性: ```cmake set_property(DIRECTORY PROPERTY EP_BASE ${CMAKE_BINARY_DIR}/subprojects) ``` 3. 包括`ExternalProject.cmake`標準模塊。該模塊提供了`ExternalProject_Add`函數: ```cmake include(ExternalProject) ``` 4. “Hello, World”源代碼通過調用`ExternalProject_Add`函數作為外部項目添加的。外部項目的名稱為`recipe-01_core`: ```cmake ExternalProject_Add(${PROJECT_NAME}_core ``` 5. 使用`SOURCE_DIR`選項為外部項目設置源目錄: ```cmake SOURCE_DIR ${CMAKE_CURRENT_LIST_DIR}/src ``` 6. `src`子目錄包含一個完整的CMake項目。為了配置和構建它，通過`CMAKE_ARGS`選項將適當的CMake選項傳遞給外部項目。例子中，只需要通過C++編譯器和C++標準的要求即可: ```cmake CMAKE_ARGS -DCMAKE_CXX_COMPILER=${CMAKE_CXX_COMPILER} -DCMAKE_CXX_STANDARD=${CMAKE_CXX_STANDARD} -DCMAKE_CXX_EXTENSIONS=${CMAKE_CXX_EXTENSIONS} -DCMAKE_CXX_STANDARD_REQUIRED=${CMAKE_CXX_STANDARD_REQUIRED} ``` 7. 我們還設置了C++編譯器標志。這些通過使用`CMAKE_CACHE_ARGS`選項傳遞到`ExternalProject_Add`中: ```cmake CMAKE_CACHE_ARGS -DCMAKE_CXX_FLAGS:STRING=${CMAKE_CXX_FLAGS} ``` 8. 我們配置外部項目，使它進行構建: ```cmake BUILD_ALWAYS 1 ``` 9. 安裝步驟不會執行任何操作(我們將在第4節中重新討論安裝，在第10章中安裝超級構建，并編寫安裝程序): ```cmake INSTALL_COMMAND "" ) ``` 現在，我們來看看`src/CMakeLists.txt`。由于我們將“Hello, World”源文件作為一個外部項目添加，這是一個獨立項目的`CMakeLists.txt`文件: 1. 這里聲明CMake版本最低要求: ```cmake cmake_minimum_required(VERSION 3.5 FATAL_ERROR) ``` 2. 聲明一個C++項目： ```cmake project(recipe-01_core LANGUAGES CXX) ``` 3. 最終，使用`hello-world.cpp`源碼文件生成可執行目標`hello-world`： ```cmake add_executable(hello-world hello-world.cpp) ``` 配置構建項目： ```shell $ mkdir -p build $ cmake .. $ cmake --build . ``` 構建目錄的結構稍微復雜一些，`subprojects`文件夾的內容如下: ```shell build/subprojects/ ├── Build │ └── recipe-01_core │ ├── CMakeCache.txt │ ├── CMakeFiles │ ├── cmake_install.cmake │ ├── hello-world │ └── Makefile ├── Download │ └── recipe-01_core ├── Install │ └── recipe-01_core ├── Stamp │ └── recipe-01_core │ ├── recipe-01_core-configure │ ├── recipe-01_core-done │ ├── recipe-01_core-download │ ├── recipe-01_core-install │ ├── recipe-01_core-mkdir │ ├── recipe-01_core-patch │ └── recipe-01_core-update └── tmp └── recipe-01_core ├── recipe-01_core-cache-.cmake ├── recipe-01_core-cfgcmd.txt └── recipe-01_core-cfgcmd.txt.in ``` `recipe-01_core`已經構建到`build/subprojects`子目錄中，稱為`Build/recipe-01_core`(這是我們設置的`EP_BASE`)。 `hello-world`可執行文件在`Build/recipe-01_core`下創建，其他子文件夾`tmp/recipe-01_core`和`Stamp/recipe-01_core`包含臨時文件，比如：CMake緩存腳本`recipe-01_core-cache-.cmake`和已執行的外部構建項目的各步驟的時間戳文件。 ## 工作原理 `ExternalProject_Add`命令可用于添加第三方源。然而，第一個例子展示了，如何將自己的項目，分為不同CMake項目的集合管理。本例中，主`CMakeLists.txt`和子`CMakeLists.txt`都聲明了一個CMake項目，它們都使用了`project`命令。 `ExternalProject_Add`有許多選項，可用于外部項目的配置和編譯等所有方面。這些選擇可以分為以下幾類: * **Directory**：它們用于調優源碼的結構，并為外部項目構建目錄。本例中，我們使用`SOURCE_DIR`選項讓CMake知道源文件在`${CMAKE_CURRENT_LIST_DIR}/src`文件夾中。用于構建項目和存儲臨時文件的目錄，也可以在此類選項或目錄屬性中指定。通過設置`EP_BASE`目錄屬性，CMake將按照以下布局為各個子項目設置所有目錄: ```shell TMP_DIR = <EP_BASE>/tmp/<name> STAMP_DIR = <EP_BASE>/Stamp/<name> DOWNLOAD_DIR = <EP_BASE>/Download/<name> SOURCE_DIR = <EP_BASE>/Source/<name> BINARY_DIR = <EP_BASE>/Build/<name> INSTALL_DIR = <EP_BASE>/Install/<name> ``` * **Download**：外部項目的代碼可能需要從在線存儲庫或資源處下載。 * **Update**和**Patch**：可用于定義如何更新外部項目的源代碼或如何應用補丁。 * **Configure**：默認情況下，CMake會假定外部項目是使用CMake配置的。如下面的示例所示，我們并不局限于這種情況。如果外部項目是CMake項目，`ExternalProject_Add`將調用CMake可執行文件，并傳遞選項。對于當前的示例，我們通過`CMAKE_ARGS`和`CMAKE_CACHE_ARGS`選項傳遞配置參數。前者作為命令行參數直接傳遞，而后者通過CMake腳本文件傳遞。示例中，腳本文件位于`build/subprojects/tmp/recipe-01_core/recipe-01_core- cache-.cmake`。然后，配置如以下所示: ```shell $ cmake -DCMAKE_CXX_COMPILER=g++ -DCMAKE_CXX_STANDARD=11 -DCMAKE_CXX_EXTENSIONS=OFF -DCMAKE_CXX_STANDARD_REQUIRED=ON -C/home/roberto/Workspace/robertodr/cmake-cookbook/chapter-08/recipe-01/cxx-example/build/subprojects/tmp/recipe-01_core/recipe-01_core-cache-.cmake "-GUnix Makefiles" /home/roberto/Workspace/robertodr/cmake-cookbook/chapter-08/recipe-01/cxx-example/src ``` * **Build**：可用于調整外部項目的實際編譯。我們的示例使用`BUILD_ALWAYS`選項確保外部項目總會重新構建。 * **Install**：這些選項用于配置應該如何安裝外部項目。我們的示例將`INSTALL_COMMAND`保留為空，我們將在第10章(編寫安裝程序)中更詳細地討論與CMake的安裝。 * **Test**：為基于源代碼構建的軟件運行測試總是不錯的想法。`ExternalProject_Add`的這類選項可以用于此目的。我們的示例沒有使用這些選項，因為“Hello, World”示例沒有任何測試，但是在第5節中，您將管理超級構建的項目，屆時將觸發一個測試步驟。 `ExternalProject.cmake`定義了`ExternalProject_Get_Property`命令，該命令對于檢索外部項目的屬性非常有用。外部項目的屬性是在首次調用`ExternalProject_Add`命令時設置的。例如，在配置`recipe-01_core`時，檢索要傳遞給CMake的參數可以通過以下方法實現: ```cmake ExternalProject_Get_Property(${PROJECT_NAME}_core CMAKE_ARGS) message(STATUS "CMAKE_ARGS of ${PROJECT_NAME}_core ${CMAKE_ARGS}") ``` **NOTE**:*`ExternalProject_Add`的完整選項列表可以在CMake文檔中找到:https://cmake.org/cmake/help/v3.5/module/ExternalProject.html#command:ExternalProject_Add* ## 更多信息下面的示例中，我們將詳細討論`ExternalProject_Add`命令的靈活性。然而，有時我們希望使用的外部項目可能需要執行額外的步驟。由于這個原因，`ExternalProject.cmake`模塊定義了以下附加命令: 1. `ExternalProject_Add_Step `: 當添加了外部項目，此命令允許將附加的命令作為自定義步驟鎖定在其上。參見:https://cmake.org/cmake/help/v3.5/module/externalproject.htm#command:externalproject_add_step 2. `ExternalProject_Add_StepTargets`:允許將外部項目中的步驟(例如：構建和測試步驟)定義為單獨的目標。這意味著可以從完整的外部項目中單獨觸發這些步驟，并允許對項目中的復雜依賴項，進行細粒度控制。參見:https://cmake.org/cmake/help/v3.5/module/ExternalProject.htm#command:externalproject_add_steptargets 3. `ExternalProject_Add_StepDependencies`:外部項目的步驟有時可能依賴于外部目標，而這個命令的設計目的就是處理這些情況。參見:https://cmake.org/cmake/help/v3.5/module/ExternalProject.html#command:externalproject_add_stepdependencies