ExternalData

管理存储在源码树之外的数据文件

简介

使用此模块可以明确引用存储在源码树之外的数据文件，并在构建时从任意本地和远程内容寻址位置获取它们。此模块提供的函数将语法为 DATA{<name>} 的参数识别为对外部数据的引用，将其替换为这些数据本地副本的完整路径，并创建构建规则来获取和更新本地副本。

例如

include(ExternalData)
set(ExternalData_URL_TEMPLATES "file:///local/%(algo)/%(hash)"
                               "file:////host/share/%(algo)/%(hash)"
                               "http://data.org/%(algo)/%(hash)")
ExternalData_Add_Test(MyData
  NAME MyTest
  COMMAND MyExe DATA{MyInput.png}
  )
ExternalData_Add_Target(MyData)

当测试 MyTest 运行时，DATA{MyInput.png} 参数将被替换为磁盘上数据文件 MyInput.png 真实实例的完整路径。如果源码树包含诸如 MyInput.png.md5 的内容链接，则 MyData 目标将在构建树中创建真实的 MyInput.png。

模块函数

ExternalData_Expand_Arguments

ExternalData_Expand_Arguments 函数评估其参数中的 DATA{} 引用，并构建一个新的参数列表。

ExternalData_Expand_Arguments(
  <target>   # Name of data management target
  <outVar>   # Output variable
  [args...]  # Input arguments, DATA{} allowed
  )

它将参数中的每个 DATA{} 引用替换为真实数据文件的完整路径，该数据文件将在 <target> 构建后存在于磁盘上。

ExternalData_Add_Test

ExternalData_Add_Test 函数封装了 CMake add_test() 命令，但支持其参数中的 DATA{} 引用。

ExternalData_Add_Test(
  <target>   # Name of data management target
  ...        # Arguments of add_test(), DATA{} allowed
  )

它将其参数通过 ExternalData_Expand_Arguments 处理，然后使用结果调用 add_test() 命令。

版本 3.31 中有改动： 如果 <target> 之后的参数定义了一个可执行文件为 CMake 目标的测试，则该目标的 TEST_LAUNCHER 和 CROSSCOMPILING_EMULATOR 属性中的空值将保留。请参阅策略 CMP0178。

ExternalData_Add_Target

ExternalData_Add_Target 函数创建自定义目标以管理外部存储的数据文件的本地实例。

ExternalData_Add_Target(
  <target>                  # Name of data management target
  [SHOW_PROGRESS <ON|OFF>]  # Show progress during the download
  )

它在目标中创建必要的自定义命令，以使数据文件可用于此模块提供的其他函数之前评估的每个 DATA{} 引用。数据文件可以从 ExternalData_URL_TEMPLATES 变量中指定的一个 URL 模板中获取，也可以在 ExternalData_OBJECT_STORES 变量中指定的路径之一中本地找到。

版本 3.20 中新增： 可以传递 SHOW_PROGRESS 参数以抑制对象下载期间的进度信息。如果未提供，对于 Ninja 和 Ninja Multi-Config 生成器，它默认为 OFF，否则为 ON。

通常，一个项目只需一个目标来管理所有外部数据。在所有数据引用处理完毕后，在配置结束时调用此函数一次。

模块变量

以下变量配置行为。它们应该在此模块提供的任何函数调用之前设置。

ExternalData_BINARY_ROOT

ExternalData_BINARY_ROOT 变量可以设置为保存由扩展的 DATA{} 引用命名的真实数据文件的目录。默认是 CMAKE_BINARY_DIR。目录布局将与 ExternalData_SOURCE_ROOT 下的内容链接的布局相同。

ExternalData_CUSTOM_SCRIPT_<key>

版本 3.2 中新增。

指定一个完整的路径，指向在 ExternalData_URL_TEMPLATES 列表中由 <key> 标识的 .cmake 自定义获取脚本。请参阅 自定义获取脚本。

ExternalData_HTTPHEADERS

4.0 版本新增。

ExternalData_HTTPHEADERS 变量可用于提供一个头部列表，每个元素包含一个格式为 Key: Value 的头部。请参阅 file(DOWNLOAD) 命令的 HTTPHEADER 选项。

ExternalData_LINK_CONTENT

ExternalData_LINK_CONTENT 变量可以设置为受支持的哈希算法名称，以启用将由 DATA{} 语法引用的真实数据文件自动转换为内容链接。对于每个此类 <file>，将创建一个名为 <file><ext> 的内容链接。原始文件将被重命名为 .ExternalData_<algo>_<hash> 形式，以便为将来传输到 URL 模板列表中的某个位置（通过此模块范围之外的方式）做准备。如果无法使用任何 URL 模板找到内容链接的数据获取规则，它将使用暂存的对象。

ExternalData_NO_SYMLINKS

3.3 版本中新增。

在某些平台上，由展开的 DATA{} 引用命名的真实数据文件可以通过符号链接在 ExternalData_BINARY_ROOT 下可用。ExternalData_NO_SYMLINKS 变量可以设置为禁用符号链接并启用使用副本代替。

ExternalData_OBJECT_STORES

ExternalData_OBJECT_STORES 变量可以设置为一个本地目录列表，这些目录使用 <dir>/%(algo)/%(hash) 布局存储对象。这些目录将首先被搜索以查找所需的对象。如果对象在任何存储中都不可用，则将使用 URL 模板远程获取并添加到列出的第一个本地存储中。如果未指定存储，则默认位置在构建树内部。

ExternalData_SERIES_PARSE

ExternalData_SERIES_PARSE_PREFIX

ExternalData_SERIES_PARSE_NUMBER

ExternalData_SERIES_PARSE_SUFFIX

ExternalData_SERIES_MATCH

请参阅 引用文件序列。

ExternalData_SOURCE_ROOT

ExternalData_SOURCE_ROOT 变量可以设置为包含任何由 DATA{} 引用命名的路径的最高源目录。默认是 CMAKE_SOURCE_DIR。ExternalData_SOURCE_ROOT 和 CMAKE_SOURCE_DIR 必须引用单个源分发中的目录（例如，它们在一个 tarball 中）。

ExternalData_TIMEOUT_ABSOLUTE

ExternalData_TIMEOUT_ABSOLUTE 变量设置下载的绝对超时时间，单位为秒，默认值为 300 秒。设置为 0 以禁用强制执行。

ExternalData_TIMEOUT_INACTIVITY

ExternalData_TIMEOUT_INACTIVITY 变量设置下载的非活动超时时间，单位为秒，默认值为 60 秒。设置为 0 以禁用强制执行。

ExternalData_URL_ALGO_<algo>_<key>

3.3 版本中新增。

指定一个自定义 URL 组件，用于替换 URL 模板中 %(algo:<key>) 形式的占位符，其中 <key> 是一个有效的 C 标识符，当通过哈希算法 <algo> 获取对象时。如果未定义，则对于任何 <key>，默认的 URL 组件就是 <algo>。

ExternalData_URL_TEMPLATES

ExternalData_URL_TEMPLATES 可用于提供一个 URL 模板列表，每个模板中包含 %(algo) 和 %(hash) 占位符。数据获取规则通过将哈希算法名称替换 %(algo)，将哈希值替换 %(hash) 来依次尝试每个 URL 模板。或者，可以使用 %(algo:<key>) 和 ExternalData_URL_ALGO_<algo>_<key> 变量，以在远程 URL 中获得更大的灵活性。

引用文件

引用单个文件

DATA{} 语法是字面量，<name> 是源码树内的完整或相对路径。源码树必须包含 <name> 处的真实数据文件，或者在 <name><ext> 处包含一个“内容链接”，其中包含使用与 <ext> 对应的哈希算法的真实文件的哈希值。例如，参数 DATA{img.png} 可以由当前源目录中的真实 img.png 文件或包含其 MD5 和的 img.png.md5 文件满足。

版本 3.8 中新增： 支持同名但哈希算法不同的多个内容链接（例如 img.png.sha256 和 img.png.sha1），只要它们都对应同一个真实文件即可。这允许从由不同哈希算法索引的源中获取对象。

引用文件序列

DATA{} 语法可以通过 DATA{<name>,:} 形式获取文件序列，其中 : 是字面量。如果源码树包含一组类似序列命名的文件或内容链接，则引用一个成员会添加获取所有成员的规则。尽管会获取序列的所有成员，但只替换最初由 DATA{} 参数命名的文件。默认配置识别以 #.ext, _#.ext, .#.ext, 或 -#.ext 结尾的文件序列名称，其中 # 是一串十进制数字，.ext 是任何单个扩展名。使用正则表达式配置它，该正则表达式从 <name> 的末尾解析 <number> 和 <suffix> 部分。

ExternalData_SERIES_PARSE - 形式为 (<number>)(<suffix>)$ 的正则表达式。

对于更复杂的情况，设置

• ExternalData_SERIES_PARSE - 至少有两个 () 组的正则表达式。

• ExternalData_SERIES_PARSE_PREFIX - <prefix> 的正则表达式组号，如果有的话。

• ExternalData_SERIES_PARSE_NUMBER - <number> 的正则表达式组号。

• ExternalData_SERIES_PARSE_SUFFIX - <suffix> 的正则表达式组号。

配置系列编号匹配，使用正则表达式匹配名为 <prefix><number><suffix> 的系列成员的 <number> 部分

ExternalData_SERIES_MATCH - 匹配所有系列成员中 <number> 的正则表达式

请注意，系列中的 <suffix> 不包括哈希算法扩展名。

引用关联文件

DATA{} 语法也可以匹配与命名文件相关联且位于同一目录中的文件。关联文件可以通过使用 DATA{<name>,<opt1>,<opt2>,...} 语法的选项来指定。每个选项可以按名称指定一个文件，或者使用 REGEX:<regex> 语法指定一个正则表达式来匹配文件名。例如，参数

DATA{MyData/MyInput.mhd,MyInput.img}                   # File pair
DATA{MyData/MyFrames00.png,REGEX:MyFrames[0-9]+\\.png} # Series

将在命令行上传递 MyInput.mha 和 MyFrames00.png，但确保关联文件位于它们旁边。

引用目录

DATA{} 语法可以使用尾部斜杠和关联文件列表来引用目录。形式为 DATA{<name>/,<opt1>,<opt2>,...} 会添加规则以获取目录中与某个关联文件选项匹配的任何文件。例如，参数 DATA{MyDataDir/,REGEX:.*} 将在命令行上传递 MyDataDir 目录的完整路径，并确保该目录包含与 MyDataDir 源目录中的每个文件或内容链接对应的文件。

版本 3.3 中新增： 为了匹配子目录中的关联文件，请指定 RECURSE: 选项，例如 DATA{MyDataDir/,RECURSE:,REGEX:.*}。

哈希算法

支持以下哈希算法

%(算法)	<扩展名>	描述
MD5	.md5	消息摘要算法 5, RFC 1321
SHA1	.sha1	美国安全哈希算法 1, RFC 3174
SHA224	.sha224	美国安全哈希算法, RFC 4634
SHA256	.sha256	美国安全哈希算法, RFC 4634
SHA384	.sha384	美国安全哈希算法, RFC 4634
SHA512	.sha512	美国安全哈希算法, RFC 4634
SHA3_224	.sha3-224	Keccak SHA-3
SHA3_256	.sha3-256	Keccak SHA-3
SHA3_384	.sha3-384	Keccak SHA-3
SHA3_512	.sha3-512	Keccak SHA-3

版本 3.8 中新增： 添加了 SHA3_* 哈希算法。

请注意，哈希值仅用于唯一数据识别和下载验证。

自定义获取脚本

版本 3.2 中新增。

当必须从 ExternalData_URL_TEMPLATES 变量中指定的 URL 模板之一获取数据文件时，通常使用 file(DOWNLOAD) 命令进行下载。可以通过使用 ExternalDataCustomScript://<key>/<loc> 形式的 URL 模板来指定使用自定义获取脚本。<key> 必须是 C 标识符，而 <loc> 必须包含 %(algo) 和 %(hash) 占位符。与键对应的变量 ExternalData_CUSTOM_SCRIPT_<key> 必须设置为 .cmake 脚本文件的完整路径。该脚本将被包含以执行实际获取，并提供以下变量：

ExternalData_CUSTOM_LOCATION

加载自定义获取脚本时，此变量设置为 URL 的位置部分，其中将包含替换后的哈希算法名称和内容哈希值。

ExternalData_CUSTOM_FILE

加载自定义获取脚本时，此变量设置为脚本必须存储获取内容的文件完整路径。文件名未指定，不应以任何方式解释。

自定义获取脚本应将获取的内容存储在文件中或设置变量

ExternalData_CUSTOM_ERROR

当自定义获取脚本未能获取请求的内容时，它必须将此变量设置为描述失败原因的简短一行消息。