8. Артефакты

Артефакты Pkg объявляются в файле Artifacts.toml, который может быть помещен в текущий каталог или корень пакета. В настоящее время Pkg поддерживает скачивание tar-файлов (которые могут быть сжаты) с URL-адреса. Ниже приведен минимальный файл Artifacts.toml, который позволит скачать socrates.tar.gz из github.com. В этом примере определен один артефакт, которому присвоено имя socrates.

Если этот файл Artifacts.toml помещен в текущий каталог, то socrates.tar.gz можно скачать, распаковать и использовать вместе с artifact"socrates". Поскольку этот tar-архив содержит папку bin и текстовый файл с именем socrates в этой папке, мы можем получить доступ к содержимому этого файла следующим образом.

Если у вас есть существующий tar-архив, доступ к которому осуществляется с помощью url, к нему также можно обращаться таким же образом. Для создания Artifacts.toml необходимо вычислить два хэша: хэш sha256 скачанного файла и хэш git-tree-sha1 распакованного содержимого. Их можно вычислить следующим образом.

Чтобы получить доступ к этому артефакту из созданного пакета, поместите файл Artifacts.toml в корень пакета, рядом с файлом Project.toml. Затем обязательно добавьте Pkg в deps и задайте julia = "1.3" или выше в разделе compat.

Pkg предоставляет API для работы с артефактами, а также формат файлов TOML для записи использования артефактов в пакетах и для автоматизации скачивания артефактов во время установки пакета. На артефакты всегда можно ссылаться по хэшу содержимого, но доступ к ним обычно осуществляется по имени, привязанному к хэшу содержимого в файле Artifacts.toml, который находится в дереве исходного кода проекта.

Вот пример файла Artifacts.toml:

Этот файл Artifacts.toml привязывает три артефакта: один с именем socrates, один с именем c_simple и один с именем processed_output. Единственным обязательным элементом информации для артефакта является его git-tree-sha1. Поскольку артефакты рассматриваются только по хэшу содержимого, назначение файла Artifacts.toml — предоставить метаданные об этих артефактах, например связать удобное для восприятия человеком имя с хэшем содержимого, предоставить информацию о том, откуда можно скачать артефакт, или даже связать одно имя с несколькими хэшами, привязанными к характерным для платформы ограничениям, таким как операционная система или версия libgfortran.

В приведенном выше примере артефакт socrates демонстрирует платформонезависимый артефакт с несколькими местами скачивания. При загрузке и установке артефакта socrates URL-адреса будут перебираться по порядку до тех пор, пока не будет найден нужный. Артефакт socrates помечен как lazy, что означает, что он не будет автоматически скачан при установке содержащего его пакета, а будет скачан по требованию, когда пакет впервые попытается его использовать.

Артефакт c_simple демонстрирует платформозависимый артефакт, где каждая запись в массиве c_simple содержит ключи, которые помогают вызывающему пакету выбрать подходящие файлы для скачивания на основе особенностей хост-компьютера. Обратите внимание, что каждый артефакт содержит как git-tree-sha1, так и sha256 для каждой записи скачивания. Это необходимо для того, чтобы убедиться в безопасности загруженного tar-архива перед попыткой его распаковки, а также для того, чтобы гарантировать, что все tar-архивы должны расширяться до одного и того же общего хэша дерева.

Артефакт processed_output не содержит раздел download и поэтому не может быть установлен. Подобный артефакт является результатом выполнения кода, который был запущен ранее и сгенерировал новый артефакт и привязал полученный хэш к имени в рамках данного проекта.

Для работы с артефактами можно использовать вспомогательные API, предоставляемые из пространства имен Pkg.Artifacts. В качестве мотивирующего примера представим, что мы пишем пакет, который должен загрузить набор данных машинного обучения «Ирис». Хотя можно было бы просто скачать набор данных на этапе сборки в каталог пакета и многие пакеты сейчас именно так и поступают, этот способ имеет ряд существенных недостатков.

Используя артефакты, вместо этих действий мы проверим, существует ли артефакт iris на диске, и только если его там нет, скачаем и установим его, после чего сможем привязать результат к файлу Artifacts.toml:

Для конкретного случая использования артефактов, которые были ранее связаны, существует сокращение artifact"name", которое автоматически ищет файл Artifacts.toml, содержащийся в текущем пакете, ищет заданный артефакт по имени, устанавливает его, если он еще не установлен, а затем возвращает путь к этому артефакту. Пример этого сокращения приведен ниже.

API Artifacts разбит на три уровня: функции с поддержкой хэша, функции с поддержкой имен и служебные функции.

Полный список docstrings и методов приведен в разделе Справочник по артефактам.

Иногда требуется переопределить расположение и содержимое артефакта. Распространенным случаем является вычислительная среда, в которой должны использоваться определенные версии двоичных зависимостей, независимо от того, с какой версией этой зависимости был опубликован пакет. Хотя стандартная конфигурация Julia скачивает, распаковывает и соединяет с общей библиотекой, системному администратору может понадобиться отключить эти возможности и вместо них использовать библиотеку, уже установленную на локальном компьютере. Для этого Pkg поддерживает файл Overrides.toml для каждого хранилища, размещаемый в каталоге хранилища artifacts (например, ~/.julia/artifacts/Overrides.toml для пользовательского хранилища по умолчанию), который может переопределять расположение артефакта либо по хэшу содержимого, либо по UUID пакета и привязанному имени артефакта. Кроме того, местом назначения может быть либо абсолютный путь, либо хэш содержимого заменяющего артефакта. Это позволяет системным администраторам создавать собственные артефакты, которые они могут использовать, переопределяя другие пакеты для применения нового артефакта.

В связи с многоуровневым характером хранилищ Pkg одновременно могут быть задействованы несколько файлов Overrides.toml. Это позволяет «внутренним» файлам Overrides.toml переопределять переопределения, размещенные во «внешних» файлах Overrides.toml. Чтобы удалить переопределение и снова включить логику расположения по умолчанию для артефакта, вставьте запись, сопоставляющую пустую строку:

Если два фрагмента Overrides.toml, приведенные выше, наложить друг на друга, конечным результатом будет сопоставление хэша содержимого 78f35e74ff113f02274ce60dab6e92b4546ef806 с "/path/to/new/replacement" и сопоставление Foo.libbar с артефактом, идентифицируемым хэшем содержимого 683942669b4639019be7631caa28c38f3e1924fe. Обратите внимание, что если раньше этот хэш был переопределен, то теперь это не так, и поэтому Foo.libbar будет обращаться непосредственно к таким расположениям, как ~/.julia/artifacts/683942669b4639019be7631caa28c38f3e1924fe.

Большинство методов, затрагиваемых переопределениями, могут игнорировать переопределения, если для них задано honor_overrides=false в качестве именованного аргумента. Для работы переопределений на основе UUID или имени файлы Artifacts.toml должны быть загружены с учетом UUID загружаемого пакета. Это автоматически определяет строковой макрос artifacts"", однако, если вы по какой-то причине вручную используете API Pkg.Artifacts в своем пакете и хотите учитывать переопределения, необходимо предоставить UUID пакета таким вызовам API, как artifact_meta() и ensure_artifact_installed(), с помощью именованного аргумента pkg_uuid.

Новое в Julia 1.6: к объектам Platform могут быть применены расширенные атрибуты, что позволяет добавлять к артефактам такие метки, как совместимость с версией драйвера CUDA, совместимость микроархитектур, совместимость с версией Julia и проч. Обратите внимание, что эта функция считается экспериментальной и может измениться в будущем. Если вы, как разработчик пакетов, сочтете эту функцию необходимой, свяжитесь с нами, чтобы мы смогли доработать ее на благо всей экосистемы. Для поддержки выбора артефакта во время Pkg.add() Pkg запустит специально именованный файл <project_root>/.pkg/select_artifacts.jl, передав в качестве первого аргумента триплет текущей платформы. Этот скрипт выбора артефактов должен вывести TOML-сериализованный словарь, представляющий артефакты, которые нужны этому пакету в соответствии с заданной платформой, и выполнить любую проверку системы, необходимую для автоматического определения возможностей платформы, если триплет данной платформы не предоставляет их явным образом. Формат словаря должен соответствовать формату, возвращаемому из Artifacts.select_downloadable_artifacts(), и действительно, большинство пакетов должны просто вызывать эту функцию с дополненным объектом Platform. Пример определения обработчика выбора артефакта может выглядеть следующим образом с разделением между двумя файлами:

В этом определении обработчика процедура расширения платформы открывает системную библиотеку (libcuda), ищет в ней символ, который выдает версию драйвера CUDA, а затем внедряет номер основной версии в свойство cuda объекта Platform, который мы расширяем. Хотя этот код не обязательно должен закрывать загруженную библиотеку (поскольку она, скорее всего, будет снова открыта пакетом CUDA сразу после завершения операций с пакетом), лучше всего сделать обработчики как можно более простыми и прозрачными, поскольку в будущем их могут использовать другие служебные функции Pkg. В своем пакете при применении макроса @artifact_str также следует использовать объекты расширенной платформы, как показано ниже:

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

Обработчики выбора артефактов могут использовать только Base, Artifacts, Libdl и TOML. Они не могут использовать другие стандартные библиотеки, а также пакеты (включая пакет, которому они принадлежат).