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

  1. #include <cstdlib>
  2. #include <iostream>
  3. #include <string>
  4. std::string say_hello() { return std::string("Hello, CMake superbuild world!"); }
  5. int main()
  6. {
  7. std::cout << say_hello() << std::endl;
  8. return EXIT_SUCCESS;
  9. }

项目结构如下:

  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)
    2. project(recipe-01 LANGUAGES CXX)
    3. set(CMAKE_CXX_STANDARD 11)
    4. set(CMAKE_CXX_EXTENSIONS OFF)
    5. 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选项为外部项目设置源目录:

    1. SOURCE_DIR
    2. ${CMAKE_CURRENT_LIST_DIR}/src
  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. 我们还设置了C++编译器标志。这些通过使用CMAKE_CACHE_ARGS选项传递到ExternalProject_Add中:

    1. CMAKE_CACHE_ARGS
    2. -DCMAKE_CXX_FLAGS:STRING=${CMAKE_CXX_FLAGS}
  8. 我们配置外部项目,使它进行构建:

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

    1. INSTALL_COMMAND
    2. ""
    3. )

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

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

    1. cmake_minimum_required(VERSION 3.5 FATAL_ERROR)
  2. 声明一个C++项目:

    1. project(recipe-01_core LANGUAGES CXX)
  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
  15. ├── recipe-01_core-configure
  16. ├── recipe-01_core-done
  17. ├── recipe-01_core-download
  18. ├── recipe-01_core-install
  19. ├── recipe-01_core-mkdir
  20. ├── recipe-01_core-patch
  21. └── recipe-01_core-update
  22. └── tmp
  23. └── recipe-01_core
  24. ├── recipe-01_core-cache-.cmake
  25. ├── recipe-01_core-cfgcmd.txt
  26. └── 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_coreStamp/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将按照以下布局为各个子项目设置所有目录:

    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:外部项目的代码可能需要从在线存储库或资源处下载。

  • UpdatePatch:可用于定义如何更新外部项目的源代码或如何应用补丁。

  • Configure:默认情况下,CMake会假定外部项目是使用CMake配置的。如下面的示例所示,我们并不局限于这种情况。如果外部项目是CMake项目,ExternalProject_Add将调用CMake可执行文件,并传递选项。对于当前的示例,我们通过CMAKE_ARGSCMAKE_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的参数可以通过以下方法实现:

  1. ExternalProject_Get_Property(${PROJECT_NAME}_core CMAKE_ARGS)
  2. 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