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”可执行文件:

#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;
}

项目结构如下:

.
├── CMakeLists.txt
└── src
      ├── CMakeLists.txt
      └── hello-world.cpp

具体实施

让我们看一下根目录下的CMakeLists.txt：

1. 声明一个C++11项目，以及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目录属性:

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

3. 包括ExternalProject.cmake标准模块。该模块提供了ExternalProject_Add函数:

   include(ExternalProject)

4. “Hello, World”源代码通过调用ExternalProject_Add函数作为外部项目添加的。外部项目的名称为recipe-01_core:

   ExternalProject_Add(${PROJECT_NAME}_core

5. 使用SOURCE_DIR选项为外部项目设置源目录:

   SOURCE_DIR
   ${CMAKE_CURRENT_LIST_DIR}/src

6. src子目录包含一个完整的CMake项目。为了配置和构建它，通过CMAKE_ARGS选项将适当的CMake选项传递给外部项目。例子中，只需要通过C++编译器和C++标准的要求即可:

   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_CACHE_ARGS
       -DCMAKE_CXX_FLAGS:STRING=${CMAKE_CXX_FLAGS}

8. 我们配置外部项目，使它进行构建:

   BUILD_ALWAYS
       1

9. 安装步骤不会执行任何操作(我们将在第4节中重新讨论安装，在第10章中安装超级构建，并编写安装程序):

   INSTALL_COMMAND
       ""
   )

现在，我们来看看src/CMakeLists.txt。由于我们将“Hello, World”源文件作为一个外部项目添加，这是一个独立项目的CMakeLists.txt文件:

1. 这里声明CMake版本最低要求:

   cmake_minimum_required(VERSION 3.5 FATAL_ERROR)

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

   project(recipe-01_core LANGUAGES CXX)

3. 最终，使用hello-world.cpp源码文件生成可执行目标hello-world：

   add_executable(hello-world hello-world.cpp)

配置构建项目：

$ mkdir -p build
$ cmake ..
$ cmake --build .

构建目录的结构稍微复杂一些，subprojects文件夹的内容如下:

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将按照以下布局为各个子项目设置所有目录:

  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。然后，配置如以下所示:

  $ 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的参数可以通过以下方法实现:

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