10. API Reference
This section describes the function interface, or "API mode" for interacting with Pkg.jl. The function API is recommended for non-interactive usage, in i.e. scripts.
Package API Reference
In the REPL mode packages (with associated version, UUID, URL etc) are parsed from strings, for example, "Package#master"
,"Package@v0.1"
, "www.mypkg.com/MyPkg#my/feature"
. It is possible to use strings as arguments for simple commands in the API mode (like Pkg.add(["PackageA", "PackageB"])
, more complicated commands, that e.g. specify URLs or version range, uses a more structured format over strings. This is done by creating an instance of a PackageSpec
which are passed in to functions.
Pkg.PackageSpec
— Function.PackageSpec(name::String, [uuid::UUID, version::VersionNumber])
PackageSpec(; name, url, path, rev, version, mode, level)
A PackageSpec
is a representation of a package with various metadata. This includes:
- The
name
of the package. - The package unique
uuid
. - A
version
(for example when adding a package. When upgrading, can also be an instance of
the enum UpgradeLevel
- A
url
and an optional gitrev
ision.rev
could be a branch name or a git commit SHA. - A local path
path
. This is equivalent to using theurl
argument but can be more descriptive. - A
mode
, which is an instance of the enumPackageMode
which can be eitherPKGMODE_PROJECT
or
PKGMODE_MANIFEST
, defaults to PKGMODE_PROJECT
. Used in e.g. Pkg.rm
.
Most functions in Pkg take a Vector
of PackageSpec
and do the operation on all the packages in the vector.
Below is a comparison between the REPL version and the PackageSpec
version:
REPL | API |
---|---|
Package | PackageSpec("Package") |
Package@0.2 | PackageSpec(name="Package", version="0.2") |
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") |
--manifest Package | PackageSpec(name="Package", mode=PKGSPEC_MANIFEST) |
--major Package | PackageSpec(name="Package", version=PKGLEVEL_MAJOR) |
Pkg.PackageMode
— Type.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 PackageSpec
or as an argument to Pkg.rm
.
Pkg.UpgradeLevel
— Type.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
.
Pkg.add
— Function.Pkg.add(pkg::Union{String, Vector{String}})
Pkg.add(pkg::Union{PackageSpec, Vector{PackageSpec}})
Add a package to the current project. This package will be available using the import
and using
keywords in the Julia REPL and if the current project is a package, also inside that package.
Examples
Pkg.add("Example") # Add a package from registry
Pkg.add(PackageSpec(name="Example", version="0.3")) # Specify version
Pkg.add(PackageSpec(url="https://github.com/JuliaLang/Example.jl", rev="master")) # From url to remote gitrepo
Pkg.add(PackageSpec(url="/remote/mycompany/juliapackages/OurPackage"))` # From path to local gitrepo
See also PackageSpec
.
Pkg.develop
— Function.Pkg.develop(pkg::Union{String, Vector{String}})
Pkg.develop(pkgs::Union{Packagespec, Vector{Packagespec}})
Make a package available for development by tracking it by path. If pkg
is given with only a name or by a URL the packages will be downloaded to the location by the environment variable JULIA_PKG_DEVDIR
with .julia/dev
as the default.
If pkg
is given as a local path, the package at that path will be tracked.
Examples
# By name
Pkg.develop("Example")
# By url
Pkg.develop(PackageSpec(url="https://github.com/JuliaLang/Compat.jl"))
# By path
Pkg.develop(PackageSpec(path="MyJuliaPackages/Package.jl"))
See also PackageSpec
Pkg.activate
— Function.Pkg.activate([s::String]; shared::Bool=false)
Activate the environment at s
. The active environment is the environment that is modified by executing package commands. The logic for what path is activated is as follows:
- If
shared
istrue
, the first existing environment nameds
from the depots in the depot stack will be activated. If no such environment exists, create and activate that environment in the first depot. - If
s
is an existing path, then activate the environment at that path. - If
s
is a package in the current project ands
is tracking a path, then activate the environment at the tracked path. - Else,
s
is interpreted as a non-existing path, activate that path.
If no argument is given to activate
, then activate the home project. The home project is specified by either the --project
command line option to the julia executable, or the JULIA_PROJECT
environment variable.
Examples
Pkg.activate()
Pkg.activate("local/path")
Pkg.activate("MyDependency")
Pkg.rm
— Function.Pkg.rm(pkg::Union{String, Vector{String}})
Pkg.rm(pkg::Union{PackageSpec, Vector{PackageSpec}})
Remove a package from the current project. If the mode
of pkg
is PKGMODE_MANIFEST
also remove it from the manifest including all recursive dependencies of pkg
.
See also PackageSpec
, PackageMode
.
Pkg.update
— Function.Pkg.update(; level::UpgradeLevel=UPLEVEL_MAJOR, mode::PackageMode = PKGMODE_PROJECT)
Pkg.update(pkg::Union{String, Vector{String}})
Pkg.update(pkg::Union{PackageSpec, Vector{PackageSpec}})
Update a package pkg
. If no posistional argument is given, update all packages in the manifest if mode
is PKGMODE_MANIFEST
and packages in both manifest and project if mode
is PKGMODE_PROJECT
. If no positional argument is given level
can be used to control what how much packages are allowed to be upgraded (major, minor, patch, fixed).
See also PackageSpec
, PackageMode
, UpgradeLevel
.
Pkg.test
— Function.Pkg.test(; coverage::Bool=false)
Pkg.test(pkg::Union{String, Vector{String}; coverage::Bool=false)
Pkg.test(pkgs::Union{PackageSpec, Vector{PackageSpec}}; coverage::Bool=false)
Run the tests for package pkg
or if no positional argument is given to test
, the current project is tested (which thus needs to be a package). A package is tested by running its test/runtests.jl
file.
The tests are run by generating a temporary environment with only pkg
and its (recursive) dependencies (recursively) in it. If a manifest exist, the versions in that manifest is used, otherwise a feasible set of package are resolved and installed.
During the test, test-specific dependencies are active, which are given in the project file as e.g.
[extras]
Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
[targets]
test = ["Test"]
Coverage statistics for the packages may be generated by passing coverage=true
. The default behavior is not to run coverage.
The tests are executed in a new process with check-bounds=yes
and by default startup-file=no
. If using the startup file (~/.julia/config/startup.jl
) is desired, start julia with --startup-file=yes
. Inlining of functions during testing can be disabled (for better coverage accuracy) by starting julia with --inline=no
.
Pkg.build
— Function.Pkg.build(; verbose = false)
Pkg.build(pkg::Union{String, Vector{String}}; verbose = false)
Pkg.build(pkgs::Union{PackageSpec, Vector{PackageSpec}}; verbose = false)
Run the build script in deps/build.jl
for pkg
and all of the dependencies in depth-first recursive order. If no argument is given to build
, the current project is built, which thus needs to be a package. This function is called automatically one any package that gets installed for the first time. verbose = true
prints the build output to stdout
/stderr
instead of redirecting to the build.log
file.
Pkg.pin
— Function.Pkg.pin(pkg::Union{String, Vector{String}})
Pkg.pin(pkgs::Union{Packagespec, Vector{Packagespec}})
Pin a package to the current version (or the one given in the packagespec
or a certain git revision. A pinned package is never updated.
Pkg.free
— Function.Pkg.free(pkg::Union{String, Vector{String}})
Pkg.free(pkgs::Union{Packagespec, Vector{Packagespec}})
Free a package which removes a pin
if it exists, or if the package is tracking a path, e.g. after Pkg.develop
, go back to tracking registered versions.
Examples
Pkg.free("Package")
Pkg.free(PackageSpec("Package"))
Pkg.instantiate
— Function.Pkg.instantiate()
If a Manifest.toml
file exist in the current project, download all the packages declared in that manifest. Else, resolve a set of feasible packages from the Project.toml
files and install them.
Pkg.resolve
— Function.Pkg.resolve()
Update the current manifest with eventual changes to the dependency graph from packages that are tracking a path.
Pkg.gc
— Function.Pkg.gc()
Garbage collect packages that are no longer reachable from any project. Only packages that are tracked by version are deleted, so no packages that might contain local changes are touched.
Pkg.status
— Function.Pkg.status([pkgs...]; mode::PackageMode=PKGMODE_PROJECT)
Print out the status of the project/manifest. If mode
is PKGMODE_PROJECT
prints out status about only those packages that are in the project (explicitly added). If mode
is PKGMODE_MANIFEST
also print for those in the manifest (recursive dependencies). If there are any packages listed as arguments the output will be limited to those packages.
Pkg.status
with package arguments requires at least Julia 1.1.
Pkg.setprotocol!
— Function.Pkg.setprotocol!(proto::Union{Nothing, AbstractString}=nothing)
Set the protocol used to access GitHub-hosted packages when add
ing a url or develop
ing a package. Defaults to delegating the choice to the package developer (proto == nothing
). Other choices for proto
are "https"
or "git"
.
Registry API Reference
Pkg's registry handling requires at least Julia 1.1.
The function API for registries uses RegistrySpec
s, similar to PackageSpec
.
Pkg.RegistrySpec
— Type.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.
Pkg's registry handling requires at least Julia 1.1.
Examples
Below is a comparison between the REPL version and the RegistrySpec
version:
REPL | API |
---|---|
Registry | RegistrySpec("Registry") |
Registry=a67d... | RegistrySpec(name="Registry", uuid="a67d...") |
local/path | RegistrySpec(path="local/path") |
www.myregistry.com | RegistrySpec(url="www.myregistry.com") |
Pkg.Registry.add
— Function.Pkg.Registry.add(url::String)
Pkg.Registry.add(registry::RegistrySpec)
Add new package registries.
Pkg's registry handling requires at least Julia 1.1.
Examples
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.rm
— Function.Pkg.Registry.rm(registry::String)
Pkg.Registry.rm(registry::RegistrySpec)
Remove registries.
Pkg's registry handling requires at least Julia 1.1.
Examples
Pkg.Registry.rm("General")
Pkg.Registry.rm(RegistrySpec(uuid = "23338594-aafe-5451-b93e-139f81909106"))
Pkg.Registry.update
— Function.Pkg.Registry.update()
Pkg.Registry.update(registry::RegistrySpec)
Pkg.Registry.update(registry::Vector{RegistrySpec})
Update registries. If no registries are given, update all available registries.
Pkg's registry handling requires at least Julia 1.1.
Examples
Pkg.Registry.update()
Pkg.Registry.update("General")
Pkg.Registry.update(RegistrySpec(uuid = "23338594-aafe-5451-b93e-139f81909106"))
Pkg.Registry.status
— Function.Pkg.Registry.status()
Display information about available registries.
Pkg's registry handling requires at least Julia 1.1.
Examples
Pkg.Registry.status()