8.1 使用超级构建模式

    本示例通过一个简单示例，介绍超级构建模式。我们将展示如何使用命令来构建一个的“Hello, World”程序。

    本示例将从以下源代码(Hello-World.cpp)构建“Hello, World”可执行文件:

    项目结构如下:

    1. .
    2. ├── CMakeLists.txt
    3. └── src
    4.       ├── CMakeLists.txt
    5.       └── hello-world.cpp

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

    1. 声明一个C++11项目，以及CMake最低版本:

      1. cmake_minimum_required(VERSION 3.5 FATAL_ERROR)
      3. project(recipe-01 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. 包括ExternalProject.cmake标准模块。该模块提供了ExternalProject_Add函数:

      1. include(ExternalProject)

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

      1. ExternalProject_Add(${PROJECT_NAME}_core

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

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

      1. CMAKE_ARGS
      2.   -DCMAKE_CXX_COMPILER=${CMAKE_CXX_COMPILER}
      3.   -DCMAKE_CXX_STANDARD=${CMAKE_CXX_STANDARD}
      4.   -DCMAKE_CXX_EXTENSIONS=${CMAKE_CXX_EXTENSIONS}
      5.   -DCMAKE_CXX_STANDARD_REQUIRED=${CMAKE_CXX_STANDARD_REQUIRED}

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

      1. BUILD_ALWAYS
      2.     1

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

      1. INSTALL_COMMAND
      2.     ""
      3. )

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

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

      1. cmake_minimum_required(VERSION 3.5 FATAL_ERROR)

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

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

      1. add_executable(hello-world hello-world.cpp)

    配置构建项目：

    1. $ mkdir -p build
    2. $ cmake ..
    3. $ cmake --build .

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

    1. build/subprojects/
    2. ├── Build
    3. │    └── recipe-01_core
    4. │        ├── CMakeCache.txt
    5. │        ├── CMakeFiles
    6. │        ├── cmake_install.cmake
    7. │        ├── hello-world
    8. │        └── Makefile
    9. ├── Download
    10. │    └── recipe-01_core
    11. ├── Install
    12. │    └── recipe-01_core
    13. ├── Stamp
    14. │        ├── recipe-01_core-configure
    15. │        ├── recipe-01_core-done
    16. │        ├── recipe-01_core-download
    17. │        ├── recipe-01_core-install
    18. │        ├── recipe-01_core-mkdir
    19. │        ├── recipe-01_core-patch
    20. │        └── recipe-01_core-update
    21. └── tmp
    22.     └── recipe-01_core
    23.         ├── recipe-01_core-cache-.cmake
    24.         ├── recipe-01_core-cfgcmd.txt
    25.         └── recipe-01_core-cfgcmd.txt.in

    recipe-01_core已经构建到build/subprojects子目录中，称为Build/recipe-01_core(这是我们设置的)。

    hello-world可执行文件在Build/recipe-01_core下创建，其他子文件夹tmp/recipe-01_core和Stamp/recipe-01_core包含临时文件，比如：CMake缓存脚本recipe-01_core-cache-.cmake和已执行的外部构建项目的各步骤的时间戳文件。

    ExternalProject_Add有许多选项，可用于外部项目的配置和编译等所有方面。这些选择可以分为以下几类:

    • Directory：它们用于调优源码的结构，并为外部项目构建目录。本例中，我们使用SOURCE_DIR选项让CMake知道源文件在${CMAKE_CURRENT_LIST_DIR}/src文件夹中。用于构建项目和存储临时文件的目录，也可以在此类选项或目录属性中指定。通过设置EP_BASE目录属性，CMake将按照以下布局为各个子项目设置所有目录:

      1. TMP_DIR = <EP_BASE>/tmp/<name>
      2. STAMP_DIR = <EP_BASE>/Stamp/<name>
      3. DOWNLOAD_DIR = <EP_BASE>/Download/<name>
      4. SOURCE_DIR = <EP_BASE>/Source/<name>
      5. BINARY_DIR = <EP_BASE>/Build/<name>
      6. 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。然后，配置如以下所示:

      1. $ cmake -DCMAKE_CXX_COMPILER=g++ -DCMAKE_CXX_STANDARD=11
      2. -DCMAKE_CXX_EXTENSIONS=OFF -DCMAKE_CXX_STANDARD_REQUIRED=ON
      3. -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的参数可以通过以下方法实现:

    NOTE:ExternalProject_Add的完整选项列表可以在CMake文档中找到:https://cmake.org/cmake/help/v3.5/module/ExternalProject.html#command:ExternalProject_Add

    1. ExternalProject_Add_Step: 当添加了外部项目，此命令允许将附加的命令作为自定义步骤锁定在其上。参见:
    2. ExternalProject_Add_StepTargets:允许将外部项目中的步骤(例如：构建和测试步骤)定义为单独的目标。这意味着可以从完整的外部项目中单独触发这些步骤，并允许对项目中的复杂依赖项，进行细粒度控制。参见:https://cmake.org/cmake/help/v3.5/module/ExternalProject.htm#command:externalproject_add_steptargets