8.2 使用超級構建管理依賴項:Ⅰ.Boost庫 · cmake-cookbook

# 8.2 使用超級構建管理依賴項:Ⅰ.Boost庫 **NOTE**:*此示例代碼可以在 https://github.com/dev-cafe/cmake-cookbook/tree/v1.0/chapter-8/recipe-02 中找到，其中有一個C++示例。該示例在CMake 3.5版(或更高版本)中是有效的，并且已經在GNU/Linux、macOS和Windows上進行過測試。* Boost庫提供了豐富的C++基礎工具，在C++開發人員中很受歡迎。第3章中，已經展示了如何在系統上找到Boost庫。然而，有時系統上可能沒有項目所需的Boost版本。這個示例將展示如何利用超級構建模式來交付代碼，并確保在缺少依賴項時，不會讓CMake停止配置。我們將重用在第3章第8節的示例代碼，以超構建的形式重新組織。這是項目的文件結構: ```shell . ├── CMakeLists.txt ├── external │ └── upstream │ ├── boost │ │ └── CMakeLists.txt │ └── CMakeLists.txt └── src ├── CMakeLists.txt └── path-info.cpp ``` 注意到項目源代碼樹中有四個`CMakeLists.txt`文件。下面的部分將對這些文件進行詳解。 ## 具體實施從根目錄的`CMakeLists.txt`開始： 1. 聲明一個C++11項目： ```cmake cmake_minimum_required(VERSION 3.5 FATAL_ERROR) project(recipe-02 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. 我們設置了`STAGED_INSTALL_PREFIX`變量。此目錄將用于安裝構建樹中的依賴項: ```cmake set(STAGED_INSTALL_PREFIX ${CMAKE_BINARY_DIR}/stage) message(STATUS "${PROJECT_NAME} staged install: ${STAGED_INSTALL_PREFIX}") ``` 4. 項目需要Boost庫的文件系統和系統組件。我們聲明了一個列表變量來保存這個信息，并設置了Boost所需的最低版本: ```cmake list(APPEND BOOST_COMPONENTS_REQUIRED filesystem system) set(Boost_MINIMUM_REQUIRED 1.61) ``` 5. 添加`external/upstream`子目錄，它將依次添加` external/upstream/boost `子目錄: ```cmake add_subdirectory(external/upstream) ``` 6. 然后，包括` ExternalProject.cmake`標準模塊，其中定義了`ExternalProject_Add`命令，它是超級構建的關鍵: ```cmake include(ExternalProject) ``` 7. 項目位于`src`子目錄下，我們將它添加為一個外部項目。使用`CMAKE_ARGS`和`CMAKE_CACHE_ARGS`傳遞CMake選項: ```cmake ExternalProject_Add(${PROJECT_NAME}_core DEPENDS boost_external SOURCE_DIR ${CMAKE_CURRENT_LIST_DIR}/src 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} CMAKE_CACHE_ARGS -DCMAKE_CXX_FLAGS:STRING=${CMAKE_CXX_FLAGS} -DCMAKE_INCLUDE_PATH:PATH=${BOOST_INCLUDEDIR} -DCMAKE_LIBRARY_PATH:PATH=${BOOST_LIBRARYDIR} BUILD_ALWAYS 1 INSTALL_COMMAND "" ) ``` 現在讓我們看看`external/upstream`中的`CMakeLists.txt`。這個文件只是添加了boost文件夾作為一個額外的目錄: ```cmake add_subdirectory(boost) ``` ` external/upstream/boost `中的`CMakeLists.txt`描述了滿足對Boost的依賴所需的操作。我們的目標很簡單，如果沒有安裝所需的版本，下載源打包文件并構建它: 1. 首先，我們試圖找到所需Boost組件的最低版本: ```cmake find_package(Boost ${Boost_MINIMUM_REQUIRED} QUIET COMPONENTS "${BOOST_COMPONENTS_REQUIRED}") ``` 2. 如果找到這些，則添加一個接口庫目標`boost_external`。這是一個虛擬目標，需要在我們的超級構建中正確處理構建順序: ```cmake if(Boost_FOUND) message(STATUS "Found Boost version ${Boost_MAJOR_VERSION}.${Boost_MINOR_VERSION}.${Boost_SUBMINOR_VERSION}") add_library(boost_external INTERFACE) else() # ... discussed below endif() ``` 3. 如果`find_package`沒有成功，或者正在強制進行超級構建，我們需要建立一個本地構建的Boost。為此，我們進入`else`部分: ```cmake else() message(STATUS "Boost ${Boost_MINIMUM_REQUIRED} could not be located, Building Boost 1.61.0 instead.") ``` 4. 由于這些庫不使用CMake，我們需要為它們的原生構建工具鏈準備參數。首先為Boost設置編譯器: ```cmake if(CMAKE_CXX_COMPILER_ID MATCHES "GNU") if(APPLE) set(_toolset "darwin") else() set(_toolset "gcc") endif() elseif(CMAKE_CXX_COMPILER_ID MATCHES ".*Clang") set(_toolset "clang") elseif(CMAKE_CXX_COMPILER_ID MATCHES "Intel") if(APPLE) set(_toolset "intel-darwin") else() set(_toolset "intel-linux") endif() endif() ``` 5. 我們準備了基于所需組件構建的庫列表，定義了一些列表變量:`_build_byproducts`，包含要構建的庫的絕對路徑;`_b2_select_libraries`，包含要構建的庫的列；和`_bootstrap_select_libraries`，這是一個字符串，與`_b2_needed_components`具有相同的內容，但格式不同: ```cmake if(NOT "${BOOST_COMPONENTS_REQUIRED}" STREQUAL "") # Replace unit_test_framework (used by CMake's find_package) with test (understood by Boost build toolchain) string(REPLACE "unit_test_framework" "test" _b2_needed_components "${BOOST_COMPONENTS_REQUIRED}") # Generate argument for BUILD_BYPRODUCTS set(_build_byproducts) set(_b2_select_libraries) foreach(_lib IN LISTS _b2_needed_components) list(APPEND _build_byproducts ${STAGED_INSTALL_PREFIX}/boost/lib/libboost_${_lib}${CMAKE_SHARED_LIBRARY_SUFFIX}) list(APPEND _b2_select_libraries --with-${_lib}) endforeach() # Transform the ;-separated list to a ,-separated list (digested by the Boost build toolchain!) string(REPLACE ";" "," _b2_needed_components "${_b2_needed_components}") set(_bootstrap_select_libraries "--with-libraries=${_b2_needed_components}") string(REPLACE ";" ", " printout "${BOOST_COMPONENTS_REQUIRED}") message(STATUS " Libraries to be built: ${printout}") endif() ``` 6. 現在，可以將Boost添加為外部項目。首先，在下載選項類中指定下載URL和checksum。`DOWNLOAD_NO_PROGRESS`設置為1，以禁止打印下載進度信息: ```cmake include(ExternalProject) ExternalProject_Add(boost_external URL https://sourceforge.net/projects/boost/files/boost/1.61.0/boost_1_61_0.zip URL_HASH SHA256=02d420e6908016d4ac74dfc712eec7d9616a7fc0da78b0a1b5b937536b2e01e8 DOWNLOAD_NO_PROGRESS 1 ``` 7. 接下來，設置更新/補丁和配置選項: ```cmake UPDATE_COMMAND "" CONFIGURE_COMMAND <SOURCE_DIR>/bootstrap.sh --with-toolset=${_toolset} --prefix=${STAGED_INSTALL_PREFIX}/boost ${_bootstrap_select_libraries} ``` 8. 構建選項使用`BUILD_COMMAND`設置。`BUILD_IN_SOURCE`設置為1時，表示構建將在源目錄中發生。這里，將`LOG_BUILD`設置為1，以便將生成腳本中的輸出記錄到文件中: ```cmake BUILD_COMMAND <SOURCE_DIR>/b2 -q link=shared threading=multi variant=release toolset=${_toolset} ${_b2_select_libraries} LOG_BUILD 1 BUILD_IN_SOURCE 1 ``` 9. 安裝選項是使用`INSTALL_COMMAND`指令設置的。注意使用`LOG_INSTALL`選項，還可以將安裝步驟記錄到文件中: ```cmake INSTALL_COMMAND <SOURCE_DIR>/b2 -q install link=shared threading=multi variant=release toolset=${_toolset} ${_b2_select_libraries} LOG_INSTALL 1 ``` 10. 最后，庫列表為`BUILD_BYPRODUCTS`并關閉 `ExternalProject_Add`命令: ```cmake BUILD_BYPRODUCTS "${_build_byproducts}" ) ``` 11. 我們設置了一些變量來指導檢測新安裝的Boost: ```cmake set( BOOST_ROOT ${STAGED_INSTALL_PREFIX}/boost CACHE PATH "Path to internally built Boost installation root" FORCE ) set( BOOST_INCLUDEDIR ${BOOST_ROOT}/include CACHE PATH "Path to internally built Boost include directories" FORCE ) set( BOOST_LIBRARYDIR ${BOOST_ROOT}/lib CACHE PATH "Path to internally built Boost library directories" FORCE ) ``` 12. `else`分支中，執行的最后一個操作是取消所有內部變量的設置: ```cmake unset(_toolset) unset(_b2_needed_components) unset(_build_byproducts) unset(_b2_select_libraries) unset(_boostrap_select_libraries) ``` 最后，讓我們看看`src/CMakeLists.txt`。這個文件描述了一個獨立的項目: 1. 聲明一個C++項目： ```cmake cmake_minimum_required(VERSION 3.5 FATAL_ERROR) project(recipe-02_core LANGUAGES CXX) ``` 2. 調用`find_package`尋找項目依賴的Boost。從主`CMakeLists.txt`中配置的項目，可以保證始終滿足依賴關系，方法是使用預先安裝在系統上的Boost，或者使用我們作為子項目構建的Boost: ```cmake find_package(Boost 1.61 REQUIRED COMPONENTS filesystem) ``` 3. 添加可執行目標，并鏈接庫: ```cmake add_executable(path-info path-info.cpp) target_link_libraries(path-info PUBLIC Boost::filesystem ) ``` **NOTE**:*導入目標雖然很簡單，但不能保證對任意Boost和CMake版本組合都有效。這是因為CMake的`FindBoost.cmake`模塊會創建手工導入的目標。因此，當CMake有未知版本發布時，可能會有`Boost_LIBRARIES`和`Boost_INCLUDE_DIRS`，沒有導入情況(https://stackoverflow.com/questions/42123509/cmake-finds-boost-but-the-imported-targets-not-available-for-boost-version )。* ## 工作原理此示例展示了如何利用超級構建模式，來整合項目的依賴項。讓我們再看一下項目的文件結構: ```shell . ├── CMakeLists.txt ├── external │ └── upstream │ ├── boost │ │ └── CMakeLists.txt │ └── CMakeLists.txt └── src ├── CMakeLists.txt └── path-info.cpp ``` 我們在項目源代碼樹中，引入了4個`CMakeLists.txt`文件: 1. 主`CMakeLists.txt`將配合超級構建。 2. ` external/upstream`中的文件將引導我們到`boost`子目錄。 3. `external/upstream/boost/CMakeLists.txt `將處理Boost的依賴。 4. 最后，`src`下的`CMakeLists.txt`將構建我們的示例代碼(其依賴于Boost)。從` external/upstream/boost/CMakeLists.txt `文件開始討論。Boost使用它自己的構建系統，因此需要在`ExternalProject_Add`中詳細配置，以便正確設置所有內容: 1. 保留目錄選項的默認值。 2. 下載步驟將從在線服務器下載所需版本的Boost。因此，我們設置了`URL`和`URL_HASH`。`URL_HASH`用于檢查下載文件的完整性。由于我們不希望看到下載的進度報告，所以將`DOWNLOAD_NO_PROGRESS`選項設置為true。 3. 更新步驟留空。如果需要重新構建，我們不想再次下載Boost。 4. 配置步驟將使用由Boost在`CONFIGURE_COMMAND`中提供的配置工具完成。由于我們希望超級構建是跨平臺的，所以我們使用` <SOURCE_DIR>`變量來引用未打包源的位置: ```cmake CONFIGURE_COMMAND <SOURCE_DIR>/bootstrap.sh --with-toolset=${_toolset} --prefix=${STAGED_INSTALL_PREFIX}/boost ${_bootstrap_select_libraries} ``` 5. 將`BUILD_IN_SOURCE`選項設置為true，說明這是一個內置的構建。`BUILD_COMMAND`使用Boost本機構建工具`b2`。由于我們將在源代碼中構建，所以我們再次使用` <SOURCE_DIR>`變量來引用未打包源代碼的位置。 6. 然后，來看安裝選項。Boost使用本地構建工具管理安裝。事實上，構建和安裝命令可以整合為一個命令。 7. 輸出日志選項`LOG_BUILD`和`LOG_INSTALL` 直接用于為`ExternalProject_Add`構建和安裝操作編寫日志文件，而不是輸出到屏幕上。 8. 最后，`BUILD_BYPRODUCTS`選項允許`ExternalProject_Add`在后續構建中，跟蹤新構建的Boost庫。構建Boost之后，構建目錄中的`${STAGED_INSTALL_PREFIX}/Boost`文件夾將包含所需的庫。我們需要將此信息傳遞給我們的項目，該構建系統是在`src/CMakeLists.txt`中生成的。為了實現這個目標，我們在主`CMakeLists.txt`的`ExternalProject_Add`中傳遞兩個額外的`CMAKE_CACHE_ARGS`: 1. CMAKE_INCLUDE_PATH: CMake查找C/C++頭文件的路徑 2. CMAKE_LIBRARY_PATH: CMake將查找庫的路徑將這些變量設置成新構建的Boost安裝路徑，可以確保正確地獲取依賴項。 **TIPS**:*在配置項目時將`CMAKE_DISABLE_FIND_PACKAGE_Boost`設置為`ON`，將跳過對Boost庫的檢測，并始終執行超級構建。參考文檔:https://cmake.org/cmake/help/v3.5/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.html 。*