# 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