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() с результатами.

ExternalData_Add_Target

Функция ExternalData_Add_Target создаёт пользовательскую цель для управления локальными экземплярами файлов данных, хранящихся внешне:

ExternalData_Add_Target(
  <target>   # Name of data management target
  )

Она создаёт пользовательские команды в целевой задаче по мере необходимости, чтобы сделать файлы данных доступными для каждой ссылки DATA{} , ранее оценённой другими функциями, предоставляемыми этим модулем. Файлы данных могут быть извлечены из одного из шаблонов URL, указанных в переменной ExternalData_URL_TEMPLATES, или могут быть найдены локально в одном из путей, указанных в переменной ExternalData_OBJECT_STORES.

Обычно для управления всеми внешними данными в проекте требуется только одна цель. Вызовите эту функцию один раз в конце конфигурации после обработки всех ссылок на данные.

Переменные модуля

Следующие переменные настраивают поведение. Их следует установить перед вызовом любой из функций, предоставляемых этим модулем.

ExternalData_BINARY_ROOT

Переменная ExternalData_BINARY_ROOT может быть установлена в каталог для хранения фактических файлов данных, названных расширенными ссылками DATA{}. По умолчанию CMAKE_BINARY_DIR. Структура каталогов будет копировать структуру ссылок на содержимое под ExternalData_SOURCE_ROOT.

ExternalData_CUSTOM_SCRIPT_<key>

Укажите полный путь к .cmake пользовательскому скрипту извлечения, идентифицированному по <key> в записях списка ExternalData_URL_TEMPLATES. См. Пользовательские скрипты извлечения.

ExternalData_LINK_CONTENT

Переменная ExternalData_LINK_CONTENT может быть установлена в имя поддерживаемого хеш-алгоритма, чтобы включить автоматическое преобразование фактических файлов данных, на которые ссылается синтаксис DATA{}, в ссылки на содержимое. Для каждой такой <file> создаётся ссылка на содержимое, названная <file><ext>. Исходный файл переименовывается в формат .ExternalData_<algo>_<hash>, чтобы подготовить его к будущей передаче в одно из расположений в списке шаблонов URL (методами, которые выходят за рамки этого модуля). Правило извлечения данных, созданное для ссылки на содержимое, будет использовать подготовленный объект, если он не может быть найден с помощью любого шаблона URL.

ExternalData_NO_SYMLINKS

Фактические файлы данных, на которые ссылаются расширенные ссылки 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 должны указывать на каталоги внутри одного дистрибутива исходного кода (например, они приходят вместе в одном архиве).

ExternalData_TIMEOUT_ABSOLUTE

Переменная ExternalData_TIMEOUT_ABSOLUTE устанавливает абсолютный таймаут загрузки в секундах, по умолчанию 300 секунды. Установите в 0 для отключения контроля.

ExternalData_TIMEOUT_INACTIVITY

Переменная ExternalData_TIMEOUT_INACTIVITY устанавливает таймаут неактивности загрузки в секундах, по умолчанию 60 секунды. Установите в 0 для отключения контроля.

ExternalData_URL_ALGO_<algo>_<key>

Укажите пользовательский компонент URL, который будет подставлен для заглушек шаблонов URL вида %(algo:<key>), где <key> — допустимый идентификатор C, при извлечении объекта, на который ссылается алгоритм хеширования <algo>. Если не определено, по умолчанию используется компонент URL <algo> для любого <key>.

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 в текущем каталоге исходного кода, либо файлом img.png.md5, содержащим его контрольную сумму MD5.

Поддерживаются несколько ссылок на содержимое с одинаковым именем и различными алгоритмами хеширования (например, img.png.sha256 и img.png.sha1) при условии, что они все соответствуют одному фактическому файлу. Это позволяет извлекать объекты из источников, индексированных различными алгоритмами хеширования.

Ссылка на серии файлов

Синтаксис DATA{} может быть настроен на извлечение серии файлов в формате DATA{<name>,:}, где : является буквальным. Если дерево исходного кода содержит группу файлов или ссылок на содержимое, названных как серия, то ссылка на один член добавляет правила для извлечения всех из них. Хотя все члены серии извлекаются, только файл, первоначально именованный аргументом DATA{}, заменяется им. По умолчанию конфигурация распознаёт имена серий файлов, заканчивающиеся #.ext, _#.ext, .#.ext, или -#.ext, где # — последовательность десятичных цифр, а .ext — любой отдельный расширение. Настройте его с помощью регулярного выражения, которое анализирует <number> и <suffix> части с конца <name>.

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

Настройте соответствие номера серии с помощью регулярного выражения, которое соответствует части <number> членов серии, именованных <prefix><number><suffix>.

ExternalData_SERIES_MATCH = regex matching <number> in all series members

Обратите внимание, что <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>,...} добавляет правила для получения любых файлов в директории, соответствующих одному из связанных вариантов файла. Например, аргумент MyDataDir передаст полный путь к директории MyDataDir в командной строке и гарантирует, что директория содержит файлы, соответствующие каждому файлу или ссылке на контент в директории источника MyDataDir. Для соответствия связанным файлам в поддиректориях укажите опцию 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

Обратите внимание, что хеши используются только для уникальной идентификации данных и проверки загрузки.

Пользовательские скрипты получения данных

Когда файл данных должен быть получен из одной из шаблонов URL, указанных в переменной ExternalData_URL_TEMPLATES, он обычно загружается с помощью команды file(DOWNLOAD). Можно указать использование пользовательского скрипта получения данных, используя шаблон URL в форме ExternalDataCustomScript://<key>/<loc>. Имя <key> должно быть идентификатором C, а <loc> должно содержать заполнитель %(algo) и %(hash). Переменная, соответствующая ключу ExternalData_CUSTOM_SCRIPT_<key>, должна быть установлена в полный путь к файлу скрипта .cmake. Скрипт будет включён для выполнения фактического получения данных и получит доступ к следующим переменным:

ExternalData_CUSTOM_LOCATION

При загрузке пользовательского скрипта получения данных эта переменная устанавливается в часть расположения URL, которая будет содержать имя алгоритма хеширования и значение хеша содержимого после подстановки.

ExternalData_CUSTOM_FILE

При загрузке пользовательского скрипта получения данных эта переменная устанавливается в полный путь к файлу, в который скрипт должен сохранить полученное содержимое. Имя файла не определено и не должно интерпретироваться каким-либо образом.

Пользовательский скрипт получения данных должен сохранить полученное содержимое в файле или установить переменную:

ExternalData_CUSTOM_ERROR

Если пользовательский скрипт получения данных не может получить запрашиваемое содержимое, он должен установить эту переменную в краткое сообщение в одну строку, описывающее причину сбоя.