8.5 使用超級構建支持項目 · cmake-cookbook

# 8.5 使用超級構建支持項目 **NOTE**:*此示例代碼可以在 https://github.com/dev-cafe/cmake-cookbook/tree/v1.0/chapter-8/recipe-05 中找到，其中有一個C++示例。該示例在CMake 3.5版(或更高版本)中是有效的，并且已經在GNU/Linux、macOS和Windows上進行過測試。* `ExternalProject`和`FetchContent`是CMake庫中兩個非常強大的工具。經過前面的示例，我們應該相信超級構建方法，在管理復雜依賴關系的項目時是多么有用。目前為止，我們已經展示了如何使用`ExternalProject`來處理以下問題: * 存儲在源樹中的源 * 從在線服務器上，檢索/獲取可用的存檔資源前面的示例展示了，如何使用`FetchContent`處理開源Git存儲庫中可用的依賴項。本示例將展示，如何使用`ExternalProject`達到同樣的效果。最后，將介紹一個示例，該示例將在第10章第4節中重用。 ## 準備工作這個超級構建的源代碼樹現在應該很熟悉了: ```shell . ├── CMakeLists.txt ├── external │ └── upstream │ ├── CMakeLists.txt │ └── message │ └── CMakeLists.txt └── src ├── CMakeLists.txt └── use_message.cpp ``` 根目錄有一個`CMakeLists.txt`，我們知道它會配合超級構建。子目錄`src`和`external`中是我們自己的源代碼，CMake指令需要滿足對消息庫的依賴，我們將在本例中構建消息庫。 ## 具體實施目前為止，建立超級構建的過程應該已經很熟悉了。讓我們再次看看必要的步驟，從根目錄的`CMakeLists.txt`開始: 1. 聲明一個C++11項目，并對項目構建類型的默認值進行設置。 ```cmake cmake_minimum_required(VERSION 3.6 FATAL_ERROR) project(recipe-05 LANGUAGES CXX) set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_EXTENSIONS OFF) set(CMAKE_CXX_STANDARD_REQUIRED ON) if(NOT DEFINED CMAKE_BUILD_TYPE OR "${CMAKE_BUILD_TYPE}" STREQUAL "") set(CMAKE_BUILD_TYPE Release CACHE STRING "Build type" FORCE) endif() message(STATUS "Build type set to ${CMAKE_BUILD_TYPE}") ``` 2. 設置`EP_BASE`目錄屬性。這將固定`ExternalProject`管理所有子項目的布局: ```cmake set_property(DIRECTORY PROPERTY EP_BASE ${CMAKE_BINARY_DIR}/subprojects) ``` 3. 我們設置了`STAGED_INSTALL_PREFIX`。與之前一樣，這個位置將作為依賴項的構建樹中的安裝目錄: ```cmake set(STAGED_INSTALL_PREFIX ${CMAKE_BINARY_DIR}/stage) message(STATUS "${PROJECT_NAME} staged install: ${STAGED_INSTALL_PREFIX}") ``` 4. 將` external/upstream`作為子目錄添加： ```cmake add_subdirectory(external/upstream) ``` 5. 添加`ExternalProject_Add`，這樣我們的項目也將由超級構建管理: ```cmake include(ExternalProject) ExternalProject_Add(${PROJECT_NAME}_core DEPENDS message_external SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/src CMAKE_ARGS -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE} -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} -Dmessage_DIR=${message_DIR} CMAKE_CACHE_ARGS -DCMAKE_CXX_FLAGS:STRING=${CMAKE_CXX_FLAGS} -DCMAKE_PREFIX_PATH:PATH=${CMAKE_PREFIX_PATH} BUILD_ALWAYS 1 INSTALL_COMMAND "" ) ``` ` external/upstream`的`CMakeLists.txt`中只包含一條命令: ```cmake add_subdirectory(message) ``` 跳轉到`message`文件夾，我們會看到對消息庫的依賴的常用命令: 1. 首先，調用`find_package`找到一個合適版本的庫: ```cmake find_package(message 1 CONFIG QUIET) ``` 2. 如果找到，會通知用戶，并添加一個虛擬`INTERFACE`庫: ```cmake get_property(_loc TARGET message::message-shared PROPERTY LOCATION) message(STATUS "Found message: ${_loc} (found version ${message_VERSION})") add_library(message_external INTERFACE) # dummy ``` 3. 如果沒有找到，再次通知用戶并繼續使用`ExternalProject_Add`: ```cmake message(STATUS "Suitable message could not be located, Building message instead.") ``` 4. 該項目托管在一個公共Git庫中，使用`GIT_TAG`選項指定下載哪個分支。和之前一樣，將`UPDATE_COMMAND`選項置為空: ```cmake include(ExternalProject) ExternalProject_Add(message_external GIT_REPOSITORY https://github.com/dev-cafe/message.git GIT_TAG master UPDATE_COMMAND "" ``` 5. 外部項目使用CMake配置和構建，傳遞必要的構建選項: ```cmake CMAKE_ARGS -DCMAKE_INSTALL_PREFIX=${STAGED_INSTALL_PREFIX} -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE} -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} CMAKE_CACHE_ARGS -DCMAKE_CXX_FLAGS:STRING=${CMAKE_CXX_FLAGS} ``` 6. 項目安裝后進行測試: ```cmake TEST_AFTER_INSTALL 1 ``` 7. 我們不希望看到下載進度，也不希望在屏幕上報告配置、構建和安裝信息，所以選擇關閉`ExternalProject_Add`: ```cmake DOWNLOAD_NO_PROGRESS 1 LOG_CONFIGURE 1 LOG_BUILD 1 LOG_INSTALL 1 ) ``` 8. 為了確保子項目在超級構建的其余部分中是可見的，我們設置了`message_DIR`目錄: ```cmake if(WIN32 AND NOT CYGWIN) set(DEF_message_DIR ${STAGED_INSTALL_PREFIX}/CMake) else() set(DEF_message_DIR ${STAGED_INSTALL_PREFIX}/share/cmake/message) endif() file(TO_NATIVE_PATH "${DEF_message_DIR}" DEF_message_DIR) set(message_DIR ${DEF_message_DIR} CACHE PATH "Path to internally built messageConfig.cmake" FORCE) ``` 最后，來看一下`src`目錄上的`CMakeLists.txt`： 1. 同樣，聲明一個C++11項目: ```cmake cmake_minimum_required(VERSION 3.6 FATAL_ERROR) project(recipe-05_core LANGUAGES CXX ) set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_EXTENSIONS OFF) set(CMAKE_CXX_STANDARD_REQUIRED ON) ``` 2. 項目需要消息庫: ```cmake find_package(message 1 CONFIG REQUIRED) get_property(_loc TARGET message::message-shared PROPERTY LOCATION) message(STATUS "Found message: ${_loc} (found version ${message_VERSION})") ``` 3. 聲明一個可執行目標，并將其鏈接到消息動態庫: ```cmake add_executable(use_message use_message.cpp) target_link_libraries(use_message PUBLIC message::message-shared ) ``` ## 工作原理示例展示了`ExternalProject_Add`的一些新選項: 1. **GIT_REPOSITORY**:這可以用來指定包含依賴項源的存儲庫的URL。CMake還可以使用其他版本控制系統，比如CVS (CVS_REPOSITORY)、SVN (SVN_REPOSITORY)或Mercurial (HG_REPOSITORY)。 2. **GIT_TAG**:默認情況下，CMake將檢出給定存儲庫的默認分支。然而，最好依賴于一個穩定的版本。這可以通過這個選項指定，它可以接受Git將任何標識符識別為“版本”信息，例如：Git提交SHA、Git標記或分支名稱。CMake所理解的其他版本控制系統也可以使用類似的選項。 3. **TEST_AFTER_INSTALL**:依賴項很可能有自己的測試套件，您可能希望運行測試套件，以確保在超級構建期間一切順利。此選項將在安裝步驟之后立即運行測試。 `ExternalProject_Add`可以理解的其他測試選項如下: * **TEST_BEFORE_INSTALL**:將在安裝步驟之前運行測試套件 * **TEST_EXCLUDE_FROM_MAIN**:可以從測試套件中，刪除對外部項目的主要目標的依賴這些選項都假定外部項目使用CTest管理測試。如果外部項目不使用CTest來管理測試，我們可以通過`TEST_COMMAND`選項來執行測試。即使是為屬于自己項目的模塊引入超級構建模式，也需要引入額外的層，重新聲明小型CMake項目，并通過`ExternalProject_Add`顯式地傳遞配置設置。引入這個附加層的好處是，清晰地分離了變量和目標范圍，這可以幫助管理由多個組件組成的項目中的復雜性、依賴性和名稱空間，這些組件可以是內部的，也可以是外部的，并由CMake組合在一起。