ExternalProject ¶

该模块提供了在 CMake 构建阶段下载和构建外部项目的命令。

在 CMake 项目中加载此模块，使用

include(ExternalProject)

外部项目定义 ¶

ExternalProject_Add¶

ExternalProject_Add() 函数创建一个自定义目标，用于驱动外部项目的下载、更新/打补丁、配置、构建、安装和测试步骤。

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

如果需要（例如为了提交到 CDash），流程中的各个步骤可以独立驱动，也可以定义额外的自定义步骤，并能控制步骤间的依赖关系。用于管理外部项目的目录结构也可以自定义。该函数支持大量选项，可用于定制外部项目的行为。

目录选项 ¶

大多数情况下，默认的目录布局已足够。通常主项目不需要更改这些实现细节。但在某些情况下，控制目录布局是有用或必要的。目录选项从主构建可以使用 ExternalProject_Get_Property() 命令检索其值这一角度来看可能更有用，从而允许主项目引用外部项目的构建产物。

PREFIX <dir>: 外部项目的根目录。除非下方另有说明，否则与外部项目相关的所有其他目录都将在此处创建。
TMP_DIR <dir>: 存储临时文件的目录。
STAMP_DIR <dir>: 存储每个步骤时间戳的目录。除非被 LOG_DIR 覆盖（参见下方的日志选项），否则各步骤的日志文件也会在此处创建。
LOG_DIR <dir>: 3.14 版新增。

存储每个步骤日志的目录。
DOWNLOAD_DIR <dir>: 解压前存储下载文件的目录。此目录仅由 URL 下载方法使用，所有其他下载方法会直接使用 SOURCE_DIR。
SOURCE_DIR <dir>: 源目录，下载的内容将被解压至此；或者对于非 URL 下载方法，此处为应检出（checkout）、克隆（clone）等操作的目录。如果未指定下载方法，此项必须指向一个已解压或已克隆/检出外部项目的现有目录。

注意

如果指定了下载方法，源目录中的任何现有内容都可能被删除。只有 URL 下载方法会在发起下载前检查该目录是否缺失或为空，若非空则会报错停止。所有其他下载方法会静默丢弃源目录中的任何先前内容。
BINARY_DIR <dir>: 指定构建目录位置。如果启用了 BUILD_IN_SOURCE，此选项将被忽略。
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      = <base>/tmp/<name>
STAMP_DIR    = <base>/Stamp/<name>
DOWNLOAD_DIR = <base>/Download/<name>
SOURCE_DIR   = <base>/Source/<name>
BINARY_DIR   = <base>/Build/<name>
INSTALL_DIR  = <base>/Install/<name>
LOG_DIR      = <STAMP_DIR>

如果未指定 PREFIX、EP_PREFIX 或 EP_BASE，则默认将 PREFIX 设置为 <name>-prefix。相对路径根据调用 ExternalProject_Add() 时的 CMAKE_CURRENT_BINARY_DIR 进行解析。

下载步骤选项 ¶

如果使用 SOURCE_DIR 选项指向一个现有的非空目录，则可以省略下载方法。否则，必须指定以下下载方法之一（不应提供多种下载方法），或提供一个自定义的 DOWNLOAD_COMMAND。

DOWNLOAD_COMMAND <cmd>...: 覆盖用于下载步骤的命令（支持 生成器表达式）。如果指定了此选项，所有其他下载选项将被忽略。为 <cmd> 提供空字符串将有效地禁用下载步骤。

外部项目源代码的路径和/或 URL 列表。当给定多个 URL 时，它们会依次尝试，直到有一个成功为止。URL 可以是本地文件系统中的普通路径（在这种情况下，它必须是提供的唯一 URL）或 file(DOWNLOAD) 命令支持的任何可下载 URL。本地文件系统路径可以指向现有目录或归档文件，而 URL 则预期指向可视为归档的文件。使用归档文件时，除非设置了 DOWNLOAD_NO_EXTRACT 选项以阻止它，否则它会自动解压。归档类型通过检查实际内容来确定，而不是基于文件扩展名的逻辑。

3.7 版本变更: 允许使用多个 URL。

URL_HASH <algo>=<hashValue>

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

URL_MD5 <md5>

等同于 URL_HASH MD5=<md5>。

DOWNLOAD_NAME <fname>

用于下载文件的文件名。如果未给定，则使用 URL 的末尾来确定文件名。此选项很少需要，默认名称通常是合适的，且通常不会在 ExternalProject 模块内部代码之外使用。

DOWNLOAD_EXTRACT_TIMESTAMP <bool>

在 3.24 版本中添加。

当指定为 true 值时，解压文件的修改时间戳将与归档文件中的一致。当为 false 时，解压文件的修改时间戳将反映执行解压时的时间。如果下载 URL 发生变化，基于归档中时间戳的设置可能导致依赖目标在可能需要重新构建时没有被重新构建。因此，除非文件时间戳对项目有某种特殊意义，否则请为此选项使用 false 值。如果未给出 DOWNLOAD_EXTRACT_TIMESTAMP，默认值为 false。参见策略 CMP0135。

DOWNLOAD_NO_EXTRACT <bool>

3.6 版本新增。

通过为该选项传递布尔真值，允许禁用下载步骤的解压部分。如果未给定该选项，下载的内容将在需要时自动解压。如果禁用了提取，下载文件的完整路径将作为后续步骤中的 <DOWNLOADED_FILE> 可用，或通过 ExternalProject_Get_Property() 命令作为属性 DOWNLOADED_FILE 可用。

DOWNLOAD_NO_PROGRESS <bool>

可用于禁用下载进度的日志记录。如果未给出该选项，则会记录下载进度消息。

TIMEOUT <seconds>

文件下载操作允许的最长时间。

INACTIVITY_TIMEOUT <seconds>

3.19 版本新增。

在一段不活动时间后终止操作。

HTTP_USERNAME <username>

3.7 版本中新增。

如果需要身份验证，则为下载操作提供用户名。

HTTP_PASSWORD <password>

3.7 版本中新增。

如果需要身份验证，则为下载操作提供密码。

HTTP_HEADER <header1> [<header2>...]

3.7 版本中新增。

为下载操作提供任意的 HTTP 标头列表。这对于访问 AWS 等系统中的内容非常有用。

TLS_VERSION <min>

3.30 版本新增。

为 https:// URL 指定最低 TLS 版本。如果未提供此选项，则将改用 CMAKE_TLS_VERSION 变量或 CMAKE_TLS_VERSION 环境变量的值（参见 file(DOWNLOAD)）。

此选项也适用于 git clone 调用，尽管默认行为不同。如果未指定 TLS_VERSION 选项、CMAKE_TLS_VERSION 变量或 CMAKE_TLS_VERSION 环境变量，行为将由 git 的默认设置或用户可能在全局级别设置的 http.sslVersion git 配置选项决定。

TLS_VERIFY <bool>

指定是否应对 https:// URL 执行证书验证。如果未提供此选项，则改用 CMAKE_TLS_VERIFY 变量或 CMAKE_TLS_VERIFY 环境变量的值（参见 file(DOWNLOAD)）。如果两者均未设置，则不执行证书验证。在无法提供 URL_HASH 的情况下，此选项可以作为替代验证措施。

此选项也适用于 git clone 调用，尽管默认行为不同。如果未指定 TLS_VERIFY 选项、CMAKE_TLS_VERIFY 变量或 CMAKE_TLS_VERIFY 环境变量，行为将由 git 的默认设置（true）或用户可能在全局级别设置的 http.sslVerify git 配置选项决定。

3.6 版本变更: 以前此选项不适用于 git clone 调用。

3.30 版本变更: 以前不检查 CMAKE_TLS_VERIFY 环境变量。

TLS_CAINFO <file>

如果启用了 TLS_VERIFY，则指定自定义证书颁发机构文件。如果未指定此选项，则将改用 CMAKE_TLS_CAINFO 变量的值（参见 file(DOWNLOAD)）。

NETRC <level>

3.11 版本新增。

指定是否在操作中使用 .netrc 文件。如果未指定此选项，则改用 CMAKE_NETRC 变量的值（参见 file(DOWNLOAD)）。有效级别为：

IGNORED: .netrc 文件被忽略。这是默认值。
OPTIONAL: .netrc 文件是可选的，URL 中的信息优先。将扫描文件以查找 URL 中未指定的任何信息。
REQUIRED: .netrc 文件是必须的，URL 中的信息将被忽略。

NETRC_FILE <file>

3.11 版本新增。

如果 NETRC 级别为 OPTIONAL 或 REQUIRED，则指定除主目录中默认文件外的替代 .netrc 文件。如果未指定此选项，则改用 CMAKE_NETRC_FILE 变量的值（参见 file(DOWNLOAD)）。

3.1 版本新增: 增加了对 .tbz2、.tar.xz、.txz 和 .7z 扩展名的支持。

4.1 版本新增: 无论文件扩展名如何，均支持 cmake -E tar 可以解压的所有归档类型。

Git ¶

注意：如果使用此下载方法，需要 1.6.5 或更高版本的 git。

GIT_REPOSITORY <url>

Git 仓库的 URL。可以使用 git 命令能够理解的任何 URL。

3.27 版本变更: 相对 URL 将根据父项目的远程地址进行解析，受 CMP0150 约束。有关如何选择远程地址（包括远程选择可能失败的情况），请参阅策略文档。本地文件系统远程应始终使用绝对路径。

GIT_TAG <tag>

Git 分支名、标签或提交哈希。请注意，分支名和标签通常应指定为远程名称（即 origin/myBranch 而不是简单的 myBranch）。这可以确保如果远程端的标签移动、分支变基（rebase）或历史被重写，本地克隆仍能正确更新。然而，通常出于多种原因，应优先指定提交哈希。

如果本地克隆已经拥有哈希对应的提交，则每次重新运行 CMake 时无需执行 git fetch 来检查更改。如果使用了许多外部项目，这可以显著提高速度。
使用特定的 git 哈希可以确保主项目自身的历史完全可追溯到外部项目演进的特定点。如果改为使用分支或标签名称，那么检出主项目的特定提交并不一定将整个构建锁定在外部项目的生命周期中的特定点。这种确定性行为的缺失会使主项目失去可追溯性和可重复性。

如果启用了 GIT_SHALLOW，则 GIT_TAG 仅适用于分支名和标签。不允许使用提交哈希。

请注意，如果未提供，GIT_TAG 默认为 master，而不是默认的 Git 分支名称。

GIT_REMOTE_NAME <name>

远程名称（可选）。如果未指定此选项，则默认为 origin。

GIT_SUBMODULES <module>...

也应更新的特定 git 子模块。如果未提供此选项，则将更新所有 git 子模块。

3.16 版本变更: 当 CMP0097 设置为 NEW 时，如果此值设置为空字符串，则不会初始化或更新任何子模块。

GIT_SUBMODULES_RECURSE <bool>

在 3.17 版本中添加。

指定是否通过将 --recursive 标志传递给 git submodule update 来递归更新 git 子模块（如果有）。如果未指定，默认值为开启。

GIT_SHALLOW <bool>

3.6 版本新增。

启用此选项后，git clone 操作将获得 --depth 1 选项。这将执行浅克隆，避免下载整个历史记录，而是仅检索 GIT_TAG 选项指定的提交。

GIT_PROGRESS <bool>

版本 3.8 新增。

启用后，此选项指示 git clone 操作通过传递 --progress 选项来报告其进度。如果没有此选项，大型项目的克隆步骤可能会看起来使构建停滞，因为在克隆操作完成之前不会记录任何内容。虽然此选项可用于提供进度以防止构建看起来停滞，但如果使用了大量外部项目，它也可能使构建输出变得过于冗余。

GIT_CONFIG <option1> [<option2>...]

版本 3.8 新增。

指定要传递给 git clone 的配置选项列表。列出的每个选项都将被转换为 git clone 命令行上的自身 --config <option>，每个选项都要求采用 key=value 的形式。

GIT_REMOTE_UPDATE_STRATEGY <strategy>

在 3.18 版本中新增。

当 GIT_TAG 引用远程分支时，此选项可用于指定更新步骤的行为。 <strategy> 必须是以下之一：

CHECKOUT: 忽略本地分支，始终检出 GIT_TAG 指定的分支。
REBASE: 尝试将当前分支变基到 GIT_TAG 指定的分支。如果有未提交的本地更改，它们将先被贮藏（stash），变基后再弹出（pop）。如果变基或弹出贮藏的更改失败，则中止变基并报错停止。当不存在 GIT_REMOTE_UPDATE_STRATEGY 时，除非默认值已被 CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY 覆盖（见下文），否则这是默认策略。注意，如果 GIT_TAG 中指定的分支与当前正在跟踪的上游分支不同，则执行变基是不安全的。在这种情况下，REBASE 将静默地被视为 CHECKOUT。
REBASE_CHECKOUT: 与 REBASE 相同，不同之处在于如果变基失败，会在变基前的原始 HEAD 位置创建一个带注释的标签，然后像 CHECKOUT 策略一样检出 GIT_TAG。存储在带注释标签上的信息将给出尝试内容，并且标签名称将包含时间戳，以便每次失败的运行都会添加一个新标签。此策略确保不会丢失任何更改，但只要 GIT_TAG 指向有效的引用，更新就应该总是成功，除非存在无法成功弹出的未提交更改。

可以设置变量 CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY 以覆盖默认策略。此变量不应由项目设置，旨在由用户设置。它主要用于持续集成脚本，以确保当远程分支上的历史被重写时，构建不会因变基操作期间的冲突而导致意外的更改或构建失败。

Subversion ¶

SVN_REPOSITORY <url>: Subversion 仓库的 URL。
SVN_REVISION -r<rev>: 从 Subversion 仓库检出的修订版本。
SVN_USERNAME <username>: Subversion 检出和更新的用户名。
SVN_PASSWORD <password>: Subversion 检出和更新的密码。
SVN_TRUST_CERT <bool>: 指定是否信任 Subversion 服务器站点证书。如果启用，--trust-server-cert 选项将被传递给 svn 检出和更新命令。

Mercurial ¶

HG_REPOSITORY <url>: Mercurial 仓库的 URL。
HG_TAG <tag>: Mercurial 分支名、标签或提交 ID。

CVS ¶

CVS_REPOSITORY <cvsroot>: CVS 仓库的 CVSROOT。
CVS_MODULE <mod>: 从 CVS 仓库检出的模块。
CVS_TAG <tag>: 从 CVS 仓库检出的标签。

更新步骤选项 ¶

每当重新运行 CMake 时，默认情况下如果下载方法支持更新，外部项目的源代码将会更新（例如，如果 GIT_TAG 没有引用特定的提交，则会检查 git 仓库）。

UPDATE_COMMAND <cmd>...

使用自定义命令覆盖下载方法的更新步骤。该命令可以使用 生成器表达式。

UPDATE_DISCONNECTED <bool>

版本 3.2 中新增。

启用此选项后，更新步骤将被跳过（但请参见下文关于更改行为的情况）。它不会阻止下载步骤。更新步骤仍可以作为步骤目标添加（参见 ExternalProject_Add_StepTargets()）并手动调用。如果您希望允许开发人员在断开网络的情况下构建项目（尽管下载步骤可能仍需要网络），这将非常有用。

3.27 版本变更: 当 UPDATE_DISCONNECTED 为 true 时，如果有关更新或下载步骤的任何详细信息发生更改，更新步骤将会执行。此外，如果使用 git 下载/更新方法，更新逻辑将被修改为跳过连接远程的尝试。如果 GIT_TAG 提到的引用在本地未知，更新步骤将以致命错误停止。

当存在此选项时，通常建议将该值作为开发人员可控制的缓存变量，而不是硬编码。如果不存在此选项，默认值取自 EP_UPDATE_DISCONNECTED 目录属性。如果该属性也未定义，则按正常情况执行更新。EP_UPDATE_DISCONNECTED 目录属性旨在作为控制项目目录层次结构中整个部分的 UPDATE_DISCONNECTED 行为的一种便利方法，并且可能是给予开发人员是否执行更新控制权的更便捷方法（假设项目还提供了一个缓存变量或某种其他方便的方法来设置目录属性）。

这可能会导致 download 步骤自动创建一个步骤目标。参见策略 CMP0114。

补丁步骤选项 ¶

PATCH_COMMAND <cmd>...: 指定在更新后修补源代码的自定义命令。默认情况下，不定义补丁命令。请注意，定义一个稳健执行的适当补丁命令可能非常困难，特别是对于 git 等下载方法，其中更改 GIT_TAG 不会丢弃来自先前补丁的更改，但补丁命令会在更新到新标签后再次被调用。

配置步骤选项 ¶

配置步骤在下载和更新步骤之后运行。默认情况下，假定外部项目是一个 CMake 项目，但如果需要可以覆盖此假设。

CONFIGURE_COMMAND <cmd>...

默认的配置命令根据主项目运行带有少量选项的 CMake。添加的选项通常仅是使用与主项目相同的生成器所必需的选项，但可以给定 CMAKE_GENERATOR 选项来覆盖此设置。项目负责添加其希望从主项目重用或以其他方式指定的任何工具链详细信息、标志或其他设置（参见下文的 CMAKE_ARGS、CMAKE_CACHE_ARGS 和 CMAKE_CACHE_DEFAULT_ARGS）。

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

CMAKE_COMMAND /.../cmake

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

CMAKE_GENERATOR <gen>

覆盖配置步骤使用的 CMake 生成器。没有此选项，将使用与主构建相同的生成器。如果已使用 CONFIGURE_COMMAND 选项指定了自定义配置命令，则忽略此选项。

CMAKE_GENERATOR_PLATFORM <platform>

版本 3.1 中新增。

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

CMAKE_GENERATOR_TOOLSET <toolset>

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

CMAKE_GENERATOR_INSTANCE <instance>

3.11 版本新增。

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

CMAKE_ARGS <arg>...

指定的参数传递给 cmake 命令行。它们可以是 cmake 命令理解的任何参数，不仅仅是 -D... 定义的缓存值（另请参见 CMake 选项）。

3.3 版本新增: 参数可以使用 生成器表达式。

CMAKE_CACHE_ARGS <arg>...

这是指定缓存变量的另一种方式，可解决命令行长度问题。参数预期采用 -Dvar:STRING=value 的形式，然后被转换为使用 FORCE 选项的 CMake set() 命令。这些 set() 命令被写入一个预加载脚本，然后使用 cmake -C 命令行选项应用。

3.3 版本新增: 参数可以使用 生成器表达式。

CMAKE_CACHE_DEFAULT_ARGS <arg>...

版本 3.2 中新增。

这与 CMAKE_CACHE_ARGS 选项相同，只是 set() 命令不包含 FORCE 关键字。这意味着这些值仅作为初始默认值，不会覆盖先前运行中已经设置的任何变量。请谨慎使用此选项，因为它可能导致不同的行为，具体取决于构建是从全新的构建目录开始还是重用了先前的构建内容。

3.15 版本新增: 如果 CMake 生成器是 Green Hills MULTI 且未被覆盖，则原始项目关于 GHS 工具集和目标系统定制缓存变量的设置将传播到外部项目中。

SOURCE_SUBDIR <dir>

3.7 版本中新增。

当未指定 CONFIGURE_COMMAND 选项时，配置步骤假定外部项目在其源树顶部（即在 SOURCE_DIR 中）具有 CMakeLists.txt 文件。SOURCE_SUBDIR 选项可用于指向源树内的替代目录，以作为 CMake 源树的顶部使用。这必须是相对路径，并将被解释为相对于 SOURCE_DIR。

3.14 版本新增: 当启用 BUILD_IN_SOURCE 选项时，BUILD_COMMAND 用于指向源树内的替代目录。

CONFIGURE_HANDLED_BY_BUILD <bool>

在 3.20 版本中添加。

启用此选项会将配置步骤对其他外部项目的依赖关系放宽为仅顺序依赖（order-only）。这意味着配置步骤将在其外部项目依赖项构建后执行，但当其外部项目依赖项之一被重新构建时，它不会被标记为脏。当构建步骤足够智能，能够确定是否需要重新运行配置步骤时，可以启用此选项。CMake 和 Meson 是构建系统示例，其构建步骤足够智能，知道是否需要重新运行配置步骤。

CONFIGURE_ENVIRONMENT_MODIFICATION <modification>...

版本 4.2 中添加。

指定应为配置步骤修改的环境变量。

设置一个分号分隔的列表，环境的变量和值形式为 MYVAR=OP:VALUE，其中 MYVAR 是要修改的环境变量的区分大小写的名称。条目按属性值中指定的顺序考虑。 OP 可以是以下之一：

reset：重置为未修改的值，忽略在此条目之前对 MYVAR 的所有修改。请注意，这将把变量重置为 ENVIRONMENT 设置的值（如果已设置），否则重置为其在其余 CTest 执行中的状态。
set：用 VALUE 替换 MYVAR 的当前值。
unset：取消设置 MYVAR 的当前值。
string_append：将单个 VALUE 追加到 MYVAR 的当前值。
string_prepend：将单个 VALUE 前置到 MYVAR 的当前值。
path_list_append：使用宿主平台的路径列表分隔符（Windows 上为 ;，其他地方为 :）将单个 VALUE 追加到 MYVAR 的当前值。
path_list_prepend：使用宿主平台的路径列表分隔符（Windows 上为 ;，其他地方为 :）将单个 VALUE 前置到 MYVAR 的当前值。
cmake_list_append：使用 ; 作为分隔符将单个 VALUE 追加到 MYVAR 的当前值。
cmake_list_prepend：使用 ; 作为分隔符将单个 VALUE 前置到 MYVAR 的当前值。

ExternalProject_Add(example
  ... # Download options, etc...
  CONFIGURE_ENVIRONMENT_MODIFICATION
    SDKROOT=set:macosx
    PKG_CONFIG_PATH=set:$ENV{PKG_CONFIG_PATH}
)

此代码片段在配置示例项目时定义了两个环境变量。 SDKROOT 环境变量设置为 macosx，而 PKG_CONFIG_PATH 的值被转发到外部项目。

环境修改与 LIST_SEPARATOR 配合使用，将环境变量中的分隔符替换为 ;。

ExternalProject_Add(example
  ... # Download options, etc...
  LIST_SEPARATOR ,
  CONFIGURE_ENVIRONMENT_MODIFICATION
    LIST_VAR=set:a,b,c
)

此代码片段和环境变量 LIST_VAR 以值 a;b;c 传递给配置命令调用。

构建步骤选项 ¶

如果配置步骤假定外部项目使用 CMake 作为其构建系统，则构建步骤也将如此。否则，构建步骤将假定基于 Makefile 的构建，并简单地运行 make，且不带参数作为默认构建步骤。如果需要，这可以用自定义构建命令覆盖。

如果主项目和外部项目都使用 make 作为它们的构建工具，则外部项目的构建步骤将作为递归 make 使用 $(MAKE) 调用。这将把一些构建工具设置从主项目传达给外部项目。如果主项目或外部项目未使用 make，则不会将除配置步骤建立的之外的构建工具设置传递给外部项目（即在主项目中运行 ninja -v 不会向外部项目的构建步骤传递 -v，即使它也使用 ninja 作为其构建工具）。

BUILD_COMMAND <cmd>...

覆盖默认构建命令（支持 生成器表达式）。如果未给定此选项，将选择默认构建命令以最合适的方式与主构建集成（例如，Makefile 生成器使用递归 make，如果项目使用 CMake 构建，则使用 cmake --build）。此选项可以指定为空字符串作为命令，以使构建步骤不执行任何操作。

BUILD_IN_SOURCE <bool>

启用此选项后，构建将直接在外部项目的源树内完成。通常应避免这种情况，使用单独的构建目录通常更可取，但当外部项目假定源内构建时，这可能很有用。如果在源内构建，则不应指定 BINARY_DIR 选项。

BUILD_ALWAYS <bool>

启用此选项会强制始终运行构建步骤。这可能是确保外部项目自身的构建依赖项被评估，而不是依赖于基于默认成功时间戳方法的稳健方法，这是最简单的方法。除非预期开发人员会以无法通过步骤目标依赖项检测到的方式修改外部项目构建所依赖的内容（例如，使用没有下载方法的 SOURCE_DIR，且开发人员可能会修改 SOURCE_DIR 中的源），否则通常不需要此选项。

BUILD_BYPRODUCTS <file>...

版本 3.2 中新增。

指定将由构建命令生成的文件，但其修改时间可能更新也可能不更新后续构建。使用 Ninja 生成器时，这也可能是显式声明依赖项所必需的。这些最终作为 BYPRODUCTS 传递给构建步骤自身对 add_custom_command() 的底层调用，该调用具有附加文档。

BUILD_JOB_SERVER_AWARE <bool>

版本 3.28 新增。

指定构建步骤知晓 GNU Make 作业服务器。有关详细信息，请参阅 add_custom_command() 文档中关于其 JOB_SERVER_AWARE 选项的内容。此选项仅在指定了显式 BUILD_COMMAND 时才相关。

BUILD_ENVIRONMENT_MODIFICATION <modification>...

版本 4.2 中添加。

指定应为构建步骤修改的环境变量。

设置一个分号分隔的列表，环境的变量和值形式为 MYVAR=OP:VALUE，其中 MYVAR 是要修改的环境变量的区分大小写的名称。条目按属性值中指定的顺序考虑。 OP 可以是以下之一：

reset：重置为未修改的值，忽略在此条目之前对 MYVAR 的所有修改。请注意，这将把变量重置为 ENVIRONMENT 设置的值（如果已设置），否则重置为其在其余 CTest 执行中的状态。
set：用 VALUE 替换 MYVAR 的当前值。
unset：取消设置 MYVAR 的当前值。
string_append：将单个 VALUE 追加到 MYVAR 的当前值。
string_prepend：将单个 VALUE 前置到 MYVAR 的当前值。
path_list_append：使用宿主平台的路径列表分隔符（Windows 上为 ;，其他地方为 :）将单个 VALUE 追加到 MYVAR 的当前值。
path_list_prepend：使用宿主平台的路径列表分隔符（Windows 上为 ;，其他地方为 :）将单个 VALUE 前置到 MYVAR 的当前值。
cmake_list_append：使用 ; 作为分隔符将单个 VALUE 追加到 MYVAR 的当前值。
cmake_list_prepend：使用 ; 作为分隔符将单个 VALUE 前置到 MYVAR 的当前值。

安装步骤选项 ¶

如果配置步骤假定外部项目使用 CMake 作为其构建系统，则安装步骤也将如此。否则，安装步骤将假定基于 Makefile 的构建，并简单地运行 make install 作为默认构建步骤。如果需要，这可以用自定义安装命令覆盖。

INSTALL_COMMAND <cmd>...: 外部项目自身的安装步骤作为主项目构建的一部分被调用。它在外部项目的构建步骤之后执行，并且可能在外部项目的测试步骤之前或之后（参见下文的 TEST_BEFORE_INSTALL 选项）。外部项目的安装规则不属于主项目的安装规则，因此如果外部项目的任何内容应作为主构建的一部分进行安装，则需要将这些内容在主构建中指定为额外的 install() 命令。默认安装步骤构建外部项目的 install 目标，但可以使用此选项通过自定义命令覆盖它（支持 生成器表达式）。将空字符串作为 <cmd> 传递使安装步骤不执行任何操作。
INSTALL_BYPRODUCTS <file>...: 3.26 版新增。

指定将由安装命令生成的文件，但其修改时间可能更新也可能不更新后续安装。使用 Ninja 生成器时，这也可能是显式声明依赖项所必需的。这些最终作为 BYPRODUCTS 传递给安装步骤自身对 add_custom_command() 的底层调用，该调用具有附加文档。
INSTALL_JOB_SERVER_AWARE <bool>: 4.0 版本新增。

指定安装步骤知晓 GNU Make 作业服务器。有关详细信息，请参阅 add_custom_command() 文档中关于其 JOB_SERVER_AWARE 选项的内容。此选项仅在指定了显式 INSTALL_COMMAND 时才相关。

注意

如果构建主项目时设置了 CMAKE_INSTALL_MODE 环境变量，则仅在满足以下条件时才会产生影响：

主项目的配置步骤假定外部项目使用 CMake 作为其构建系统。
外部项目的安装命令实际运行。请注意，由于 ExternalProject 可能在内部使用时间戳，如果安装步骤依赖的任何内容都不需要重新执行，则安装命令可能也不需要运行。

还要注意，ExternalProject 不会检查 CMAKE_INSTALL_MODE 环境变量是否在运行之间发生变化。

INSTALL_ENVIRONMENT_MODIFICATION <modification>...

版本 4.2 中添加。

指定应为安装步骤修改的环境变量。

设置一个分号分隔的列表，环境的变量和值形式为 MYVAR=OP:VALUE，其中 MYVAR 是要修改的环境变量的区分大小写的名称。条目按属性值中指定的顺序考虑。 OP 可以是以下之一：

reset：重置为未修改的值，忽略在此条目之前对 MYVAR 的所有修改。请注意，这将把变量重置为 ENVIRONMENT 设置的值（如果已设置），否则重置为其在其余 CTest 执行中的状态。
set：用 VALUE 替换 MYVAR 的当前值。
unset：取消设置 MYVAR 的当前值。
string_append：将单个 VALUE 追加到 MYVAR 的当前值。
string_prepend：将单个 VALUE 前置到 MYVAR 的当前值。
path_list_append：使用宿主平台的路径列表分隔符（Windows 上为 ;，其他地方为 :）将单个 VALUE 追加到 MYVAR 的当前值。
path_list_prepend：使用宿主平台的路径列表分隔符（Windows 上为 ;，其他地方为 :）将单个 VALUE 前置到 MYVAR 的当前值。
cmake_list_append：使用 ; 作为分隔符将单个 VALUE 追加到 MYVAR 的当前值。
cmake_list_prepend：使用 ; 作为分隔符将单个 VALUE 前置到 MYVAR 的当前值。

测试步骤选项 ¶

仅当提供了以下至少一个 TEST_... 选项时，才会定义测试步骤。

TEST_COMMAND <cmd>...

覆盖默认测试命令（支持 生成器表达式）。如果未给定此选项，测试步骤的默认行为是构建外部项目自身的 test 目标。此选项可以将 <cmd> 指定为空字符串，这允许仍定义测试步骤，但它不会执行任何操作。如果将空字符串作为测试命令，请勿指定任何其他 TEST_... 选项，但如果不需要测试步骤目标，则最好完全省略所有 TEST_... 选项。

TEST_BEFORE_INSTALL <bool>

启用此选项后，测试步骤将在安装步骤之前执行。默认行为是测试步骤在安装步骤之后运行。

TEST_AFTER_INSTALL <bool>

此选项主要作为指示需要测试步骤但所有默认行为已足够的一种方式非常有用。将此选项指定为布尔真值可确保定义测试步骤，并且它在安装步骤之后。如果同时启用了 TEST_BEFORE_INSTALL 和 TEST_AFTER_INSTALL，则后者将被静默忽略。

TEST_EXCLUDE_FROM_MAIN <bool>

版本 3.2 中新增。

如果启用，主构建的默认 ALL 目标将不依赖于测试步骤。这可以作为一种确保定义了测试步骤但仅在手动请求时才被调用的有效方式。这可能会导致 install 或 build 步骤自动创建步骤目标。参见策略 CMP0114。

TEST_ENVIRONMENT_MODIFICATION <modification>...

版本 4.2 中添加。

指定应为测试步骤修改的环境变量。

设置一个分号分隔的列表，环境的变量和值形式为 MYVAR=OP:VALUE，其中 MYVAR 是要修改的环境变量的区分大小写的名称。条目按属性值中指定的顺序考虑。 OP 可以是以下之一：

reset：重置为未修改的值，忽略在此条目之前对 MYVAR 的所有修改。请注意，这将把变量重置为 ENVIRONMENT 设置的值（如果已设置），否则重置为其在其余 CTest 执行中的状态。
set：用 VALUE 替换 MYVAR 的当前值。
unset：取消设置 MYVAR 的当前值。
string_append：将单个 VALUE 追加到 MYVAR 的当前值。
string_prepend：将单个 VALUE 前置到 MYVAR 的当前值。
path_list_append：使用宿主平台的路径列表分隔符（Windows 上为 ;，其他地方为 :）将单个 VALUE 追加到 MYVAR 的当前值。
path_list_prepend：使用宿主平台的路径列表分隔符（Windows 上为 ;，其他地方为 :）将单个 VALUE 前置到 MYVAR 的当前值。
cmake_list_append：使用 ; 作为分隔符将单个 VALUE 追加到 MYVAR 的当前值。
cmake_list_prepend：使用 ; 作为分隔符将单个 VALUE 前置到 MYVAR 的当前值。

输出日志选项 ¶

以下每个 LOG_... 选项都可用于在脚本中包装相关步骤，以将其输出捕获到文件中。日志文件将在 LOG_DIR（如果已提供）中创建，否则在具有特定步骤文件名的 STAMP_DIR 目录中创建。

LOG_DOWNLOAD <bool>: 启用后，下载步骤的输出将被记录到文件中。
LOG_UPDATE <bool>: 启用后，更新步骤的输出将被记录到文件中。
LOG_PATCH <bool>: 3.14 版新增。

启用后，补丁步骤的输出将被记录到文件中。
LOG_CONFIGURE <bool>: 启用后，配置步骤的输出将被记录到文件中。
LOG_BUILD <bool>: 启用后，构建步骤的输出将被记录到文件中。
LOG_INSTALL <bool>: 启用后，安装步骤的输出将被记录到文件中。
LOG_TEST <bool>: 启用后，测试步骤的输出将被记录到文件中。
LOG_MERGED_STDOUTERR <bool>: 3.14 版新增。

启用后，对于任何输出被记录到文件的步骤，stdout 和 stderr 将被合并。
LOG_OUTPUT_ON_FAILURE <bool>: 3.14 版新增。

此选项仅在启用了至少一个其他 LOG_<step> 选项时才有效。如果启用了文件日志记录的步骤发生错误，并且 LOG_OUTPUT_ON_FAILURE 设置为 true，则该步骤的输出将打印到控制台。对于记录了大量输出的情况，可能只会将输出的末尾部分打印到控制台。

终端访问选项 ¶

3.4 版本新增。

在某些情况下，可以授予步骤直接访问终端的权限。授予步骤对终端的访问权限可能允许它在需要时接收终端输入，例如其他选项未提供的身份验证详细信息。使用 Ninja 生成器，这些选项将步骤置于 console 作业池 中。每个步骤可以通过以下选项单独授予对终端的访问权限：

USES_TERMINAL_DOWNLOAD <bool>: 授予下载步骤对终端的访问权限。
USES_TERMINAL_UPDATE <bool>: 授予更新步骤对终端的访问权限。
USES_TERMINAL_PATCH <bool>: 在版本 3.23 中添加。

授予补丁步骤对终端的访问权限。
USES_TERMINAL_CONFIGURE <bool>: 授予配置步骤对终端的访问权限。
USES_TERMINAL_BUILD <bool>: 授予构建步骤对终端的访问权限。
USES_TERMINAL_INSTALL <bool>: 授予安装步骤对终端的访问权限。
USES_TERMINAL_TEST <bool>: 授予测试步骤对终端的访问权限。

目标选项 ¶

DEPENDS <targets>...: 指定外部项目所依赖的其他目标。其他目标将在执行外部项目的任何步骤之前更新。因为外部项目在内部为每个步骤使用额外的自定义目标，所以 DEPENDS 选项是确保所有这些步骤都依赖于其他目标的最便捷方式。仅仅执行 add_dependencies(<name> <targets>) 不会使任何步骤依赖于 <targets>。
EXCLUDE_FROM_ALL <bool>: 启用此选项后，该选项将外部项目从主构建的默认 ALL 目标中排除。
STEP_TARGETS <step-target>...: 为指定步骤生成自定义目标。如果需要手动触发步骤或者如果它们需要用作其他目标的依赖项，则需要这样做。如果未指定此选项，则默认值取自 EP_STEP_TARGETS 目录属性。有关此选项效果的进一步讨论，请参阅下方的 ExternalProject_Add_StepTargets()。
INDEPENDENT_STEP_TARGETS <step-target>...: 3.19 版本弃用：仅当策略 CMP0114 未设置为 NEW 时，才允许这样做。

为指定的步骤生成自定义目标，并防止这些目标应用通常的依赖项。如果未指定此选项，则默认值取自 EP_INDEPENDENT_STEP_TARGETS 目录属性。此选项主要用于允许独立驱动各个步骤，例如在 CDash 设置中，每个步骤应单独启动和报告，而不是作为一个整体构建。有关此选项效果的进一步讨论，请参阅下文的 ExternalProject_Add_StepTargets()。

杂项选项 ¶

LIST_SEPARATOR <sep>

对于各种 ..._COMMAND 选项、CMAKE_ARGS 以及 ..._ENVIRONMENT_MODIFICATION` 操作，ExternalProject 将把指定命令行中的 <sep> 替换为 ;。这可用于确保命令中包含字面的 ;，否则直接使用会被 CMake API 解释为参数分隔符。请注意，应选择一个不会与非列表分隔符用法相混淆的分隔符。例如，使用 LIST_SEPARATOR 允许在命令行上传递列表值给 CMake 缓存变量。

ExternalProject_Add(example
  ... # Download options, etc.
  LIST_SEPARATOR ","
  CMAKE_ARGS "-DCMAKE_PREFIX_PATH:STRING=${first_prefix},${second_prefix}"
)

COMMAND <cmd>...

任何其他 ..._COMMAND 选项可以通过在其后附加所需数量的 COMMAND ... 选项来追加额外的命令（支持 生成器表达式）。例如：

ExternalProject_Add(example
  ... # Download options, etc.
  BUILD_COMMAND ${CMAKE_COMMAND} -E echo "Starting $<CONFIG> build"
  COMMAND       ${CMAKE_COMMAND} --build <BINARY_DIR> --config $<CONFIG>
  COMMAND       ${CMAKE_COMMAND} -E echo "$<CONFIG> build complete"
)

还应注意，每个构建步骤都是通过调用 ExternalProject_Add_Step() 创建的。有关某些选项支持的自动替换，请参阅该命令的文档。

获取项目属性 ¶

ExternalProject_Get_Property¶

ExternalProject_Get_Property() 函数检索外部项目目标属性。

ExternalProject_Get_Property(<name> <prop1> [<prop2>...])

该函数将属性值存储在同名的变量中。属性名称对应于 ExternalProject_Add() 的关键字参数名称。例如，可以按如下方式检索源目录：

ExternalProject_Get_property(myExtProj SOURCE_DIR)
message("Source dir of myExtProj = ${SOURCE_DIR}")

显式步骤管理 ¶

ExternalProject_Add() 函数本身通常足以将外部项目集成到主构建中。某些场景需要额外的工作来实现所需行为，例如添加自定义步骤或将步骤作为可手动触发的目标。 ExternalProject_Add_Step()、ExternalProject_Add_StepTargets() 和 ExternalProject_Add_StepDependencies 函数提供了实现此类步骤级功能所需的底层控制。

ExternalProject_Add_Step¶

ExternalProject_Add_Step() 函数为通过先前调用 ExternalProject_Add() 定义的外部项目指定一个额外的自定义步骤。

ExternalProject_Add_Step(<name> <step> [<option>...])

<name> 与传递给原始 ExternalProject_Add() 调用的名称相同。指定的 <step> 不得是预定义步骤之一（mkdir、download、update、patch、configure、build、install 或 test）。支持的选项如下：

COMMAND <cmd>...

由该自定义步骤执行的命令行（支持 生成器表达式）。此选项可以重复多次，以指定按顺序执行的多个命令。

COMMENT "<text>..."

自定义步骤执行时要打印的文本。

DEPENDEES <step>...

此步骤所依赖的其他步骤（自定义或预定义）。

DEPENDERS <step>...

依赖于此新自定义步骤的其他步骤（自定义或预定义）。

DEPENDS <file>...

此自定义步骤所依赖的文件。

ENVIRONMENT_MODIFICATION <modification>...

版本 4.2 中添加。

指定在运行外部项目步骤中的命令时应修改的环境变量。

设置一个分号分隔的列表，环境的变量和值形式为 MYVAR=OP:VALUE，其中 MYVAR 是要修改的环境变量的区分大小写的名称。条目按属性值中指定的顺序考虑。 OP 可以是以下之一：

reset：重置为未修改的值，忽略该条目之前对 MYVAR 的所有修改。请注意，如果设置了 ENVIRONMENT，这将把变量重置为由该属性设置的值，否则重置为 CTest 执行其余部分中的状态。
set：用 VALUE 替换 MYVAR 的当前值。
unset：取消设置 MYVAR 的当前值。
string_append：将单个 VALUE 追加到 MYVAR 的当前值。
string_prepend：将单个 VALUE 前置到 MYVAR 的当前值。
path_list_append：使用宿主平台的路径列表分隔符（Windows 上为 ;，其他地方为 :）将单个 VALUE 追加到 MYVAR 的当前值。
path_list_prepend：使用宿主平台的路径列表分隔符（Windows 上为 ;，其他地方为 :）将单个 VALUE 前置到 MYVAR 的当前值。
cmake_list_append：使用 ; 作为分隔符将单个 VALUE 追加到 MYVAR 的当前值。
cmake_list_prepend：使用 ; 作为分隔符将单个 VALUE 前置到 MYVAR 的当前值。

INDEPENDENT <bool>

3.19 版本新增。

指定此步骤是否独立于 ExternalProject_Add() 的 DEPENDS 选项指定的外部依赖项。默认值为 FALSE。标记为独立的步骤只能依赖于其他标记为独立的步骤。请参阅策略 CMP0114。

请注意，此处使用的“独立”一词仅指独立于 DEPENDS 选项指定的外部目标，并且与步骤对其他步骤的依赖关系正交。

如果通过 ExternalProject_Add() 的 STEP_TARGETS 选项或 ExternalProject_Add_StepTargets() 函数为独立步骤创建了步骤目标，它将不会依赖于外部目标，但可能依赖于其他步骤的目标。

BYPRODUCTS <file>...

版本 3.2 中新增。

此自定义步骤将生成的文件，但其修改时间可能不会被后续构建更新。在使用 Ninja 生成器时，这对于显式声明依赖项可能是必需的。此文件列表最终将作为 BYPRODUCTS 选项传递给内部用于实现自定义步骤的 add_custom_command()，该命令有额外的文档。

ALWAYS <bool>

启用此选项时，指定应始终运行此自定义步骤（即始终将其视为过期）。

JOB_SERVER_AWARE <bool>

版本 3.28 新增。

指定自定义步骤是否感知 GNU Make 作业服务器。有关详细信息，请参阅 add_custom_command() 文档中关于其 JOB_SERVER_AWARE 选项的内容。

EXCLUDE_FROM_MAIN <bool>

启用此选项时，指定外部项目的主目标不依赖于此自定义步骤。这可能会导致为该步骤所依赖的步骤自动创建步骤目标。请参阅策略 CMP0114。

WORKING_DIRECTORY <dir>

指定在运行自定义步骤命令之前要设置的工作目录。如果未指定此选项，则目录将为调用 ExternalProject_Add_Step() 时 CMAKE_CURRENT_BINARY_DIR 的值。

LOG <bool>

如果设置，这将导致自定义步骤的输出被捕获到外部项目的 LOG_DIR（如果已提供）或 STAMP_DIR 中的文件中。

USES_TERMINAL <bool>

如果启用，此选项会在可能的情况下给予自定义步骤对终端的直接访问权限。

每个标准和自定义步骤的命令行、注释、工作目录和副产品都会被处理，以将标记 <SOURCE_DIR>、<SOURCE_SUBDIR>、<BINARY_DIR>、<INSTALL_DIR>、<TMP_DIR>、<DOWNLOAD_DIR> 和 <DOWNLOADED_FILE> 替换为在原始调用 ExternalProject_Add() 中定义的相应属性值。

3.3 版本新增：标记替换扩展到副产品。

3.11 版本新增： <DOWNLOAD_DIR> 替换标记。

ExternalProject_Add_StepTargets¶

ExternalProject_Add_StepTargets() 函数为所列步骤生成目标。每个创建的目标名称格式为 <name>-<step>。

ExternalProject_Add_StepTargets(<name> <step1> [<step2>...])

为步骤创建目标允许将其用作另一个目标的依赖项或手动触发。拥有特定步骤的目标还可以通过在构建命令行上指定目标来独立驱动它们。例如，您可能正在提交到一个基于子项目的仪表板，您希望驱动构建的配置部分，然后提交到仪表板，接着是构建部分，最后是测试。如果您调用一个依赖于步骤链中间某步骤的自定义目标，则之前的所有步骤也将运行，以确保一切都是最新的。

在内部，ExternalProject_Add() 调用 ExternalProject_Add_Step() 来创建每个步骤。如果指定了任何 STEP_TARGETS，则在 ExternalProject_Add_Step() 之后也会调用 ExternalProject_Add_StepTargets()。即使 STEP_TARGETS 选项中未提及某步骤，稍后仍可调用 ExternalProject_Add_StepTargets() 来手动定义该步骤的目标。

ExternalProject_Add() 的 STEP_TARGETS 选项通常是确保为感兴趣的特定步骤创建目标的最简单方法。对于自定义步骤，如果也应为该自定义步骤创建目标，则必须显式调用 ExternalProject_Add_StepTargets()。这两个选项的替代方法是填充 EP_STEP_TARGETS 目录属性。它作为步骤目标选项的默认值，可以在定义多个外部项目时省去重复指定相同步骤目标集的麻烦。

3.19 版本新增：如果 CMP0114 设置为 NEW，步骤目标将完全负责持有实现其步骤的自定义命令。由 ExternalProject_Add 创建的主要目标依赖于步骤目标，步骤目标彼此依赖。目标级依赖关系与自定义命令为每个步骤使用的文件级依赖关系匹配。使用 ExternalProject_Add_Step() 的 INDEPENDENT 选项创建的步骤目标，不依赖于 ExternalProject_Add() 的 DEPENDS 选项指定的外部目标。预定义步骤 mkdir、download、update 和 patch 是独立的。

如果 CMP0114 不是 NEW，则可以使用以下已弃用的行为：

可以在 <name> 之后、第一个步骤之前立即指定已弃用的 NO_DEPENDS 选项。如果指定了 NO_DEPENDS 选项，步骤目标将不依赖于外部项目的依赖项（即不依赖于由 ExternalProject_Add() 创建的 <name> 自定义目标的任何依赖项）。这对于 download、update 和 patch 步骤通常是安全的，因为它们通常不需要更新和构建依赖项。但是，对任何其他预定义步骤使用 NO_DEPENDS 可能会破坏并行构建。仅在确定命名步骤确实没有依赖项时才使用 NO_DEPENDS。对于自定义步骤，请考虑自定义命令是否需要配置、构建和安装依赖项。
ExternalProject_Add() 的 INDEPENDENT_STEP_TARGETS 选项，或 EP_INDEPENDENT_STEP_TARGETS 目录属性，指示该函数在内部为指定步骤调用使用 NO_DEPENDS 选项的 ExternalProject_Add_StepTargets()。

ExternalProject_Add_StepDependencies¶

版本 3.2 中新增。

ExternalProject_Add_StepDependencies() 函数可用于向步骤添加依赖项。添加的依赖项必须是 CMake 已知的目标（可以是普通的可执行文件或库目标、自定义目标，甚至是另一个外部项目的步骤目标）。

ExternalProject_Add_StepDependencies(<name> <step> <target1> [<target2>...])

此函数负责设置目标级和文件级依赖关系，并将确保并行构建不会被破坏。每当为 ExternalProject 模块生成的某些步骤目标添加依赖项时，都应使用它，而不是 add_dependencies()。

示例 ¶

以下示例展示了如何从 GitHub 下载并构建一个名为 FooBar 的假设项目。

include(ExternalProject)
ExternalProject_Add(foobar
  GIT_REPOSITORY    git@github.com:FooCo/FooBar.git
  GIT_TAG           origin/release/1.2.3
)

为了示例起见，定义第二个名为 SecretSauce 的假设外部项目，它从 Web 服务器下载。为了利用更快的内部网络（如果可用），提供了两个 URL，并回退到较慢的外部服务器。该项目是一个没有配置步骤的典型 Makefile 项目，因此重写了一些默认命令。构建仅要求构建 sauce 目标。

find_program(MAKE_EXE NAMES gmake nmake make)
ExternalProject_Add(secretsauce
  URL               http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
                    https://www.somecompany.com/downloads/sauce-2.7.zip
  URL_HASH          MD5=d41d8cd98f00b204e9800998ecf8427e
  CONFIGURE_COMMAND ""
  BUILD_COMMAND     ${MAKE_EXE} sauce
)

假设 secretsauce 的构建步骤要求必须已经构建好 foobar。这可以强制执行如下：

ExternalProject_Add_StepDependencies(secretsauce build foobar)

另一种选择是为 foobar 的构建步骤创建一个自定义目标，并让 secretsauce 依赖于该目标，而不是整个 foobar 项目。这意味着 foobar 只需要构建，在 secretsauce 可以构建之前，它不需要运行其安装或测试步骤。依赖关系也可以与 secretsauce 项目一起定义。

ExternalProject_Add_StepTargets(foobar build)
ExternalProject_Add(secretsauce
  URL               http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
                    https://www.somecompany.com/downloads/sauce-2.7.zip
  URL_HASH          MD5=d41d8cd98f00b204e9800998ecf8427e
  CONFIGURE_COMMAND ""
  BUILD_COMMAND     ${MAKE_EXE} sauce
  DEPENDS           foobar-build
)

与其调用 ExternalProject_Add_StepTargets()，不如与 foobar 项目本身一起定义目标。

ExternalProject_Add(foobar
  GIT_REPOSITORY git@github.com:FooCo/FooBar.git
  GIT_TAG        origin/release/1.2.3
  STEP_TARGETS   build
)

如果许多外部项目应具有相同的步骤目标集，则设置目录属性可能更方便。通过在用 ExternalProject_Add() 创建外部项目之前设置 EP_STEP_TARGETS 目录属性，可以自动创建 build 步骤目标。

set_property(DIRECTORY PROPERTY EP_STEP_TARGETS build)

最后，假设 secretsauce 提供了一个名为 makedoc 的脚本，可用于生成其文档。进一步假设该脚本期望输出目录作为唯一参数提供，并且应该从 secretsauce 源目录运行。可以定义自定义步骤和触发该脚本的自定义目标，如下所示：

ExternalProject_Add_Step(secretsauce docs
  COMMAND           <SOURCE_DIR>/makedoc <BINARY_DIR>
  WORKING_DIRECTORY <SOURCE_DIR>
  COMMENT           "Building secretsauce docs"
  ALWAYS            TRUE
  EXCLUDE_FROM_MAIN TRUE
)
ExternalProject_Add_StepTargets(secretsauce docs)

然后可以从主构建中触发该自定义步骤，如下所示：

cmake --build . --target secretsauce-docs

ExternalProject ¶

外部项目定义 ¶

目录选项 ¶

下载步骤选项 ¶

URL ¶

Git ¶

Subversion ¶

Mercurial ¶

CVS ¶

更新步骤选项 ¶

补丁步骤选项 ¶

配置步骤选项 ¶

构建步骤选项 ¶

安装步骤选项 ¶

测试步骤选项 ¶

输出日志选项 ¶

终端访问选项 ¶

目标选项 ¶

杂项选项 ¶

获取项目属性 ¶

显式步骤管理 ¶

示例 ¶

目录

上一主题

下一主题

本页