# 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 。*
- 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 留下评论——让其他读者知道你的想法