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
  )

Она создаёт пользовательские команды в целевой задаче по мере необходимости, чтобы сделать файлы данных доступными для каждой ссылки DATA{} ранее оценённой другими функциями этого модуля. Файлы данных могут быть загружены из одного из шаблонов URL, указанных в переменной ExternalData_URL_TEMPLATES, или могут быть найдены локально в одном из путей, указанных в переменной ExternalData_OBJECT_STORES.

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

Переменные модуля

Следующие переменные настраивают поведение. Их следует установить перед вызовом любой из функций, предоставляемых этим модулем.

ExternalData_BINARY_ROOT

Переменная ExternalData_BINARY_ROOT может быть установлена в директорию для хранения реальных файлов данных, именованных расширенными ссылками DATA{}. По умолчанию CMAKE_BINARY_DIR. Структура директорий будет зеркально отражать структуру ссылок на содержимое в ExternalData_SOURCE_ROOT.

ExternalData_CUSTOM_SCRIPT_<key>

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

ExternalData_LINK_CONTENT

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

ExternalData_NO_SYMLINKS

Реальные файлы данных, именованные с помощью расширенных 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>

Укажите пользовательский компонент 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.

Поддерживаются несколько ссылок на содержимое с одинаковым именем, но с разными алгоритмами хеширования (например, img.png.sha256 и img.png.sha1), если они все соответствуют одному реальному файлу. Это позволяет загружать объекты из источников, индексированных различными алгоритмами хеширования.

Ссылка на серии файлов

Синтаксис 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 источника. Для сопоставления связанных файлов в поддиректориях укажите опцию RECURSE:, например DATA{MyDataDir/,RECURSE:,REGEX:.*}.

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

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

%(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

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