CMakeFindExternalProject

简介

CMakeFindExternalProject（下称CFEP）是用于CMake构建系统的依赖管理工具。
其实现借助CMake内置的ExternalProject模块。
允许CMake在配置期（而非构建期）安装第三方依赖库。
同时, 它提供了第三方依赖安装, Windows运行时库安装等工具。

功能

使用注意：
以下函数(宏)均允许以小写形式调用
CYGWIN平台也被判定为WINDOWS平台
还为CYGWIN平台的cygwin1.dll添加支持

第三方依赖

CMake提供如下函数: CEFP_find_xxx xxx可以为url，git，dir分别表示从不同的地方下载第三方依赖库。
并不是所有时候都会下载构建并安装(不是安装到全局目录而是安装到)第三方依赖库，只有通过find_package无法定位到库时才会购机第三方库。

从URL下载项目

cfep_find_url(<name>
    [REQUIRED]
    [QUIET]
    [MODULE]
    [URL _url]
    [CMAKE_DIR _dir]
    [PACKAGE ...]
    [EXTERNAL ...]
)

• name 库名，用于find_package。（必须指定）
• REQUIRED 参数表示是否强制找到该库。
• QUITE 参数表示是否保持安静，即不输出信息。
• MODULE 以module模式而非config模式寻找库（只是设置参数的不同，find_package采用相同的策略）。
• URL 指定一个url链接。（必须指定）
• CMAKE_DIR 表示当构建并安装该库后，该库的CMake文件夹和安装目录的相对位置。 若不提供该值，则使用默认值，具体见后文。
• PACKAGE 可跟多个参数, 将应用于find_package。但不可为REQUIRED以及QUIET。
• EXTERNAL 可跟多个参数, 具体见后文。

该函数的执行效果与find_package一样，本质就是调用find_package。 可以设定cache：<name>_BUILD表示必须启用构建, 而不是先find_package。 同时, 还会额外定义一下CACHE。

• <name>_CFEP_FOUND 表示CFEP是否成功构建, 安装第三方依赖库
• <name>_CFEP_BUILD_DIR 表示第三方库的构建位置（不代表找到该库）
• <name>_CFEP_INSTALL 表示第三方库的安装位置
• <name>_CFEP_INSTALL_TYPE 表示第三方库的安装类型，具体见后文

注意：库被安装后会再次执行find_package, 但库成功安装不代表find_package能成功。 同时<name>_CFEP_FOUND也只表示库安装成功, <name>_FOUND才能代表库定位成功 库并不是直接安装在CMAKE_INSTALL_PREFIX中

EXTERNAL参数

EXTERNAL支持如下参数：

NOT_INFO
FORCE

BUILD_DIR _build_dir
INSTALL_DIR _install
TIMEOUT _time

CMAKE_ARGS ...
BUILD_CMAKE_ARGS ...
BUILD_CMAKE_CACHE_ARGS ...
BUILD_CMAKE_CACHE_DEFAULT_ARGS ...

CFEP的原理的构建原理是, 生成一个CMakeLists.txt，其中调用ExternalProject模块, 最后执行CMakeLists.txt。

• NOT_INFO 不显示消息
• FORCE 强制执行 (当多次执行时, CMakeLists.txt不会重复生成, 因此配置步骤的部分内容不会重复执行, 使用该选项将强制CMakeLists.txt重新生成)
• BUILD_DIR 项目构建的位置 默认是：CMAKE_BINARY_DIR/deps/<name>，指定后变为CMAKE_BINARY_DIR/deps/<_build_dir>
• INSTALL_DIR 项目的安装方式：
  • base 或 binary：安装到CMAKE_BINARY_DIR/<name>
  • 其他：安装到_build_dir/install
• TIMEOUT 下载超时(不是构建超时)
• CMAKE_ARGS 运行CMakeLists.txt的CMake命令行参数
• BUILD_CMAKE_ARGS传递给ExternalProject_Add的CMAKE_ARGS参数。已经设定生成器和CMAKE_BUILD_TYPE，以及生成器等参数。
• BUILD_CMAKE_CACHE_ARGS传递给ExternalProject_Add的CMAKE_CACHE_ARGS参数。已经设定生成器和CMAKE_INSTALL_PREFIX参数。
• BUILD_CMAKE_CACHE_DEFAULT_ARGS传递给ExternalProject_Add的CMAKE_CACHE_DEFAULT_ARGS参数。

在_build_dir目录下还包括一些构建日志log, 源码source等。

CMAKE_DIR参数

CFEP安装项目后, 需要找到该项目的cmake文件所在路径，供find_package使用。 因此，CMAKE_DIR参数用于指定cmake文件相对于该库的安装路径的位置。 默认值为： Windows: ./cmake 其他系统: ./shared/cmake/<name>

从git下载项目

与从url下载项目类似, 但没有URL参数, 添加如下参数：

GIT _git
GIT_TAG _tag

• GIT git仓库的地址。不建议使用ssh。（必须指定）
• GIT_TAG git_tag, 可以为hash信息, git标签, git分支名。（必须指定）

其余效果与url相似。 <_build_dir>目录下download文件夹将为空。

从本地文件构建项目

与从url下载项目类似，但没有URL参数，添加如下参数：

SOURCE_DIR _source_dir

• SOURCE_DIR 指定第三方依赖库的文件夹

其余效果与url相似。 <_build_dir>目录下download文件夹将为空。 <_build_dir>目录下将没有source文件夹。

安装第三方依赖

添加到安装目录

将第三方依赖安装到指定位置(随构建树一起安装)，使用函数:

cfep_install(<name>
    [NOT_QUIET]
    [PREFIX _prefix]
)

• name 即第三方依赖库名字, 同CFEP_find_xxx。
• NOT_QUIET 即输出安装信息
• PREFIX 即安装位置, 默认为CMAKE_INSTALL_PREFIX

注意：该函数执行前需要执行CFEP_find_xxx函数。 若CFEP_find_xxx未安装第三方依赖, 则此函数被的执行被忽略。

立即复制到指定位置

将第三方依赖安装的内容复制到指定位置(CMake配置时执行)，使用函数:

cfep_copy_install(<name>
    [NOT_QUIET]
    [DEST _dest]
)

• name 即第三方依赖库名字, 同CFEP_find_xxx。
• NOT_QUIET 即输出安装信息
• DEST 即复制的位置, 默认为CMAKE_BINARY_DIR

注意：该函数执行前需要执行CFEP_find_xxx函数。 若CFEP_find_xxx未安装第三方依赖, 则此函数被的执行被忽略。

Windows动态库

以下函数尽在windows平台生效, 其他平台执行无效果

安装导入库

因为windows平台没有rpath等机制, 因此需要将第三方导入的库的.dll复制到指定位置 使用函数:

wi_install_import(
    [RUNTIME _runtime]
    [LIBRARY _library]
    [TARGETS ...]
)

• RUNTIME 运行时库安装的位置, 默认值为INSTALL_BINDIR
• LIBRARY 导入库的安装位置，默认值为INSTALL_LIBDIR
• TARGETS 安装的对象

wi_install_import是在构建树安装时才安装导入的库。 使用wi_copy_import可以在CMake配置时就复制文件到指定位置。 使用wi_build_import可以在CMake构建时才复制文件到指定位置（本质是添加一个构建目标）。 使用方式和wi_install_import相同。

安装.dll

使用如下函数，可以检索文件夹下的所有dll并安装到指定位置：

wi_install_dll_bin(
    [RUNTIME _runtime]
    [DIRS ...]
)

• RUNTIME 运行时库安装的位置, 默认值为INSTALL_BINDIR
• DIRS 需要检查的目录路径

wi_install_dll_bin是在构建树安装时才安装导入的库。 使用wi_copy_dll_bin可以在CMake配置时就复制文件到指定位置。 使用方式和wi_install_dll_bin相同。

检查是否包含.exe

使用如下函数，检查一个目录是否包含.exe，若包含则将该目录的.dll安装到指定位置：

wi_install_dll_dir(
    [RUNTIME _runtime]
    [DIRS ...]
)

• RUNTIME 运行时库安装的位置, 默认值为INSTALL_BINDIR
• DIRS 需要检查的目录路径

wi_install_dll_dir是在构建树安装时才安装导入的库。 使用wi_copy_dll_dir可以在CMake配置时就复制文件到指定位置。 使用方式和wi_install_dll_dir相同。

安装程序

设定安装路径

设定标准的GNU安装路径, 使用如下函数：

wi_set_install_dir
wi_set_install_dir_quiet

以上两个函数的区别在于, 后者不会显示任何信息。 注意：该函数必须在project指令后执行。

他们将会设定cache:

• INSTALL_LIBDIR 库文件的安装路径
• INSTALL_BINDIR 可执行文件的安装路径
• INSTALL_INCLUDEDIR 头文件的安装路径
• INSTALL_RESOURCEDIR resource文件的安装路径
• INSTALL_CMAKEDIR cmake文件的安装路径

同时还会设定构建时动态库和可执行文件的输出位置

• CMAKE_ARCHIVE_OUTPUT_DIRECTORY
• CMAKE_LIBRARY_OUTPUT_DIRECTORY
• CMAKE_RUNTIME_OUTPUT_DIRECTORY

cygwin支持

使用函数wi_find_cygwin1可以获取cygwin1.dll动态库。 将生成导入目标: CYGWIN::cygwin1

使用方式

将项目中的cmake/CMakeFindExternalProject文件夹放置在项目指定位置, 在cmake中执行：

include(<CMakeFindExternalProject文件夹位置>/init.cmake)

文件介绍

• CMakeFindExternalProject.cmake文件包含的是第三方依赖管理的程序 依赖于CMakeLists.txt.in文件
• WindowsInstall.cmake是.dll安装程序
• InstallDir.cmake是安装路径设置程序以及安装程序 依赖于_void_p_test.c文件，该程序用于检查一个void指针的大小。

声明

开源协议

本程序是在HUAN LICENSE下发布的。