Cmake | ExternalProject_Add函数详解（构建时）

目录

一、目录选项

1.PREFIX

2.TMP_DIR

3.STAMP_DIR

4.LOG_DIR

5.DOWNLOAD_DIR

6.SOURCE_DIR

7.BINARY_DIR

8.INSTALL_DIR

二、下载配置

1.URL [...]

2.URL_HASH=

3.DOWNLOAD_NO_PROGRESS

三、配置选项

1.CONFIGURE_COMMAND ..

2.CMAKE_COMMAND /.../cmake

3.CMAKE_GENERATOR

4.CMAKE_GENERATOR_PLATFORM

5.CMAKE_GENERATOR_TOOLSET

6.CMAKE_GENERATOR_INSTANCE

7.CMAKE_ARGS ...

8.CMAKE_CACHE_ARGS ...

四、构建选项

1.BUILD_ALWAYS 

五、安装步骤选项

1.INSTALL_COMMAND ...

六、函数应用

1.配置存在的外部项目

 2.下载、配置、安装boost库

七、ExternalProject.cmake与FetchContent.cmake对比

1.FetchContent_Declare

---

        ExternalProject_Add（）函数创建一个自定义目标，以实现外部项目的下载、更新/修补、配置、构建、安装和测试步骤。本文主要讲解常用的一些选项。其他选项看参考官方文档。

ExternalProject_Add(<name> [<option>...])

        ExternalProject_Add函数支持大量选项，用于定制外部项目行为，它允许在构建时检索项目的依赖项。

一、目录选项

1.PREFIX <dir>

        外部项目的根目录。除非下文另有说明，否则与外部项目相关的所有其他目录将在此处创建。

2.TMP_DIR <dir>

        存储临时文件的目录。

3.STAMP_DIR <dir>

        用于存储每个步骤的时间戳的目录。除非被Log_DIR覆盖，否则各个步骤中的日志文件也会在此处创建。

4.LOG_DIR <dir>

        用于存储每个步骤的日志的目录。

5.DOWNLOAD_DIR <dir>

        解包前存储下载文件的目录。此目录仅由URL下载方法使用，所有其他下载方法使用SOURCE_DIR。

6.SOURCE_DIR <dir>

        将下载内容解包到的源目录，或对于非URL下载方法，应在签出、克隆存储库等的目录。如果未指定下载方法，则必须指向外部项目已解包或克隆/签出的现有目录。

        注意：如果指定了下载方法，则可能会删除源目录的任何现有内容。在开始下载之前，只有URL下载方法会检查此目录是否丢失或为空，如果不是空的，则会出现错误停止。所有其他下载方法都会自动放弃源目录中以前的任何内容。

7.BINARY_DIR <dir>

        指定生成目录位置。如果BUILD_IN_SOURCE启用，则忽略此选项。

8.INSTALL_DIR <dir>

        要放置在<INSTALL_DIR>占位符中的安装前缀。这实际上并没有将外部项目配置为安装到给定的前缀。这必须通过向外部项目配置步骤传递适当的参数来完成，例如使用<INSTALL_DIR>。

注意：

        如果以上任何一项未指定_DIR选项，其默认值计算如下:

• 如果给定了PREFIX选项或设置了EP_PREFIX 目录属性，则会在指定的前缀下生成并安装外部项目：

TMP_DIR      = <prefix>/tmp
STAMP_DIR    = <prefix>/src/<name>-stamp
DOWNLOAD_DIR = <prefix>/src
SOURCE_DIR   = <prefix>/src/<name>
BINARY_DIR   = <prefix>/src/<name>-build
INSTALL_DIR  = <prefix>
LOG_DIR      = <STAMP_DIR>

• 如果设置了EP_BASE 目录属性，则外部项目的组件将存储在指定的基目录下：

TMP_DIR      = <prefix>/tmp
STAMP_DIR    = <prefix>/src/<name>-stamp
DOWNLOAD_DIR = <prefix>/src
SOURCE_DIR   = <prefix>/src/<name>
BINARY_DIR   = <prefix>/src/<name>-build
INSTALL_DIR  = <prefix>
LOG_DIR      = <STAMP_DIR>

        如果未指定PREFIX、EP_PREFIX或EP_BASE，则默认设置PREFIX为<name>-PREFIX。x相对路径为在调用ExternalProject_Add（）时，CMAKE_CURRENT_BINARY_DIR所指向的值。

二、下载配置

1.URL <url1> [<url2>...]

        外部项目源的路径或URL列表。当给出多个URL时，会依次尝试，直到其中一个成功。

  include(ExternalProject)
  ExternalProject_Add(boost_external
    URL
      https://sourceforge.net/projects/boost/files/boost/1.61.0/boost_1_61_0.zip
   )

2.URL_HASH<algo>=<hashValue>

        要下载的存档文件的哈希。参数的形式应该是<algo>=<hashValue>，其中algo可以是file（）命令支持的任何哈希算法。强烈建议URL下载时指定此选项，因为它可以确保下载内容的完整性。它还用于检查以前下载的文件，如果本地目录中已有与指定哈希匹配的早期下载文件，则可以完全避免连接到远程位置。

  include(ExternalProject)
  ExternalProject_Add(boost_external
    URL_HASH
          SHA256=02d420e6908016d4ac74dfc712eec7d9616a7fc0da78b0a1b5b937536b2e01e8
  )

3.DOWNLOAD_NO_PROGRESS <bool>

        可用于禁用记录下载进度。如果未给出此选项，将记录下载进度消息。

三、配置选项

        配置步骤在下载和更新步骤之后运行。

1.CONFIGURE_COMMAND <cmd>..

        默认的configure命令根据主项目运行带有几个选项的CMake。添加的选项通常只是使用与主项目相同的生成器所需的选项，但可以使用CMAKE_GENERATOR选项来覆盖此选项。

        对于非CMake外部项目，必须使用CONFIGURE_COMMAND选项覆盖默认的配置命令（支持生成器表达式）。对于不需要配置步骤的项目，使用空字符串指定此选项作为要执行的命令。

2.CMAKE_COMMAND /.../cmake

        为配置步骤指定另一个cmake可执行文件（使用绝对路径）。通常不建议这样做，因为通常希望在整个构建过程中使用相同的CMake版本。如果已使用CONFIGURE_COMMAND指定自定义配置命令，则忽略此选项。

3.CMAKE_GENERATOR <gen>

        重写用于配置步骤的CMake生成器。如果没有此选项，将使用与主版本相同的生成器。如果使用CONFIGURE_COMMAND选项指定了自定义配置命令，则忽略此选项。

4.CMAKE_GENERATOR_PLATFORM <platform>

        将特定于生成器的平台名称传递给CMake命令。在没有CMAKE_GENERATOR 选项的情况下提供此选项是错误的。

5.CMAKE_GENERATOR_TOOLSET <toolset>

        将特定于生成器的工具集名称传递给CMake命令。在没有CMAKE_GENERATOR 选项的情况下提供此选项是错误的。

6.CMAKE_GENERATOR_INSTANCE <instance>

        将特定于生成器的实例选择传递给CMake命令。在没有CMAKE_GENERATOR 选项的情况下提供此选项是错误的。

7.CMAKE_ARGS <arg>...

        指定的参数被传递到cmake命令行。它们可以是cmake命令理解的任何参数，而不仅仅是-D定义的缓存值参数

8.CMAKE_CACHE_ARGS <arg>...

        这是另一种指定缓存变量的方法，在这种情况下，命令行长度问题可能会成为一个问题。参数的格式应为var:STRING=value。（详见例子）

四、构建选项

1.BUILD_ALWAYS <bool>

        启用此选项将强制始终运行构建步骤。这是可靠地确保外部项目自身的构建依赖关系得到评估的最简单方法，而不是依赖基于默认成功时间戳的方法。

五、安装步骤选项

1.INSTALL_COMMAND <cmd>...

        外部项目的安装规则不是主项目的安装规则的一部分，因此，如果外部项目中的任何内容应该作为主版本的一部分进行安装，则需要在主版本中将其指定为附加的install（）命令。默认安装步骤生成外部项目的安装目标，但可以使用此选项使用自定义命令覆盖（支持生成器表达式）。传入空字符串会使安装步骤不执行任何操作。

六、函数应用

1.配置存在的外部项目

#为当前目录和底层目录设置 EP_BASE 目录属性
set_property(DIRECTORY PROPERTY EP_BASE ${CMAKE_BINARY_DIR}/subprojects)

#包括 ExternalProject.cmake 标准模块。该模块提供了 ExternalProject_Add 函数
include(ExternalProject)

ExternalProject_Add(${PROJECT_NAME}_core
  #使用 SOURCE_DIR 选项为外部项目设置源目录
  SOURCE_DIR
    ${CMAKE_CURRENT_LIST_DIR}/src
  #通过 CMAKE_ARGS 选项将适当的CMake选项传递给外部项目
  CMAKE_ARGS
    -DCMAKE_CXX_COMPILER=${CMAKE_CXX_COMPILER}
    -DCMAKE_CXX_STANDARD=${CMAKE_CXX_STANDARD}
    -DCMAKE_CXX_EXTENSIONS=${CMAKE_CXX_EXTENSIONS}
    -DCMAKE_CXX_STANDARD_REQUIRED=${CMAKE_CXX_STANDARD_REQUIRED}
  #通过使用 CMAKE_CACHE_ARGS 选项将C++编译器标志传递到外部项目
  CMAKE_CACHE_ARGS
    -DCMAKE_CXX_FLAGS:STRING=${CMAKE_CXX_FLAGS}
  #配置外部项目，使它进行构建
  BUILD_ALWAYS
    1
  #安装步骤不会执行任何操作
  INSTALL_COMMAND
    ""
  )

 2.下载、配置、安装boost库

  include(ExternalProject)
  ExternalProject_Add(boost_external
	#在下载选项类中指定下载URL和校验码
    URL
      https://sourceforge.net/projects/boost/files/boost/1.61.0/boost_1_61_0.zip
	#URL_HASH 用于检查下载文件的完整性
    URL_HASH
      SHA256=02d420e6908016d4ac74dfc712eec7d9616a7fc0da78b0a1b5b937536b2e01e8
    # DOWNLOAD_NO_PROGRESS 设置为1，以禁止打印下载进度信息
	DOWNLOAD_NO_PROGRESS
      1
	#设置更新/补丁和配置选项
    UPDATE_COMMAND
      ""
    CONFIGURE_COMMAND
      <SOURCE_DIR>/bootstrap.sh
      --with-toolset=${_toolset}
      --prefix=${STAGED_INSTALL_PREFIX}/boost
      ${_bootstrap_select_libraries}
	#构建选项使用 BUILD_COMMAND 设置
    BUILD_COMMAND
      <SOURCE_DIR>/b2 -q
           link=shared
           threading=multi
           variant=release
           toolset=${_toolset}
           ${_b2_select_libraries}
	#将 LOG_BUILD 设置为1，以便将生成脚本中的输出记录到文件中
    LOG_BUILD
      1
	#BUILD_IN_SOURCE 设置为1时，表示构建将在源目录中发生
    BUILD_IN_SOURCE
      1
	#安装命令
    INSTALL_COMMAND
      <SOURCE_DIR>/b2 -q install
           link=shared
           threading=multi
           variant=release
           toolset=${_toolset}
           ${_b2_select_libraries}
	#将安装步骤记录到文件中
    LOG_INSTALL
      1
	#库列表为 BUILD_BYPRODUCTS
    BUILD_BYPRODUCTS
      "${_build_byproducts}"
    )

七、ExternalProject.cmake与FetchContent.cmake对比

        FetchContent.cmake允许在配置时通过ExternalProject.cmake支持的任何方法填充内容。ExternalProject_Add（）在生成时下载，而FetchContent模块使内容立即可用，允许配置步骤使用Add_subdirectory（）、include（）或file（）操作等命令中的内容。

        参考文档：FetchContent — CMake 3.23.0-rc3 Documentation

1.FetchContent_Declare

FetchContent_Declare(<name> <contentOptions>...)

        FetchContent_Declare函数记录描述如何填充指定内容的选项。如果此类详细信息已在该项目的早期记录（无论在项目层次结构中的何处），则会忽略此调用以及以后对相同内容<name>的所有调用。这种“先录制，再赢取”的方法允许分层项目让父项目覆盖子项目的内容细节。

• <name>：可以是任何不带空格的字符串，但最好只使用字母、数字和下划线。该名称将不区分大小写，对于它所代表的内容，它应该是显而易见的，通常是子项目的名称或其顶级project（）命令的值（如果它是CMake项目）。对于知名公共项目，名称通常应为项目的正式名称。选择一个不寻常的名称，使得需要相同内容的其他项目不太可能使用相同的名称，从而导致内容被多次填充。
• <contentOptions>：可以是ExternalProject_Add（）命令理解的任何下载、更新或补丁选项。配置、构建、安装和测试步骤被明确禁用，因此与它们相关的选项将被忽略。SOURCE_SUBDIR选项是一个例外。

        在大多数情况下，<contentOptions>只是定义下载方法和方法特定细节（如提交标记或存档哈希）的几个选项。 

include(FetchContent)
#声明内容——名称、存储库位置和要获取的精确版本
FetchContent_Declare(
     googletest
     GIT_REPOSITORY https://github.com/google/googletest.git
     GIT_TAG release-1.8.0
     )
#查询内容是否已经被获取/填充
FetchContent_GetProperties(googletest)