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
  [SHOW_PROGRESS <ON|OFF>]  # Show progress during the download
  )

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

Новая функция в версии 3.20: Аргумент SHOW_PROGRESS может быть передан для подавления информации о прогрессе во время загрузки объектов. Если не указано, по умолчанию он равен OFF для генераторов Ninja и Ninja Multi-Config и ON в противном случае.

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

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

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

ExternalData_BINARY_ROOT

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

ExternalData_CUSTOM_SCRIPT_<key>

Новая функция в версии 3.2.

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

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

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>. Если не определено, по умолчанию частью 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.

Алгоритмы хеширования

Поддерживаются следующие алгоритмы хеширования:

%(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

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