ExternalData

• Введение
• Функции модуля
• Переменные модуля

• Ссылки на файлы

  • Ссылки на отдельные файлы
  • Ссылки на серии файлов
  • Ссылки на связанные файлы
  • Ссылки на каталоги
• Алгоритмы хеширования
• Пользовательские сценарии загрузки

Этот модуль предоставляет команды для управления файлами данных, хранящимися вне дерева исходного кода.

Загрузите этот модуль в проекте CMake с помощью:

include(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_HTTPHEADERS

Добавлено в версии 4.0.

Переменную ExternalData_HTTPHEADERS можно использовать для передачи списка заголовков, каждый элемент которого содержит один заголовок в формате Key: Value. См. параметр HTTPHEADER команды file(DOWNLOAD).

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_STATE_ROOT

Добавлено в версии 4.4.

Переменной ExternalData_STATE_ROOT можно задать каталог для хранения метаданных, управляемых модулем, вне ExternalData_BINARY_ROOT. Если она задана, ExternalData сохраняет записи хешей в этом каталоге, продолжая размещать реальные файлы данных в ExternalData_BINARY_ROOT. По умолчанию записи хешей по-прежнему хранятся рядом с материализованными данными.

ExternalData_LINK_MODE

Добавлено в версии 4.4.

Переменная ExternalData_LINK_MODE задаёт способ предоставления доступа к реальным файлам данных в ExternalData_BINARY_ROOT.

Значением может быть одно из следующих:

auto

Пробовать каждый из поддерживаемых режимов, пока один из них не сработает. Порядок по умолчанию — hardlink -> symlink -> copy в Windows и symlink -> hardlink -> copy на других платформах.

hardlink

Материализовать пути как жёсткие ссылки на реальные файлы.

symlink

Материализовать пути как символические ссылки на реальные файлы.

copy

Материализовать пути как копии реальных файлов.

Либо значением может быть список, разделённый точками с запятой, состоящий из hardlink, symlink и copy; режимы будут проверяться в указанном порядке, пока один из них не сработает.

Если задано значение ExternalData_NO_SYMLINKS, режим symlink исключается из автоматического выбора и не может быть запрошен явно.

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>

Добавлено в версии 3.3.

Укажите пользовательский компонент URL, подставляемый вместо заполнителей шаблона URL вида %(algo:<key>), где <key> — допустимый идентификатор C, при загрузке объекта, указанного с помощью алгоритма хеширования <algo>. Если значение не задано, компонентом URL по умолчанию для любого <key> будет просто <algo>.

ExternalData_URL_TEMPLATES

Переменной ExternalData_URL_TEMPLATES можно задать список шаблонов URL, каждый из которых использует заполнители %(algo) и %(hash). Правила загрузки данных перебирают шаблоны URL по порядку, подставляя имя алгоритма хеширования вместо %(algo), а значение хеша — вместо %(hash). Для большей гибкости при работе с удалёнными URL можно также использовать %(algo:<key>) вместе с переменными ExternalData_URL_ALGO_<algo>_<key>.

Ссылки на файлы

Ссылки на отдельные файлы

Синтаксис 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 — регулярное выражение вида (<number>)(<suffix>)$.

Для более сложных случаев задайте:

• ExternalData_SERIES_PARSE — регулярное выражение как минимум с двумя группами ().
• ExternalData_SERIES_PARSE_PREFIX — номер группы регулярного выражения для <prefix>, если она есть.
• ExternalData_SERIES_PARSE_NUMBER — номер группы регулярного выражения для <number>.
• ExternalData_SERIES_PARSE_SUFFIX — номер группы регулярного выражения для <suffix>.

Настройте сопоставление номеров серии с помощью регулярного выражения, соответствующего части <number> в именах элементов серии вида <prefix><number><suffix>:

ExternalData_SERIES_MATCH — регулярное выражение, которому соответствует <number> во всех элементах серии

Обратите внимание, что <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.

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

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

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

Пользовательские сценарии загрузки

Когда файл данных необходимо загрузить из одного из шаблонов 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

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