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

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