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

Изменено в версии 3.31: Если аргументы после <target> определяют тест с исполняемым файлом, который является целевым объектом CMake, пустые значения в свойствах TEST_LAUNCHER и CROSSCOMPILING_EMULATOR этого целевого объекта сохраняются. См. политику CMP0178.

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

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