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

# 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子目录中，它将计算源代码中定义的函数的傅里叶变换。 ## 准备工作这个示例的目录布局，是超级构建中非常常见的结构: ```shell . ├── CMakeLists.txt ├── external │ └── upstream │ ├── CMakeLists.txt │ └── fftw3 │ └── CMakeLists.txt └── src ├── CMakeLists.txt └── fftw_example.c ``` 代码`fftw_example.c`位于`src`子目录中，它将调用傅里叶变换函数。 ## 具体实施从主`CMakeLists.txt`开始，这里将整个超级构建过程放在一起: 1. 声明一个支持C99的项目： ```cmake 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`目录属性和阶段安装目录: ```cmake 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 `子目录中检查，我们会将这个子目录添加到构建系统中: ```cmake add_subdirectory(external/upstream) ``` 4. 包含` ExternalProject.cmake`模块： ```cmake include(ExternalProject) ``` 5. 我们为`recipe-03_core`声明了外部项目。这个项目的源代码在`${CMAKE_CURRENT_LIST_DIR}/src`文件夹中。该项目设置为`FFTW3_DIR`选项，选择正确的FFTW库: ```cmake 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`文件夹作为构建系统中的另一个子目录: ```cmake add_subdirectory(fftw3) ``` ` external/upstream/fftw3 `中的`CMakeLists.txt`负责处理依赖关系: 1. 首先，尝试在系统上找到FFTW3库。注意，我们配置`find_package`使用的参数: ```cmake find_package(FFTW3 CONFIG QUIET) ``` 2. 如果找到了库，就可以导入目标`FFTW3::FFTW3`来链接它。我们向用户打印一条消息，显示库的位置。我们添加一个虚拟`INTERFACE`库`fftw3_external`。超级建设中，这需要正确地固定子项目之间的依赖树: ```cmake 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校验和进行文件完整性检查: ```cmake 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. 禁用打印下载进程，并将更新命令定义为空: ```cmake OWNLOAD_NO_PROGRESS 1 UPDATE_COMMAND "" ``` 5. 配置、构建和安装输出将被记录到一个文件中: ```cmake LOG_CONFIGURE 1 LOG_BUILD 1 LOG_INSTALL 1 ``` 6. 将`fftw3_external`项目的安装前缀设置为之前定义的`STAGED_INSTALL_PREFIX`目录，并关闭FFTW3的测试套件构建: ```cmake CMAKE_ARGS -DCMAKE_INSTALL_PREFIX=${STAGED_INSTALL_PREFIX} -DBUILD_TESTS=OFF ``` 7. 如果在Windows上构建，通过生成器表达式设置`WITH_OUR_MALLOC`预处理器选项，并关闭`ExternalProject_Add`命令: ```cmake CMAKE_CACHE_ARGS -DCMAKE_C_FLAGS:STRING=$<$<BOOL:WIN32>:-DWITH_OUR_MALLOC> ) ``` 8. 最后，定义`FFTW3_DIR`变量并缓存它。CMake将使用该变量作为`FFTW3::FFTW3`目标的搜索目录: ```cmake 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 cmake_minimum_required(VERSION 3.5 FATAL_ERROR) project(recipe-03_core LANGUAGES C) ``` 2. 使用`find_package`来检测FFTW库，再次使用配置检测模式: ```cmake 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`: ```cmake add_executable(fftw_example fftw_example.c) ``` 4. 为可执行目标设置链接库: ```cmake 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*