Question

NOTE : 此示例代码可以在 https://github.com/dev-cafe/cmake-cookbook/tree/v1.0/chapter-8/recipe-03 中找到，其中有一个 C 示例。该示例在 CMake 3.5 版（或更高版本) 中是有效的，并且已经在 GNU/Linux、macOS 和 Windows 上进行过测试。

对于 CMake 支持的所有项目，超级构建模式可用于管理相当复杂的依赖关系。正如在前面的示例所演示的，CMake 并不需要管理各种子项目。与前一个示例相反，这个示例中的外部子项目将是一个 CMake 项目，并将展示如何使用超级构建，下载、构建和安装 FFTW 库。FFTW 是一个快速傅里叶变换库，可在 http://www.fftw.org 免费获得。

我们项目的代码 fftw_example.c 位于 src 子目录中，它将计算源代码中定义的函数的傅里叶变换。

准备工作

这个示例的目录布局，是超级构建中非常常见的结构:

.
├── CMakeLists.txt
├── external
│    └── upstream
│        ├── CMakeLists.txt
│        └── fftw3
│            └── CMakeLists.txt
└── src
    ├── CMakeLists.txt
    └── fftw_example.c

代码 fftw_example.c 位于 src 子目录中，它将调用傅里叶变换函数。

具体实施

从主 CMakeLists.txt 开始，这里将整个超级构建过程放在一起:

1. 声明一个支持 C99 的项目：

   cmake_minimum_required(VERSION 3.5 FATAL_ERROR)
   project(recipe-03 LANGUAGES C)
   set(CMAKE_C_STANDARD 99)
   set(CMAKE_C_EXTENSIONS OFF)
   set(CMAKE_C_STANDARD_REQUIRED ON)

2. 和上一个示例一样，我们设置了 EP_BASE 目录属性和阶段安装目录:

   set_property(DIRECTORY PROPERTY EP_BASE ${CMAKE_BINARY_DIR}/subprojects)
   set(STAGED_INSTALL_PREFIX ${CMAKE_BINARY_DIR}/stage)
   message(STATUS "${PROJECT_NAME} staged install: ${STAGED_INSTALL_PREFIX}")

3. 对 FFTW 的依赖关系在 external/upstream 子目录中检查，我们会将这个子目录添加到构建系统中:

   add_subdirectory(external/upstream)

4. 包含 ExternalProject.cmake 模块：

   include(ExternalProject)

5. 我们为 recipe-03_core 声明了外部项目。这个项目的源代码在 ${CMAKE_CURRENT_LIST_DIR}/src 文件夹中。该项目设置为 FFTW3_DIR 选项，选择正确的 FFTW 库:

   ExternalProject_Add(${PROJECT_NAME}_core
     DEPENDS
         fftw3_external
     SOURCE_DIR
         ${CMAKE_CURRENT_LIST_DIR}/src
     CMAKE_ARGS
       -DFFTW3_DIR=${FFTW3_DIR}
       -DCMAKE_C_STANDARD=${CMAKE_C_STANDARD}
       -DCMAKE_C_EXTENSIONS=${CMAKE_C_EXTENSIONS}
       -DCMAKE_C_STANDARD_REQUIRED=${CMAKE_C_STANDARD_REQUIRED}
     CMAKE_CACHE_ARGS
       -DCMAKE_C_FLAGS:STRING=${CMAKE_C_FLAGS}
       -DCMAKE_PREFIX_PATH:PATH=${CMAKE_PREFIX_PATH}
     BUILD_ALWAYS
         1
     INSTALL_COMMAND
         ""
     )

external/upstream 子目录还包含一个 CMakeLists.txt :

这个文件中，添加 fftw3 文件夹作为构建系统中的另一个子目录:

add_subdirectory(fftw3)

external/upstream/fftw3 中的 CMakeLists.txt 负责处理依赖关系:

1. 首先，尝试在系统上找到 FFTW3 库。注意，我们配置 find_package 使用的参数:

   find_package(FFTW3 CONFIG QUIET)

2. 如果找到了库，就可以导入目标 FFTW3::FFTW3 来链接它。我们向用户打印一条消息，显示库的位置。我们添加一个虚拟 INTERFACE 库 fftw3_external 。超级建设中，这需要正确地固定子项目之间的依赖树:

   find_package(FFTW3 CONFIG QUIET)
   ​
   if(FFTW3_FOUND)
     get_property(_loc TARGET FFTW3::fftw3 PROPERTY LOCATION)
     message(STATUS "Found FFTW3: ${_loc} (found version ${FFTW3_VERSION})")
       add_library(fftw3_external INTERFACE) # dummy
   else()
       # this branch will be discussed below
   endif()

3. 如果 CMake 无法找到预安装版本的 FFTW，我们将进入 else 分支。这个分支中，使用 ExternalProject_Add 下载、构建和安装它。外部项目的名称为 fftw3_external 。 fftw3_external 项目将从官方地址下载，下载完成后将使用 MD5 校验和进行文件完整性检查:

   message(STATUS "Suitable FFTW3 could not be located. Downloading and building!")
   ​
   include(ExternalProject)
   ExternalProject_Add(fftw3_external
     URL
         http://www.fftw.org/fftw-3.3.8.tar.gz
     URL_HASH
         MD5=8aac833c943d8e90d51b697b27d4384d

4. 禁用打印下载进程，并将更新命令定义为空:

     OWNLOAD_NO_PROGRESS
         1
     UPDATE_COMMAND
         ""

5. 配置、构建和安装输出将被记录到一个文件中:

     LOG_CONFIGURE
         1
     LOG_BUILD
         1
     LOG_INSTALL
         1

6. 将 fftw3_external 项目的安装前缀设置为之前定义的 STAGED_INSTALL_PREFIX 目录，并关闭 FFTW3 的测试套件构建:

     CMAKE_ARGS
       -DCMAKE_INSTALL_PREFIX=${STAGED_INSTALL_PREFIX}
       -DBUILD_TESTS=OFF

7. 如果在 Windows 上构建，通过生成器表达式设置 WITH_OUR_MALLOC 预处理器选项，并关闭 ExternalProject_Add 命令:

     CMAKE_CACHE_ARGS
         -DCMAKE_C_FLAGS:STRING=$<$<BOOL:WIN32>:-DWITH_OUR_MALLOC>
     )

8. 最后，定义 FFTW3_DIR 变量并缓存它。CMake 将使用该变量作为 FFTW3::FFTW3 目标的搜索目录:

   include(GNUInstallDirs)
   ​
   set(
     FFTW3_DIR ${STAGED_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR}/cmake/fftw3
     CACHE PATH "Path to internally built FFTW3Config.cmake"
     FORCE
     )

src 文件夹中的 CMakeLists.txt 相当简洁:

1. 同样在这个文件中，我们声明了一个 C 项目:

   cmake_minimum_required(VERSION 3.5 FATAL_ERROR)
   project(recipe-03_core LANGUAGES C)

2. 使用 find_package 来检测 FFTW 库，再次使用配置检测模式:

   find_package(FFTW3 CONFIG REQUIRED)
   get_property(_loc TARGET FFTW3::fftw3 PROPERTY LOCATION)
   message(STATUS "Found FFTW3: ${_loc} (found version ${FFTW3_VERSION})")

3. 将 fftw_example.c 源文件添加到可执行目标 fftw_example :

   add_executable(fftw_example fftw_example.c)

4. 为可执行目标设置链接库:

   target_link_libraries(fftw_example
     PRIVATE
         FFTW3::fftw3
     )

工作原理

本示例演示了如何下载、构建和安装由 CMake 管理其构建系统的外部项目。与前一个示例（必须使用自定义构建系统) 相反，这个超级构建设置相当简洁。需要注意的是，使用 find_package 命令了配置选项；这说明 CMake 首先查找 FFTW3Config.cmake ，以定位 FFTW3 库，将库导出为第三方项目获取的目标。目标包含库的版本、配置和位置，即关于如何配置和构建目标的完整信息。如果系统上没有安装库，我们需要声明 FFTW3Config.cmake 文件的位置。这可以通过设置 FFTW3_DIR 变量来实现。这是 external/upstream/fftw3/CMakeLists.txt 文件中的最后一步。使用 GNUInstallDirs.cmake 模块，我们将 FFTW3_DIR 设置为缓存变量，以便稍后在超级构建中使用。

TIPS : 配置项目时将 CMAKE_DISABLE_FIND_PACKAGE_FFTW3 设置为 ON ，将跳过对 FFTW 库的检测，并始终执行超级构建。参考: https://cmake.org/cmake/help/v3.5/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.html ​