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 сумму.

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

Синтаксис 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>,...} добавляет правила для извлечения всех файлов в каталоге, которые соответствуют одному из связанных вариантов файлов. Например, аргумент DATA{MyDataDir/,REGEX:.*} передаст полный путь к каталогу 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

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

Пользовательские скрипты загрузки

Когда файл данных необходимо загрузить из одной из шаблонов 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

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