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节的示例代码，以超构建的形式重新组织。这是项目的文件结构:

  1. .
  2. ├── CMakeLists.txt
  3. ├── external
  4. │    └── upstream
  5. │        ├── boost
  6. │        │    └── CMakeLists.txt
  7. │        └── CMakeLists.txt
  8. └── src
  9.     ├── CMakeLists.txt
  10.     └── path-info.cpp

注意到项目源代码树中有四个CMakeLists.txt文件。下面的部分将对这些文件进行详解。

具体实施

从根目录的CMakeLists.txt开始：

  1. 声明一个C++11项目：

    1. cmake_minimum_required(VERSION 3.5 FATAL_ERROR)
    3. project(recipe-02 LANGUAGES CXX)
    5. set(CMAKE_CXX_STANDARD 11)
    6. set(CMAKE_CXX_EXTENSIONS OFF)
    7. set(CMAKE_CXX_STANDARD_REQUIRED ON)

  2. 对EP_BASE进行属性设置：

    1. set_property(DIRECTORY PROPERTY EP_BASE ${CMAKE_BINARY_DIR}/subprojects)

  3. 我们设置了STAGED_INSTALL_PREFIX变量。此目录将用于安装构建树中的依赖项:

    1. set(STAGED_INSTALL_PREFIX ${CMAKE_BINARY_DIR}/stage)
    2. message(STATUS "${PROJECT_NAME} staged install: ${STAGED_INSTALL_PREFIX}")

  4. 项目需要Boost库的文件系统和系统组件。我们声明了一个列表变量来保存这个信息，并设置了Boost所需的最低版本:

    1. list(APPEND BOOST_COMPONENTS_REQUIRED filesystem system)
    2. set(Boost_MINIMUM_REQUIRED 1.61)

  5. 添加external/upstream子目录，它将依次添加external/upstream/boost子目录:

    1. add_subdirectory(external/upstream)

  6. 然后，包括ExternalProject.cmake标准模块，其中定义了ExternalProject_Add命令，它是超级构建的关键:

    1. include(ExternalProject)

  7. 项目位于src子目录下，我们将它添加为一个外部项目。使用CMAKE_ARGS和CMAKE_CACHE_ARGS传递CMake选项:

    1. ExternalProject_Add(${PROJECT_NAME}_core
    2.   DEPENDS
    3.       boost_external
    4.   SOURCE_DIR
    5.       ${CMAKE_CURRENT_LIST_DIR}/src
    6.   CMAKE_ARGS
    7.     -DCMAKE_CXX_COMPILER=${CMAKE_CXX_COMPILER}
    8.     -DCMAKE_CXX_STANDARD=${CMAKE_CXX_STANDARD}
    9.     -DCMAKE_CXX_EXTENSIONS=${CMAKE_CXX_EXTENSIONS}
    10.     -DCMAKE_CXX_STANDARD_REQUIRED=${CMAKE_CXX_STANDARD_REQUIRED}
    11.   CMAKE_CACHE_ARGS
    12.     -DCMAKE_CXX_FLAGS:STRING=${CMAKE_CXX_FLAGS}
    13.     -DCMAKE_INCLUDE_PATH:PATH=${BOOST_INCLUDEDIR}
    14.     -DCMAKE_LIBRARY_PATH:PATH=${BOOST_LIBRARYDIR}
    15.   BUILD_ALWAYS
    16.       1
    17.   INSTALL_COMMAND
    18.       ""
    19.   )

现在让我们看看external/upstream中的CMakeLists.txt。这个文件只是添加了boost文件夹作为一个额外的目录:

  1. add_subdirectory(boost)

external/upstream/boost中的CMakeLists.txt描述了满足对Boost的依赖所需的操作。我们的目标很简单，如果没有安装所需的版本，下载源打包文件并构建它:

  1. 首先，我们试图找到所需Boost组件的最低版本:

    1. find_package(Boost ${Boost_MINIMUM_REQUIRED} QUIET COMPONENTS "${BOOST_COMPONENTS_REQUIRED}")

  2. 如果找到这些，则添加一个接口库目标boost_external。这是一个虚拟目标，需要在我们的超级构建中正确处理构建顺序:

    1. if(Boost_FOUND)
    2.     message(STATUS "Found Boost version ${Boost_MAJOR_VERSION}.${Boost_MINOR_VERSION}.${Boost_SUBMINOR_VERSION}")
    3.   add_library(boost_external INTERFACE)
    4. else()
    5.     # ... discussed below
    6. endif()

  3. 如果find_package没有成功，或者正在强制进行超级构建，我们需要建立一个本地构建的Boost。为此，我们进入else部分:

    1. else()
    2.     message(STATUS "Boost ${Boost_MINIMUM_REQUIRED} could not be located, Building Boost 1.61.0 instead.")

  4. 由于这些库不使用CMake，我们需要为它们的原生构建工具链准备参数。首先为Boost设置编译器:

    1. if(CMAKE_CXX_COMPILER_ID MATCHES "GNU")
    2.   if(APPLE)
    3.       set(_toolset "darwin")
    4.   else()
    5.       set(_toolset "gcc")
    6.   endif()
    7. elseif(CMAKE_CXX_COMPILER_ID MATCHES ".*Clang")
    8.   set(_toolset "clang")
    9. elseif(CMAKE_CXX_COMPILER_ID MATCHES "Intel")
    10.   if(APPLE)
    11.       set(_toolset "intel-darwin")
    12.   else()
    13.       set(_toolset "intel-linux")
    14.   endif()
    15. endif()

  5. 我们准备了基于所需组件构建的库列表，定义了一些列表变量:_build_byproducts，包含要构建的库的绝对路径;_b2_select_libraries，包含要构建的库的列；和_bootstrap_select_libraries，这是一个字符串，与_b2_needed_components具有相同的内容，但格式不同:

    1. if(NOT "${BOOST_COMPONENTS_REQUIRED}" STREQUAL "")
    2.   # Replace unit_test_framework (used by CMake's find_package) with test (understood by Boost build toolchain)
    3.   string(REPLACE "unit_test_framework" "test" _b2_needed_components "${BOOST_COMPONENTS_REQUIRED}")
    4.   # Generate argument for BUILD_BYPRODUCTS
    5.   set(_build_byproducts)
    6.   set(_b2_select_libraries)
    7.   foreach(_lib IN LISTS _b2_needed_components)
    8.       list(APPEND _build_byproducts ${STAGED_INSTALL_PREFIX}/boost/lib/libboost_${_lib}${CMAKE_SHARED_LIBRARY_SUFFIX})
    9.       list(APPEND _b2_select_libraries --with-${_lib})
    10.   endforeach()
    11.   # Transform the ;-separated list to a ,-separated list (digested by the Boost build toolchain!)
    12.   string(REPLACE ";" "," _b2_needed_components "${_b2_needed_components}")
    13.   set(_bootstrap_select_libraries "--with-libraries=${_b2_needed_components}")
    14.   string(REPLACE ";" ", " printout "${BOOST_COMPONENTS_REQUIRED}")
    15.   message(STATUS " Libraries to be built: ${printout}")
    16. endif()

  6. 现在，可以将Boost添加为外部项目。首先，在下载选项类中指定下载URL和checksum。DOWNLOAD_NO_PROGRESS设置为1，以禁止打印下载进度信息:

    1. include(ExternalProject)
    2. ExternalProject_Add(boost_external
    3.   URL
    4.       https://sourceforge.net/projects/boost/files/boost/1.61.0/boost_1_61_0.zip
    5.   URL_HASH
    6.       SHA256=02d420e6908016d4ac74dfc712eec7d9616a7fc0da78b0a1b5b937536b2e01e8
    7.   DOWNLOAD_NO_PROGRESS
    8.       1

  7. 接下来，设置更新/补丁和配置选项:

    1.   UPDATE_COMMAND
    2.       ""
    3.   CONFIGURE_COMMAND
    4.       <SOURCE_DIR>/bootstrap.sh
    5.           --with-toolset=${_toolset}
    6.           --prefix=${STAGED_INSTALL_PREFIX}/boost
    7.   ${_bootstrap_select_libraries}

  8. 构建选项使用BUILD_COMMAND设置。BUILD_IN_SOURCE设置为1时，表示构建将在源目录中发生。这里，将LOG_BUILD设置为1，以便将生成脚本中的输出记录到文件中:

    1.   BUILD_COMMAND
    2.     <SOURCE_DIR>/b2 -q
    3.       link=shared
    4.       threading=multi
    5.       variant=release
    6.       toolset=${_toolset}
    7.       ${_b2_select_libraries}
    8.   LOG_BUILD
    9.     1
    10.   BUILD_IN_SOURCE
    11.     1

  9. 安装选项是使用INSTALL_COMMAND指令设置的。注意使用LOG_INSTALL选项，还可以将安装步骤记录到文件中:

    1.   INSTALL_COMMAND
    2.     <SOURCE_DIR>/b2 -q install
    3.       link=shared
    4.       threading=multi
    5.       variant=release
    6.       toolset=${_toolset}
    7.       ${_b2_select_libraries}
    8.   LOG_INSTALL
    9.       1

  10. 最后，库列表为BUILD_BYPRODUCTS并关闭ExternalProject_Add命令:

    1.   BUILD_BYPRODUCTS
    2.     "${_build_byproducts}"
    3.   )

  11. 我们设置了一些变量来指导检测新安装的Boost:

    1. set(
    2.   BOOST_ROOT ${STAGED_INSTALL_PREFIX}/boost
    3.   CACHE PATH "Path to internally built Boost installation root"
    4.   FORCE
    5.   )
    6. set(
    7.   BOOST_INCLUDEDIR ${BOOST_ROOT}/include
    8.   CACHE PATH "Path to internally built Boost include directories"
    9.   FORCE
    10.   )
    11. set(
    12.   BOOST_LIBRARYDIR ${BOOST_ROOT}/lib
    13.   CACHE PATH "Path to internally built Boost library directories"
    14.   FORCE
    15.   )

  12. else分支中，执行的最后一个操作是取消所有内部变量的设置:

    1. unset(_toolset)
    2. unset(_b2_needed_components)
    3. unset(_build_byproducts)
    4. unset(_b2_select_libraries)
    5. unset(_boostrap_select_libraries)

最后，让我们看看src/CMakeLists.txt。这个文件描述了一个独立的项目:

  1. 声明一个C++项目：

    1. cmake_minimum_required(VERSION 3.5 FATAL_ERROR)
    2. project(recipe-02_core LANGUAGES CXX)

  2. 调用find_package寻找项目依赖的Boost。从主CMakeLists.txt中配置的项目，可以保证始终满足依赖关系，方法是使用预先安装在系统上的Boost，或者使用我们作为子项目构建的Boost:

    1. find_package(Boost 1.61 REQUIRED COMPONENTS filesystem)

  3. 添加可执行目标，并链接库:

    1. add_executable(path-info path-info.cpp)
    2. target_link_libraries(path-info
    3.   PUBLIC
    4.       Boost::filesystem
    5.   )

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 )。

工作原理

此示例展示了如何利用超级构建模式，来整合项目的依赖项。让我们再看一下项目的文件结构:

  1. .
  2. ├── CMakeLists.txt
  3. ├── external
  4. │    └── upstream
  5. │        ├── boost
  6. │        │    └── CMakeLists.txt
  7. │        └── CMakeLists.txt
  8. └── src
  9.     ├── CMakeLists.txt
  10.     └── 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>变量来引用未打包源的位置:

    1. CONFIGURE_COMMAND
    2. <SOURCE_DIR>/bootstrap.sh
    3. --with-toolset=${_toolset}
    4. --prefix=${STAGED_INSTALL_PREFIX}/boost
    5. ${_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 。