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

Обратите внимание, что имя серии не включает хэш-алгоритмическое расширение.

Ссылка на связанные файлы

Синтаксис 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

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