Question

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 ​