Документация Engee

11. Справка по API

В этом разделе описывается функциональный API для взаимодействия с Pkg.jl. Для неинтерактивного использования, например в скриптах, рекомендуется применять функциональный API, а не режим REPL Pkg.

Общая справка по API

Некоторые параметры обычно полезны и могут быть указаны в любом вызове API. Чтобы задать их, используйте именованные аргументы.

Перенаправление вывода

Для перенаправления выводимых данных Pkg используется именованный аргумент io::IOBuffer. Например, Pkg.add("Example"; io=devnull) отбрасывает любой вывод, созданный в результате вызова add.

Справка по API пакетов

В режиме REPL Pkg пакеты (со связанными с ними версией, UUID, URL и т. д.) анализируются как строки, например "Package#master", "Package@v0.1", "www.mypkg.com/MyPkg#my/feature".

В функциональном API строки можно использовать в качестве аргументов для простых команд (например, Pkg.add(["PackageA", "PackageB"])), но для более сложных команд, которые, например, указывают URL-адреса или диапазон версий, требуется использовать более структурированный формат. Для этого создается экземпляр PackageSpec, который передается функциям.

# Pkg.addFunction

Pkg.add(pkg::Union{String, Vector{String}}; preserve=PRESERVE_TIERED, installed=false)
Pkg.add(pkg::Union{PackageSpec, Vector{PackageSpec}}; preserve=PRESERVE_TIERED, installed=false)

Добавляет пакет в текущий проект. Этот пакет будет доступен с помощью ключевых слов import и using в REPL Julia, а если текущий проект является пакетом, то и внутри этого пакета.

Уровни разрешения

Pkg разрешает набор пакетов в вашей среде, используя многоуровневый алгоритм. Именованный аргумент preserve позволяет указать конкретный уровень в алгоритме разрешения. В следующей таблице описаны значения аргументов для preserve (в порядке строгости):

Значение Описание

PRESERVE_ALL_INSTALLED

Аналогично PRESERVE_ALL, и добавляет только те, которые уже установлены

PRESERVE_ALL

Сохраняет состояние всех существующих зависимостей (включая рекурсивные зависимости)

PRESERVE_DIRECT

Сохраняет состояние всех существующих прямых зависимостей

PRESERVE_SEMVER

Сохраняет совместимые с semver версии прямых зависимостей

PRESERVE_NONE

Не сохраняет информацию о версии

PRESERVE_TIERED_INSTALLED

Аналогично PRESERVE_TIERED, за исключением того, что PRESERVE_ALL_INSTALLED будет опробовано первым

PRESERVE_TIERED

Использует уровень, который сохранит наибольший объем информации о версии

и позволит успешно разрешать версии (это значение по умолчанию)

Чтобы изменить стратегию по умолчанию на PRESERVE_TIERED_INSTALLED, задайте переменной среды JULIA_PKG_PRESERVE_TIERED_INSTALLED значение true.

После установки новых пакетов проект будет предварительно скомпилирован. Дополнительные сведения см. в описании pkg> ?precompile.

При использовании стратегии PRESERVE_ALL_INSTALLED новые добавленные пакеты, скорее всего, уже будут предварительно скомпилированы, но если это не так, это может быть связано либо с тем, что сочетание версий пакетов, разрешенных в данной среде, не было разрешено и предварительно скомпилировано ранее, либо кэш предварительной компиляции был удален хранилищем кэша LRU (см. описание JULIA_MAX_NUM_PRECOMPILE_FILES).

Совместимость: Julia 1.9

Для стратегий PRESERVE_TIERED_INSTALLED и PRESERVE_ALL_INSTALLED требуется версия не ниже Julia 1.9.

Примеры

Pkg.add("Example") # Добавление пакета из реестра
Pkg.add("Example"; preserve=Pkg.PRESERVE_ALL) # Добавление пакета `Example` и строгое сохранение существующих зависимостей
Pkg.add(name="Example", version="0.3") # Указание версии; последний выпуск из серии 0.3
Pkg.add(name="Example", version="0.3.1") # Указание версии; точный выпуск
Pkg.add(url="https://github.com/JuliaLang/Example.jl", rev="master") # От url к удаленному репозиторию git
Pkg.add(url="/remote/mycompany/juliapackages/OurPackage") # От пути к локальному репозиторию git
Pkg.add(url="https://github.com/Company/MonoRepo", subdir="juliapkgs/Package.jl)") # С подкаталогом

После установки новых пакетов проект будет предварительно скомпилирован. Дополнительные сведения см. в разделе Предварительная компиляция среды.

См. также описание PackageSpec и Pkg.develop.

# Pkg.developFunction

Pkg.develop(pkg::Union{String, Vector{String}}; io::IO=stderr, preserve=PRESERVE_TIERED, installed=false)
Pkg.develop(pkgs::Union{PackageSpec, Vector{PackageSpec}}; io::IO=stderr, preserve=PRESERVE_TIERED, installed=false)

Делает пакет доступным для разработки, отслеживая его по пути. Если для пакета (pkg) задано только имя или URL-адрес, пакет будет скачан в расположение, указанное переменной среды JULIA_PKG_DEVDIR, при этом joinpath(DEPOT_PATH[1],"dev") будет использоваться по умолчанию.

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

Стратегии сохранения, предлагаемые Pkg.add, также доступны с помощью именованного аргумента preserve. Дополнительные сведения см. в описании Pkg.add.

Примеры

# По имени
Pkg.develop("Example")

# По URL-адресу
Pkg.develop(url="https://github.com/JuliaLang/Compat.jl")

# По пути
Pkg.develop(path="MyJuliaPackages/Package.jl")

См. также описание PackageSpec и Pkg.add.

# Pkg.activateFunction

Pkg.activate([s::String]; shared::Bool=false, io::IO=stderr)
Pkg.activate(; temp::Bool=false, shared::Bool=false, io::IO=stderr)

Активирует среду в s. Активной является среда, которая изменяется при выполнении команд пакета. Логика активации пути следующая.

  • Если shared имеет значение true, активируется первая существующая среда с именем s из хранилищ в стеке хранилищ. Если такая среда не существует, создайте и активируйте ее в первом хранилище.

  • Если temp имеет значение true, будет создана и активирована временная среда, которая будет удалена при выходе из процесса Julia.

  • Если s является существующим путем, будет активирована среда по этому пути.

  • Если s является пакетом в текущем проекте и s отслеживает путь, активируется среда по отслеживаемому пути

  • В противном случае s интерпретируется как несуществующий путь, который затем активируется.

Если аргумент для функции activate не указан, активируется домашний проект. Домашний проект задается либо параметром командной строки --project исполняемого файла Julia, либо переменной среды JULIA_PROJECT.

Примеры

Pkg.activate()
Pkg.activate("local/path")
Pkg.activate("MyDependency")
Pkg.activate(; temp=true)

# Pkg.rmFunction

Pkg.rm(pkg::Union{String, Vector{String}}; mode::PackageMode = PKGMODE_PROJECT)
Pkg.rm(pkg::Union{PackageSpec, Vector{PackageSpec}}; mode::PackageMode = PKGMODE_PROJECT)

Удаляет пакет из текущего проекта. Если mode имеет значение PKGMODE_MANIFEST, также удаляет его из манифеста, включая все рекурсивные зависимости pkg.

См. также описание PackageSpec и PackageMode.

# Pkg.updateFunction

Pkg.update(; level::UpgradeLevel=UPLEVEL_MAJOR, mode::PackageMode = PKGMODE_PROJECT, preserve::PreserveLevel)
Pkg.update(pkg::Union{String, Vector{String}})
Pkg.update(pkg::Union{PackageSpec, Vector{PackageSpec}})

Если позиционные аргументы не указаны, обновляет все пакеты в манифесте, если mode имеет значение PKGMODE_MANIFEST, и пакеты в манифесте и проекте, если mode имеет значение PKGMODE_PROJECT. Если позиционные аргументы не указаны, level можно использовать для управления степенью обновления пакетов (номер основной версии, номер дополнительной версии, исправление, исправленная версия).

Если пакеты заданы в качестве позиционных аргументов, аргумент preserve можно использовать для управления тем, какие другие пакеты разрешено обновлять:

  • PRESERVE_ALL (по умолчанию): разрешено обновлять только pkg.

  • PRESERVE_DIRECT: разрешено обновлять только pkg и косвенные зависимости, которые не являются прямыми зависимостями в проекте.

  • PRESERVE_NONE: разрешено обновлять pkg и все его косвенные зависимости.

После обновления пакетов проект будет предварительно скомпилирован. Дополнительные сведения см. в разделе Предварительная компиляция среды.

См. также описание PackageSpec, PackageMode и UpgradeLevel.

# Pkg.testFunction

Pkg.test(; kwargs...)
Pkg.test(pkg::Union{String, Vector{String}; kwargs...)
Pkg.test(pkgs::Union{PackageSpec, Vector{PackageSpec}}; kwargs...)

Именованные аргументы

  • coverage::Bool=false: включить или отключить генерацию статистики охвата.

  • allow_reresolve::Bool=true: разрешить Pkg повторно разрешать версии пакетов в тестовой среде.

  • julia_args::Union{Cmd, Vector{String}}: параметры, которые будут переданы процессу тестирования.

  • test_args::Union{Cmd, Vector{String}}: тестовые аргументы (ARGS), доступные в процессе тестирования.

Совместимость: Julia 1.9

Для allow_reresolve требуется версия не ниже Julia 1.9.

Запускает тесты для пакета pkg или текущего проекта (который, таким образом, должен быть пакетом), если позиционные аргументы для Pkg.test не заданы. Для тестирования пакета выполняется его файл test/runtests.jl.

Тесты запускаются путем создания временной среды, содержащей только пакет pkg и его (рекурсивные) зависимости. Если существует файл манифеста и именованный аргумент allow_reresolve имеет значение false, используются версии, содержащиеся в файле манифеста. В противном случае будет разрешен и установлен подходящий набор пакетов.

Во время тестирования активны зависимости, характерные для теста, которые указаны в файле проекта, например следующим образом:

[extras]
Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"

[targets]
test = ["Test"]

Тесты выполняются в новом процессе при check-bounds=yes и по умолчанию startup-file=no. Если вы хотите использовать файл запуска (~/.julia/config/startup.jl), запустите Julia с --startup-file=yes. Встраивание функций во время тестирования можно отключить (для повышения точности охвата), запустив Julia с --inline=no.

# Pkg.buildFunction

Pkg.build(; verbose = false, io::IO=stderr)
Pkg.build(pkg::Union{String, Vector{String}}; verbose = false, io::IO=stderr)
Pkg.build(pkgs::Union{PackageSpec, Vector{PackageSpec}}; verbose = false, io::IO=stderr)

Выполняет скрипт сборки в deps/build.jl для pkg и всех его зависимостей в порядке рекурсии в глубину. Если аргумент для функции build не указан, собирается текущий проект, который, таким образом, должен быть пакетом. Эта функция вызывается автоматически для любого пакета, устанавливаемого в первый раз. verbose = true выводит выходные данные сборки в stdout/stderr вместо перенаправления в файл build.log.

# Pkg.pinFunction

Pkg.pin(pkg::Union{String, Vector{String}}; io::IO=stderr, all_pkgs::Bool=false)
Pkg.pin(pkgs::Union{PackageSpec, Vector{PackageSpec}}; io::IO=stderr, all_pkgs::Bool=false)

Закрепляет пакет в текущей версии (или заданной в PackageSpec) или в определенной редакции git. Закрепленный пакет никогда не обновляется автоматически: если pkg отслеживает путь, или репозиторий, они остаются отслеживаемыми, но не обновляются. Чтобы получить обновления из исходного пути или удаленного хранилища, пакет необходимо сначала освободить.

Совместимость: Julia 1.7

Именованный аргумент all_pkgs появился в версии Julia 1.7.

Примеры

Pkg.pin("Example")
Pkg.pin(name="Example", version="0.3.1")
Pkg.pin(all_pkgs = true)

# Pkg.freeFunction

Pkg.free(pkg::Union{String, Vector{String}}; io::IO=stderr, all_pkgs::Bool=false)
Pkg.free(pkgs::Union{PackageSpec, Vector{PackageSpec}}; io::IO=stderr, all_pkgs::Bool=false)

Если pkg закреплен, удалите закрепление. Если pkg отслеживает путь, например после Pkg.develop, вернитесь к отслеживанию зарегистрированных версий. Чтобы освободить все зависимости, задайте all_pkgs=true.

Совместимость: Julia 1.7

Именованный аргумент all_pkgs появился в версии Julia 1.7.

Примеры

Pkg.free("Package")
Pkg.free(all_pkgs = true)

# Pkg.instantiateFunction

Pkg.instantiate(; verbose = false, io::IO=stderr)

Если файл Manifest.toml существует в активном проекте, скачивает все пакеты, объявленные в этом манифесте. В противном случае разрешает набор подходящих пакетов из файлов Project.toml и устанавливает их. verbose = true выводит выходные данные сборки в stdout/stderr вместо перенаправления в файл build.log. Если файл Project.toml не существует в текущем активном проекте, создает его со всеми зависимостями в манифесте и создает экземпляр итогового проекта.

После установки пакетов проект будет предварительно скомпилирован. Дополнительные сведения см. в разделе Предварительная компиляция среды.

# Pkg.resolveFunction

Pkg.resolve(; io::IO=stderr)

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

# Pkg.gcFunction

Pkg.gc(; collect_delay::Period=Day(7), io::IO=stderr)

Собирает в мусор установки пакетов и артефактов, просматривая все известные файлы Manifest.toml и Artifacts.toml, отмечая те, которые были удалены, а затем находя артефакты и пакеты, которые после этого не использовались никакими другими проектами, помечая их как «заброшенные». Этот метод удаляет только те ставшие ненужными объекты (версии пакетов, артефакты и вспомогательные пространства), которые непрерывно не использовались в течение периода collect_delay, по умолчанию составляющим семь дней.

# Pkg.statusFunction

Pkg.status([pkgs...]; outdated::Bool=false, mode::PackageMode=PKGMODE_PROJECT, diff::Bool=false, compat::Bool=false, extensions::Bool=false, io::IO=stdout)

Выводит состояние проекта или манифеста.

Пакеты, отмеченные символом , имеют новые версии, которые могут быть установлены, например, с помощью Pkg.up. Те, что отмечены символом , имеют новые версии, но не могут быть установлены из-за конфликтов совместимости с другими пакетами. Чтобы узнать причину, задайте именованный аргумент outdated=true.

При задании outdated=true будут отображены только пакеты, которые не имеют последней версии, будет показана их максимальная версия и причины, по которым они не имеют последней версии (либо из-за того, что другие пакеты удерживают их в связи с ограничениями совместимости, либо из-за совместимости в файле проекта). Например, вывод состояния следующего вида

pkg> Pkg.status(; outdated=true)
Status `Manifest.toml`
⌃ [a8cc5b0e] Crayons v2.0.0 [<v3.0.0], (<v4.0.4)
⌅ [b8a86587] NearestNeighbors v0.4.8 (<v0.4.9) [compat]
⌅ [2ab3a3ac] LogExpFunctions v0.2.5 (<v0.3.0): SpecialFunctions

означает, что последней версией Crayons является 4.0.4, но последняя версия, совместимая с разделом [compat] в текущем проекте, — это 3.0.0. Последняя версия NearestNeighbors — 0.4.9, но из-за ограничений совместимости в проекте она осталась на уровне 0.4.8. Последней версией LogExpFunctions является 0.3.0, но из-за SpecialFunctions она остается на уровне 0.2.5.

Если mode имеет значение PKGMODE_PROJECT, выводит состояние только для пакетов, которые находятся в проекте (добавлены явным образом). Если mode имеет значение PKGMODE_MANIFEST, выводит состояние и для тех, которые находятся в манифесте (рекурсивные зависимости). Если есть пакеты, указанные как аргументы, в выводе будут приведены именно они.

При задании ext=true будут отображены зависимости с расширениями и зависимости расширений тех, которые загружены в данный момент.

Если среда находится в репозитории git, при задании diff=true будут выведена разница по сравнению с последней фиксацией git.

См. описание Pkg.project и Pkg.dependencies со сведениями о получении состояния проекта или манифеста в виде объекта Julia вместо его вывода.

Совместимость: Julia 1.8

Индикаторы и были добавлены в Julia 1.8. Для использования именованного аргумента outdated требуется версия Julia не ниже 1.8.

# Pkg.compatFunction

Pkg.compat()

Интерактивно редактирует записи [compat] в текущем проекте.

Pkg.compat(pkg::String, compat::String)

Задает строку [compat] для данного пакета в текущем проекте.

Более подробные сведения см. в разделе Совместимость.

# Pkg.precompileFunction

Pkg.precompile(; strict::Bool=false, timing::Bool=false)
Pkg.precompile(pkg; strict::Bool=false, timing::Bool=false)
Pkg.precompile(pkgs; strict::Bool=false, timing::Bool=false)

Параллельно предварительно компилирует все или определенные зависимости проекта.

Задайте timing=true, чтобы показать продолжительность предварительной компиляции каждой зависимости.

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

Этот метод вызывается автоматически после любого действия Pkg, изменяющего манифест. Все пакеты, в которых ранее возникала ошибка во время предварительной компиляции, не будут повторно компилироваться в автоматическом режиме до тех пор, пока не будут изменены. Чтобы отключить автоматическую предварительную компиляцию, задайте ENV["JULIA_PKG_PRECOMPILE_AUTO"]=0. Чтобы вручную контролировать количество используемых заданий, задайте ENV["JULIA_NUM_PRECOMPILE_TASKS"].

Совместимость: Julia 1.8

Для указания пакетов, подлежащих предварительной компиляции, требуется версия не ниже Julia 1.8.

Совместимость: Julia 1.9

Для временного режима требуется версия не ниже Julia 1.9.

Примеры

Pkg.precompile()
Pkg.precompile("Foo")
Pkg.precompile(["Foo", "Bar"])

# Pkg.offlineFunction

Pkg.offline(b::Bool=true)

Включает (b=true) или отключает (b=false) автономный режим.

В автономном режиме Pkg пытается выполнить как можно больше задач без подключения к Интернету. Например, при добавлении пакета Pkg учитывает только те версии, которые уже скачаны в разрешении версий.

Чтобы работать в автономном режиме во всех сеансах Julia, задайте переменной среды JULIA_PKG_OFFLINE значение "true".

# Pkg.whyFunction

Pkg.why(pkg::Union{String, Vector{String}})
Pkg.why(pkg::Union{PackageSpec, Vector{PackageSpec}})

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

Совместимость: Julia 1.9

Для этой функции требуется версия Julia не ниже 1.9.

# Pkg.dependenciesFunction

Pkg.dependencies()::Dict{UUID, PackageInfo}

Эта функция пока имеет экспериментальный характер.

Запрашивает граф зависимостей активного проекта. Результатом является Dict, который сопоставляет UUID пакета со структурой PackageInfo, представляющей зависимость (пакет).

Поля PackageInfo

Поле Описание

name

Имя пакета

version

Версия пакета (Nothing для стандартных библиотек)

tree_hash

Хэш файла дерева каталогов пакетов

is_direct_dep

Пакет является прямой зависимостью

is_pinned

Закреплен ли пакет

is_tracking_path

Отслеживает ли пакет путь

is_tracking_repo

Отслеживает ли пакет репозиторий

is_tracking_registry

Отслеживается ли пакет по реестру, т. е. не по пути и не по хранилищу

git_revision

Редакция git при отслеживании по репозиторию

git_source

Источник git при отслеживании по репозиторию

source

Каталог, содержащий исходный код этого пакета

dependencies

Зависимости этого пакета в виде вектора идентификаторов UUID

# Pkg.respect_sysimage_versionsFunction

Pkg.respect_sysimage_versions(b::Bool=true)

Включает (b=true) или отключает (b=false) соблюдение версий, которые находятся в системном образе (по умолчанию включено).

Если этот параметр включен, Pkg будет устанавливать только те пакеты, которые были помещены в системный образ (например, с помощью PackageCompiler) с версией пакета в системном образе. Кроме того, при попытке добавить пакет по URL-адресу или разработать (develop) пакет, который находится в системном образе, возникнет ошибка.

# Pkg.projectFunction

Pkg.project()::ProjectInfo

Эта функция пока имеет экспериментальный характер.

Запрашивает структуру ProjectInfo, которая содержит информацию об активном проекте.

Поля ProjectInfo

Поле Описание

name

Имя проекта

uuid

Идентификатор UUID проекта

version

Версия проекта

ispackage

Является ли проект пакетом (имеет имя и uuid)

dependencies

Прямые зависимости проекта в виде Dict, который сопоставляет имя зависимости с UUID зависимости

path

Расположение файла проекта, определяющего активный проект

# Pkg.undoFunction

undo()

Отменяет последнее изменение активного проекта. Сохраняются только состояния в текущем сеансе, максимум 50 состояний.

См. также: redo.

# Pkg.redoFunction

redo()

Возвращает изменения с последней отмены (undo).

# Pkg.setprotocol!Function

setprotocol!(;
    domain::AbstractString = "github.com",
    protocol::Union{Nothing, AbstractString}=nothing
)

Задает протокол, используемый для доступа к размещенным пакетам при добавлении (add) URL-адреса или разработке (develop) пакета. По умолчанию выбор делегируется разработчику пакета (protocol === nothing). Другими вариантами для protocol являются "https" или "git".

Примеры

julia> Pkg.setprotocol!(domain = "github.com", protocol = "ssh")

julia> Pkg.setprotocol!(domain = "gitlab.mycompany.com")

# Pkg.PackageSpecType

PackageSpec(name::String, [uuid::UUID, version::VersionNumber])
PackageSpec(; name, url, path, subdir, rev, version, mode, level)

A PackageSpec is a representation of a package with various metadata. This includes:

  • The name of the package.

  • The package’s unique uuid.

  • A version (for example when adding a package). When upgrading, can also be an instance of the enum UpgradeLevel. If the version is given as a String this means that unspecified versions are "free", for example version="0.5" allows any version 0.5.x to be installed. If given as a VersionNumber, the exact version is used, for example version=v"0.5.3".

  • A url and an optional git revision. rev can be a branch name or a git commit SHA1.

  • A local path. This is equivalent to using the url argument but can be more descriptive.

  • A subdir which can be used when adding a package that is not in the root of a repository.

Most functions in Pkg take a Vector of PackageSpec and do the operation on all the packages in the vector.

Many functions that take a PackageSpec or a Vector{PackageSpec} can be called with a more concise notation with NamedTuples. For example, Pkg.add can be called either as the explicit or concise versions as:

Explicit Concise

Pkg.add(PackageSpec(name="Package"))

Pkg.add(name = "Package")

Pkg.add(PackageSpec(url="www.myhost.com/MyPkg")))

Pkg.add(name = "Package")

Pkg.add([PackageSpec(name="Package"), PackageSpec(path="/MyPkg"])

Pkg.add([(;name="Package"), (;path="MyPkg")])

Below is a comparison between the REPL mode and the functional API:

REPL API

Package

PackageSpec("Package")

Package@0.2

PackageSpec(name="Package", version="0.2")

-

PackageSpec(name="Package", version=v"0.2.1")

Package=a67d...

PackageSpec(name="Package", uuid="a67d...")

Package#master

PackageSpec(name="Package", rev="master")

local/path#feature

PackageSpec(path="local/path"; rev="feature")

www.mypkg.com

PackageSpec(url="www.mypkg.com")

--major Package

PackageSpec(name="Package", version=UPLEVEL_MAJOR)

# Pkg.PackageModeType

PackageMode

An enum with the instances

  • PKGMODE_MANIFEST

  • PKGMODE_PROJECT

Determines if operations should be made on a project or manifest level. Used as an argument to Pkg.rm, Pkg.update and Pkg.status.

# Pkg.UpgradeLevelType

UpgradeLevel

An enum with the instances

  • UPLEVEL_FIXED

  • UPLEVEL_PATCH

  • UPLEVEL_MINOR

  • UPLEVEL_MAJOR

Determines how much a package is allowed to be updated. Used as an argument to PackageSpec or as an argument to Pkg.update.

Справка по API реестров

Функциональный API для реестров использует RegistrySpec аналогично PackageSpec.

# Pkg.RegistrySpecType

RegistrySpec(name::String)
RegistrySpec(; name, url, path)

A RegistrySpec is a representation of a registry with various metadata, much like PackageSpec.

Most registry functions in Pkg take a Vector of RegistrySpec and do the operation on all the registries in the vector.

Examples

Below is a comparison between the REPL mode and the functional API
REPL API

MyRegistry

RegistrySpec("MyRegistry")

MyRegistry=a67d...

RegistrySpec(name="MyRegistry", uuid="a67d...")

local/path

RegistrySpec(path="local/path")

www.myregistry.com

RegistrySpec(url="www.myregistry.com")

# Pkg.Registry.addFunction

Pkg.Registry.add(registry::RegistrySpec)

Добавляет новые реестры пакетов.

Функция Pkg.Registry.add() без аргументов установит реестры по умолчанию.

Примеры

Pkg.Registry.add("General")
Pkg.Registry.add(RegistrySpec(uuid = "23338594-aafe-5451-b93e-139f81909106"))
Pkg.Registry.add(RegistrySpec(url = "https://github.com/JuliaRegistries/General.git"))

# Pkg.Registry.rmFunction

Pkg.Registry.rm(registry::String)
Pkg.Registry.rm(registry::RegistrySpec)

Удаляет реестры.

Примеры

Pkg.Registry.rm("General")
Pkg.Registry.rm(RegistrySpec(uuid = "23338594-aafe-5451-b93e-139f81909106"))

# Pkg.Registry.updateFunction

Pkg.Registry.update()
Pkg.Registry.update(registry::RegistrySpec)
Pkg.Registry.update(registry::Vector{RegistrySpec})

Обновляет реестры. Если реестры не заданы, обновляет все доступные реестры.

Примеры

Pkg.Registry.update()
Pkg.Registry.update("General")
Pkg.Registry.update(RegistrySpec(uuid = "23338594-aafe-5451-b93e-139f81909106"))

# Pkg.Registry.statusFunction

Pkg.Registry.status()

Отображает сведения о доступных реестрах.

Примеры

Pkg.Registry.status()

Справка по API артефактов

# Pkg.Artifacts.create_artifactFunction

create_artifact(f::Function)

Создает новый артефакт, выполняя f(artifact_path), хэшируя результат и перемещая его в хранилище артефактов (~/.julia/artifacts в стандартной установке). Возвращает идентификационный хэш дерева данного артефакта.

# Pkg.Artifacts.remove_artifactFunction

remove_artifact(hash::SHA1; honor_overrides::Bool=false)

Удаляет заданный артефакт (идентифицируемый по хэшу git-дерева SHA1) с диска. Обратите внимание, что если артефакт установлен в нескольких хранилищах, он будет удален из всех. Если переопределенный артефакт запрашивается для удаления, он будет проигнорирован. Этот метод никогда не будет пытаться удалить переопределенный артефакт.

В общем, рекомендуется использовать Pkg.gc() для управления установкой артефактов и не использовать remove_artifact() напрямую, поскольку бывает сложно определить, используется ли артефакт другим пакетом.

# Pkg.Artifacts.verify_artifactFunction

verify_artifact(hash::SHA1; honor_overrides::Bool=false)

Проверяет, что заданный артефакт (идентифицируемый по хэшу git-дерева SHA1) установлен на диске, и обеспечивает его целостность. Если заданный артефакт переопределен, пропускает проверку, пока для honor_overrides не будет задано значение true.

# Pkg.Artifacts.bind_artifact!Function

bind_artifact!(artifacts_toml::String, name::String, hash::SHA1;
               platform::Union{AbstractPlatform,Nothing} = nothing,
               download_info::Union{Vector{Tuple},Nothing} = nothing,
               lazy::Bool = false,
               force::Bool = false)

Записывает сопоставление name с hash в заданном файле (Julia)Artifacts.toml. Если platform имеет значение, отличное от nothing, артефакт помечается как характерный для платформы и будет представлять собой множественное сопоставление. Можно привязать несколько артефактов с одинаковым именем, но разными платформами (platform) и хэшами (hash) в одном файле artifacts_toml. Если force имеет значение true, уже существующее отображение будет переопределено; в противном случае возникнет ошибка.

download_info является необязательным вектором, содержащим кортежи URL-адресов и хэш. Эти URL-адреса будут указаны в качестве возможных расположений, где можно получить этот артефакт. Если lazy имеет значение true, даже если информация о скачивании доступна, этот артефакт не будет скачан, пока к нему не будет предоставлен доступ с помощью синтаксиса artifact"name" или пока для него не будет вызвана функция ensure_artifact_installed().

# Pkg.Artifacts.unbind_artifact!Function

unbind_artifact!(artifacts_toml::String, name::String; platform = nothing)

Отменяет привязку заданного имени (name) от файла (Julia)Artifacts.toml. Завершается сбоем, если в файле не существует такой привязки.

# Pkg.Artifacts.download_artifactFunction

download_artifact(tree_hash::SHA1, tarball_url::String, tarball_hash::String;
                  verbose::Bool = false, io::IO=stderr)

Скачивает или устанавливает артефакт в хранилище артефактов. Возвращает true при успешном выполнении, возвращает объект ошибки в случае неудачи.

Совместимость: Julia 1.8

Начиная с Julia версии 1.8 эта функция возвращает объект ошибки, а не false в случае неудачи.

# Pkg.Artifacts.ensure_artifact_installedFunction

ensure_artifact_installed(name::String, artifacts_toml::String;
                          platform::AbstractPlatform = HostPlatform(),
                          pkg_uuid::Union{Base.UUID,Nothing}=nothing,
                          verbose::Bool = false,
                          quiet_download::Bool = false,
                          io::IO=stderr)

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

# Pkg.Artifacts.ensure_all_artifacts_installedFunction

ensure_all_artifacts_installed(artifacts_toml::String;
                               platform = HostPlatform(),
                               pkg_uuid = nothing,
                               include_lazy = false,
                               verbose = false,
                               quiet_download = false,
                               io::IO=stderr)

Устанавливает все неленивые артефакты из заданного файла (Julia)Artifacts.toml. Необходимо указать package_uuid для правильной поддержки переопределений из записей Overrides.toml в хранилищах.

Если include_lazy имеет значение true, также будут установлены ленивые пакеты.

Эта функция устарела и должна быть заменена следующим фрагментом:

artifacts = select_downloadable_artifacts(artifacts_toml; platform, include_lazy)
for name in keys(artifacts)
    ensure_artifact_installed(name, artifacts[name], artifacts_toml; platform=platform)
end

Эта функция устарела в Julia 1.6 и будет удалена в будущей версии. Вместо нее используйте select_downloadable_artifacts() и ensure_artifact_installed().

# Pkg.Artifacts.archive_artifactFunction

archive_artifact(hash::SHA1, tarball_path::String; honor_overrides::Bool=false)

Архивирует артефакт в tar-архив, хранящийся в tarball_path, возвращает SHA256 результирующего tar-архива в виде шестнадцатеричной строки. Выдает ошибку, если артефакт не существует. Если артефакт переопределен, выдает ошибку, пока не будет задана функция honor_overrides.