ExternalData

此模块提供了用于管理存储在源代码树外部的数据文件的命令。

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

include(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 目标（target）的测试，那么该目标的 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 中新增。

指定一个 .cmake 自定义获取脚本的完整路径，该脚本由 ExternalData_URL_TEMPLATES 列表中的条目通过 <key> 标识。请参阅 Custom Fetch Scripts。

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

请参阅 Referencing File Series。

ExternalData_SOURCE_ROOT

变量 ExternalData_SOURCE_ROOT 可以设置为包含 DATA{} 引用命名的任何路径的最高源目录。默认值为 CMAKE_SOURCE_DIR。ExternalData_SOURCE_ROOT 和 CMAKE_SOURCE_DIR 必须指向同一个源分发包内的目录（例如，它们一起打包）。

ExternalData_TIMEOUT_ABSOLUTE

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

ExternalData_TIMEOUT_INACTIVITY

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

ExternalData_URL_ALGO_<algo>_<key>

3.3 版本中新增。

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

ExternalData_URL_TEMPLATES

变量 ExternalData_URL_TEMPLATES 可以设置为提供一个 URL 模板列表，其中每个模板都使用占位符 %(algo) 和 %(hash)。数据获取规则会按顺序尝试每个 URL 模板，将哈希算法名称替换 %(algo)，并将哈希值替换 %(hash)。或者，您可以使用 %(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:.*}。

哈希算法

支持以下哈希算法：

%(algo)	<ext>	描述
MD5	.md5	Message-Digest Algorithm 5, RFC 1321
SHA1	.sha1	US Secure Hash Algorithm 1, RFC 3174
SHA224	.sha224	US Secure Hash Algorithms, RFC 4634
SHA256	.sha256	US Secure Hash Algorithms, RFC 4634
SHA384	.sha384	US Secure Hash Algorithms, RFC 4634
SHA512	.sha512	US Secure Hash Algorithms, 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) 占位符。一个与 key 对应的变量 ExternalData_CUSTOM_SCRIPT_<key> 必须设置为一个 .cmake 脚本文件的完整路径。该脚本将被包含以执行实际获取，并提供以下变量：

ExternalData_CUSTOM_LOCATION

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

ExternalData_CUSTOM_FILE

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

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

ExternalData_CUSTOM_ERROR

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