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.

New in version 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>

New in version 3.2.

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

ExternalData_LINK_CONTENT

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

ExternalData_NO_SYMLINKS

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

ExternalData_TIMEOUT_ABSOLUTE

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

ExternalData_TIMEOUT_INACTIVITY

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

ExternalData_URL_ALGO_<algo>_<key>

New in version 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

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