外部数据 ¶

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

介绍 ¶

使用此模块可以明确引用存储在源树外部的数据文件，并在构建时从任意本地和远程内容寻址位置获取它们。此模块提供的函数将语法为“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:command:add_test 命令，但在其参数中支持 DATA{} 引用

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

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

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 列表的条目中指定 .cmake 自定义提取脚本的完整路径，该脚本由 <key> 标识。请参阅“自定义获取脚本”。

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

ExternalData_NO_SYMLINKS¶: 在 3.3 版本加入.

在某些平台上，可以使用符号链接在 ExternalData_BINARY_ROOT 下提供由扩展的 DATA{} 引用命名的真实数据文件。 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 组件来替换形式为 %(algo:<key>) 的 URL 模板占位符，其中 <key> 是有效的 C 标识符``<算法>``。如果未定义，则默认 URL 组件只是任何 <key> 的 <algo>。

ExternalData_URL_TEMPLATES¶: ExternalData_URL_TEMPLATES 可以设置为在每个模板中使用占位符 %(algo) 和 %(hash) 来提供 URL 模板列表。数据获取规则按顺序尝试每个 URL 模板，方法是用散列算法名称代替 %(algo) 和散列值代替 %(hash)。或者，可以将 %(algo:<key>) 与 ExternalData_URL_ALGO_<algo>_<key> 变量一起使用，以获得远程 URL 的更大灵活性。

DATA{} 语法是文字，<name> 是源代码树中的完整路径或相对路径。源树必须在 <name> 处包含一个真实的数据文件，或者在 <name><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 = regex of the form (<number>)(<suffix>)$

对于更复杂的情况集

ExternalData_SERIES_PARSE = regex with at least two () groups
ExternalData_SERIES_PARSE_PREFIX = <prefix> regex group number, if any
ExternalData_SERIES_PARSE_NUMBER = <number> regex group number
ExternalData_SERIES_PARSE_SUFFIX = <suffix> regex group number

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

ExternalData_SERIES_MATCH = regex matching <number> in all series members

请注意，系列的“<后缀>”不包括哈希算法扩展。

引用关联文件 ¶

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>     Description
-------     -----     -----------
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) 占位符。与键对应的变量，ExternalData_CUSTOM_SCRIPT_<key>，必须设置为``.cmake``脚本文件的完整路径。该脚本将被包含以执行实际的提取，并提供以下变量：

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

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

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

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

外部数据 ¶

介绍 ¶

模块功能 ¶

模块变量 ¶

引用文件 ¶

引用单个文件 ¶

参考文件系列 ¶

引用关联文件 ¶

引用目录 ¶

哈希算法 ¶

自定义获取脚本 ¶

目录

上一主题

下一主题

本页