8.3 使用超级构建管理依赖项:Ⅱ.FFTW库

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子目录中，它将计算源代码中定义的函数的傅里叶变换。

准备工作

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

  1. .
  2. ├── CMakeLists.txt
  3. ├── external
  4. │    └── upstream
  5. │        ├── CMakeLists.txt
  6. │        └── fftw3
  7. │            └── CMakeLists.txt
  8. └── src
  9.     ├── CMakeLists.txt
  10.     └── fftw_example.c

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

具体实施

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

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

    1. cmake_minimum_required(VERSION 3.5 FATAL_ERROR)
    2. project(recipe-03 LANGUAGES C)
    3. set(CMAKE_C_STANDARD 99)
    4. set(CMAKE_C_EXTENSIONS OFF)
    5. set(CMAKE_C_STANDARD_REQUIRED ON)

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

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

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

    1. add_subdirectory(external/upstream)

  4. 包含ExternalProject.cmake模块：

    1. include(ExternalProject)

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

    1. ExternalProject_Add(${PROJECT_NAME}_core
    2.   DEPENDS
    3.       fftw3_external
    4.   SOURCE_DIR
    5.       ${CMAKE_CURRENT_LIST_DIR}/src
    6.   CMAKE_ARGS
    7.     -DFFTW3_DIR=${FFTW3_DIR}
    8.     -DCMAKE_C_STANDARD=${CMAKE_C_STANDARD}
    9.     -DCMAKE_C_EXTENSIONS=${CMAKE_C_EXTENSIONS}
    10.     -DCMAKE_C_STANDARD_REQUIRED=${CMAKE_C_STANDARD_REQUIRED}
    11.   CMAKE_CACHE_ARGS
    12.     -DCMAKE_C_FLAGS:STRING=${CMAKE_C_FLAGS}
    13.     -DCMAKE_PREFIX_PATH:PATH=${CMAKE_PREFIX_PATH}
    14.   BUILD_ALWAYS
    15.       1
    16.   INSTALL_COMMAND
    17.       ""
    18.   )

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

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

  1. add_subdirectory(fftw3)

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

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

    1. find_package(FFTW3 CONFIG QUIET)

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

    1. find_package(FFTW3 CONFIG QUIET)
    3. if(FFTW3_FOUND)
    4.   get_property(_loc TARGET FFTW3::fftw3 PROPERTY LOCATION)
    5.   message(STATUS "Found FFTW3: ${_loc} (found version ${FFTW3_VERSION})")
    6.     add_library(fftw3_external INTERFACE) # dummy
    7. else()
    8.     # this branch will be discussed below
    9. endif()

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

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

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

    1.   OWNLOAD_NO_PROGRESS
    2.       1
    3.   UPDATE_COMMAND
    4.       ""

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

    1.   LOG_CONFIGURE
    2.       1
    3.   LOG_BUILD
    4.       1
    5.   LOG_INSTALL
    6.       1

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

    1.   CMAKE_ARGS
    2.     -DCMAKE_INSTALL_PREFIX=${STAGED_INSTALL_PREFIX}
    3.     -DBUILD_TESTS=OFF

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

    1.   CMAKE_CACHE_ARGS
    2.       -DCMAKE_C_FLAGS:STRING=$<$<BOOL:WIN32>:-DWITH_OUR_MALLOC>
    3.   )

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

    1. include(GNUInstallDirs)
    3. set(
    4.   FFTW3_DIR ${STAGED_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR}/cmake/fftw3
    5.   CACHE PATH "Path to internally built FFTW3Config.cmake"
    6.   FORCE
    7.   )

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

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

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

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

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

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

    1. add_executable(fftw_example fftw_example.c)

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

    1. target_link_libraries(fftw_example
    2.   PRIVATE
    3.       FFTW3::fftw3
    4.   )

工作原理

本示例演示了如何下载、构建和安装由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