diff --git a/dev/api/index.html b/dev/api/index.html index cd6f3878fc..b6b778f4fb 100644 --- a/dev/api/index.html +++ b/dev/api/index.html @@ -6,7 +6,7 @@ Pkg.add(name="Example", version="0.3.1") # Specify version; exact release Pkg.add(url="https://github.com/JuliaLang/Example.jl", rev="master") # From url to remote gitrepo Pkg.add(url="/remote/mycompany/juliapackages/OurPackage") # From path to local gitrepo -Pkg.add(url="https://github.com/Company/MonoRepo", subdir="juliapkgs/Package.jl)") # With subdir

After the installation of new packages the project will be precompiled. See more at Environment Precompilation.

See also PackageSpec, Pkg.develop.

source
Pkg.develop — Function
Pkg.develop(pkg::Union{String, Vector{String}}; io::IO=stderr, preserve=PRESERVE_TIERED, installed=false)
+Pkg.add(url="https://github.com/Company/MonoRepo", subdir="juliapkgs/Package.jl)") # With subdir

After the installation of new packages the project will be precompiled. See more at Environment Precompilation.

See also PackageSpec, Pkg.develop.

source
Pkg.develop — Function
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)

Make a package available for development by tracking it by path. If pkg is given with only a name or by a URL, the package will be downloaded to the location specified by the environment variable JULIA_PKG_DEVDIR, with joinpath(DEPOT_PATH[1],"dev") being the default.

If pkg is given as a local path, the package at that path will be tracked.

The preserve strategies offered by Pkg.add are also available via the preserve kwarg. See Pkg.add for more information.

Examples

# By name
 Pkg.develop("Example")
 
@@ -14,61 +14,61 @@
 Pkg.develop(url="https://github.com/JuliaLang/Compat.jl")
 
 # By path
-Pkg.develop(path="MyJuliaPackages/Package.jl")

See also PackageSpec, Pkg.add.

source
Pkg.activate — Function
Pkg.activate([s::String]; shared::Bool=false, io::IO=stderr)
+Pkg.develop(path="MyJuliaPackages/Package.jl")

See also PackageSpec, Pkg.add.

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

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 is true, the first existing environment named s 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 temp is true this will create and activate a temporary environment which will be deleted when the julia process is exited.
  • If s is an existing path, then activate the environment at that path.
  • If s is a package in the current project and s is tracking a path, then activate the environment at the tracked path.
  • Otherwise, s is interpreted as a non-existing path, which is then activated.

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.activate(; temp=true)
source
Pkg.rm — Function
Pkg.rm(pkg::Union{String, Vector{String}}; mode::PackageMode = PKGMODE_PROJECT)
-Pkg.rm(pkg::Union{PackageSpec, Vector{PackageSpec}}; mode::PackageMode = PKGMODE_PROJECT)

Remove a package from the current project. If mode is equal to PKGMODE_MANIFEST also remove it from the manifest including all recursive dependencies of pkg.

See also PackageSpec, PackageMode.

source
Pkg.update — Function
Pkg.update(; level::UpgradeLevel=UPLEVEL_MAJOR, mode::PackageMode = PKGMODE_PROJECT, preserve::PreserveLevel)
+Pkg.activate(; temp=true)
source
Pkg.rm — Function
Pkg.rm(pkg::Union{String, Vector{String}}; mode::PackageMode = PKGMODE_PROJECT)
+Pkg.rm(pkg::Union{PackageSpec, Vector{PackageSpec}}; mode::PackageMode = PKGMODE_PROJECT)

Remove a package from the current project. If mode is equal to PKGMODE_MANIFEST also remove it from the manifest including all recursive dependencies of pkg.

See also PackageSpec, PackageMode.

source
Pkg.update — Function
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}})

If no positional 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 by how much packages are allowed to be upgraded (major, minor, patch, fixed).

If packages are given as positional arguments, the preserve argument can be used to control what other packages are allowed to update:

  • PRESERVE_ALL (default): Only allow pkg to update.
  • PRESERVE_DIRECT: Only allow pkg and indirect dependencies that are not a direct dependency in the project to update.
  • PRESERVE_NONE: Allow pkg and all its indirect dependencies to update.

After any package updates the project will be precompiled. See more at Environment Precompilation.

See also PackageSpec, PackageMode, UpgradeLevel.

source
Pkg.test — Function
Pkg.test(; kwargs...)
+Pkg.update(pkg::Union{PackageSpec, Vector{PackageSpec}})

If no positional 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 by how much packages are allowed to be upgraded (major, minor, patch, fixed).

If packages are given as positional arguments, the preserve argument can be used to control what other packages are allowed to update:

  • PRESERVE_ALL (default): Only allow pkg to update.
  • PRESERVE_DIRECT: Only allow pkg and indirect dependencies that are not a direct dependency in the project to update.
  • PRESERVE_NONE: Allow pkg and all its indirect dependencies to update.

After any package updates the project will be precompiled. See more at Environment Precompilation.

See also PackageSpec, PackageMode, UpgradeLevel.

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

Keyword arguments:

  • coverage::Bool=false: enable or disable generation of coverage statistics.
  • allow_reresolve::Bool=true: allow Pkg to reresolve the package versions in the test environment
  • julia_args::Union{Cmd, Vector{String}}: options to be passed the test process.
  • test_args::Union{Cmd, Vector{String}}: test arguments (ARGS) available in the test process.
Julia 1.9

allow_reresolve requires at least Julia 1.9.

Run the tests for package pkg, or for the current project (which thus needs to be a package) if no positional argument is given to Pkg.test. A package is tested by running its test/runtests.jl file.

The tests are run by generating a temporary environment with only the pkg package and its (recursive) dependencies in it. If a manifest file exists and the allow_reresolve keyword argument is set to false, the versions in the manifest file are used. Otherwise a feasible set of packages is resolved and installed.

During the tests, 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"]

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.

source
Pkg.build — Function
Pkg.build(; verbose = false, io::IO=stderr)
+test = ["Test"]

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.

source
Pkg.build — Function
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)

Run the build script in deps/build.jl for pkg and all of its 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 on 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.

source
Pkg.pin — Function
Pkg.pin(pkg::Union{String, Vector{String}}; io::IO=stderr, all_pkgs::Bool=false)
+Pkg.build(pkgs::Union{PackageSpec, Vector{PackageSpec}}; verbose = false, io::IO=stderr)

Run the build script in deps/build.jl for pkg and all of its 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 on 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.

source
Pkg.pin — Function
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)

Pin a package to the current version (or the one given in the PackageSpec) or to a certain git revision. A pinned package is never automatically updated: if pkg is tracking a path, or a repository, those remain tracked but will not update. To get updates from the origin path or remote repository the package must first be freed.

Julia 1.7

The all_pkgs kwarg was introduced in julia 1.7.

Examples

Pkg.pin("Example")
 Pkg.pin(name="Example", version="0.3.1")
-Pkg.pin(all_pkgs = true)
source
Pkg.free — Function
Pkg.free(pkg::Union{String, Vector{String}}; io::IO=stderr, all_pkgs::Bool=false)
+Pkg.pin(all_pkgs = true)
source
Pkg.free — Function
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)

If pkg is pinned, remove the pin. If pkg is tracking a path, e.g. after Pkg.develop, go back to tracking registered versions. To free all dependencies set all_pkgs=true.

Julia 1.7

The all_pkgs kwarg was introduced in julia 1.7.

Examples

Pkg.free("Package")
-Pkg.free(all_pkgs = true)
source
Pkg.instantiate — Function
Pkg.instantiate(; verbose = false, io::IO=stderr)

If a Manifest.toml file exists in the active project, download all the packages declared in that manifest. Otherwise, resolve a set of feasible packages from the Project.toml files and install them. verbose = true prints the build output to stdout/stderr instead of redirecting to the build.log file. If no Project.toml exist in the current active project, create one with all the dependencies in the manifest and instantiate the resulting project.

After packages have been installed the project will be precompiled. See more at Environment Precompilation.

source
Pkg.resolve — Function
Pkg.resolve(; io::IO=stderr)

Update the current manifest with potential changes to the dependency graph from packages that are tracking a path.

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

Garbage-collect package and artifact installations by sweeping over all known Manifest.toml and Artifacts.toml files, noting those that have been deleted, and then finding artifacts and packages that are thereafter not used by any other projects, marking them as "orphaned". This method will only remove orphaned objects (package versions, artifacts, and scratch spaces) that have been continually un-used for a period of collect_delay; which defaults to seven days.

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

Print out the status of the project/manifest.

Packages marked with ⌃ have new versions that can be installed, e.g. via Pkg.up. Those marked with ⌅ have new versions available, but cannot be installed due to compatibility conflicts with other packages. To see why, set the keyword argument outdated=true.

Setting outdated=true will only show packages that are not on the latest version, their maximum version and why they are not on the latest version (either due to other packages holding them back due to compatibility constraints, or due to compatibility in the project file). As an example, a status output like:

pkg> Pkg.status(; outdated=true)
+Pkg.free(all_pkgs = true)
source
Pkg.instantiate — Function
Pkg.instantiate(; verbose = false, io::IO=stderr)

If a Manifest.toml file exists in the active project, download all the packages declared in that manifest. Otherwise, resolve a set of feasible packages from the Project.toml files and install them. verbose = true prints the build output to stdout/stderr instead of redirecting to the build.log file. If no Project.toml exist in the current active project, create one with all the dependencies in the manifest and instantiate the resulting project.

After packages have been installed the project will be precompiled. See more at Environment Precompilation.

source
Pkg.resolve — Function
Pkg.resolve(; io::IO=stderr)

Update the current manifest with potential changes to the dependency graph from packages that are tracking a path.

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

Garbage-collect package and artifact installations by sweeping over all known Manifest.toml and Artifacts.toml files, noting those that have been deleted, and then finding artifacts and packages that are thereafter not used by any other projects, marking them as "orphaned". This method will only remove orphaned objects (package versions, artifacts, and scratch spaces) that have been continually un-used for a period of collect_delay; which defaults to seven days.

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

Print out the status of the project/manifest.

Packages marked with ⌃ have new versions that can be installed, e.g. via Pkg.up. Those marked with ⌅ have new versions available, but cannot be installed due to compatibility conflicts with other packages. To see why, set the keyword argument outdated=true.

Setting outdated=true will only show packages that are not on the latest version, their maximum version and why they are not on the latest version (either due to other packages holding them back due to compatibility constraints, or due to compatibility in the project file). As an example, a status output like:

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

means that the latest version of Crayons is 4.0.4 but the latest version compatible with the [compat] section in the current project is 3.0.0. The latest version of NearestNeighbors is 0.4.9 but due to compat constrains in the project it is held back to 0.4.8. The latest version of LogExpFunctions is 0.3.0 but SpecialFunctions is holding it back to 0.2.5.

If mode is PKGMODE_PROJECT, print out status only about the packages that are in the project (explicitly added). If mode is PKGMODE_MANIFEST, print status also about those in the manifest (recursive dependencies). If there are any packages listed as arguments, the output will be limited to those packages.

Setting ext=true will show dependencies with extensions and what extension dependencies of those that are currently loaded.

Setting diff=true will, if the environment is in a git repository, limit the output to the difference as compared to the last git commit.

See Pkg.project and Pkg.dependencies to get the project/manifest status as a Julia object instead of printing it.

Julia 1.8

The ⌃ and ⌅ indicators were added in Julia 1.8. The outdated keyword argument requires at least Julia 1.8.

source
Pkg.compat — Function
Pkg.compat()

Interactively edit the [compat] entries within the current Project.

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

Set the [compat] string for the given package within the current Project.

See Compatibility for more information on the project [compat] section.

source
Pkg.precompile — Function
Pkg.precompile(; strict::Bool=false, timing::Bool=false)
+⌅ [2ab3a3ac] LogExpFunctions v0.2.5 (<v0.3.0): SpecialFunctions

means that the latest version of Crayons is 4.0.4 but the latest version compatible with the [compat] section in the current project is 3.0.0. The latest version of NearestNeighbors is 0.4.9 but due to compat constrains in the project it is held back to 0.4.8. The latest version of LogExpFunctions is 0.3.0 but SpecialFunctions is holding it back to 0.2.5.

If mode is PKGMODE_PROJECT, print out status only about the packages that are in the project (explicitly added). If mode is PKGMODE_MANIFEST, print status also about those in the manifest (recursive dependencies). If there are any packages listed as arguments, the output will be limited to those packages.

Setting ext=true will show dependencies with extensions and what extension dependencies of those that are currently loaded.

Setting diff=true will, if the environment is in a git repository, limit the output to the difference as compared to the last git commit.

See Pkg.project and Pkg.dependencies to get the project/manifest status as a Julia object instead of printing it.

Julia 1.8

The ⌃ and ⌅ indicators were added in Julia 1.8. The outdated keyword argument requires at least Julia 1.8.

source
Pkg.compat — Function
Pkg.compat()

Interactively edit the [compat] entries within the current Project.

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

Set the [compat] string for the given package within the current Project.

See Compatibility for more information on the project [compat] section.

source
Pkg.precompile — Function
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)

Precompile all or specific dependencies of the project in parallel.

Set timing=true to show the duration of the precompilation of each dependency.

Note

Errors will only throw when precompiling the top-level dependencies, given that not all manifest dependencies may be loaded by the top-level dependencies on the given system. This can be overridden to make errors in all dependencies throw by setting the kwarg strict to true

Note

This method is called automatically after any Pkg action that changes the manifest. Any packages that have previously errored during precompilation won't be retried in auto mode until they have changed. To disable automatic precompilation set ENV["JULIA_PKG_PRECOMPILE_AUTO"]=0. To manually control the number of tasks used set ENV["JULIA_NUM_PRECOMPILE_TASKS"].

Julia 1.8

Specifying packages to precompile requires at least Julia 1.8.

Julia 1.9

Timing mode requires at least Julia 1.9.

Examples

Pkg.precompile()
 Pkg.precompile("Foo")
-Pkg.precompile(["Foo", "Bar"])
source
Pkg.offline — Function
Pkg.offline(b::Bool=true)

Enable (b=true) or disable (b=false) offline mode.

In offline mode Pkg tries to do as much as possible without connecting to internet. For example, when adding a package Pkg only considers versions that are already downloaded in version resolution.

To work in offline mode across Julia sessions you can set the environment variable JULIA_PKG_OFFLINE to "true".

source
Pkg.why — Function
Pkg.why(pkg::Union{String, Vector{String}})
-Pkg.why(pkg::Union{PackageSpec, Vector{PackageSpec}})

Show the reason why this package is in the manifest. The output is all the different ways to reach the package through the dependency graph starting from the dependencies.

Julia 1.9

This function requires at least Julia 1.9.

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

This feature is considered experimental.

Query the dependency graph of the active project. The result is a Dict that maps a package UUID to a PackageInfo struct representing the dependency (a package).

PackageInfo fields

FieldDescription
nameThe name of the package
versionThe version of the package (this is Nothing for stdlibs)
tree_hashA file hash of the package directory tree
is_direct_depThe package is a direct dependency
is_pinnedWhether a package is pinned
is_tracking_pathWhether a package is tracking a path
is_tracking_repoWhether a package is tracking a repository
is_tracking_registryWhether a package is being tracked by registry i.e. not by path nor by repository
git_revisionThe git revision when tracking by repository
git_sourceThe git source when tracking by repository
sourceThe directory containing the source code for that package
dependenciesThe dependencies of that package as a vector of UUIDs
source
Pkg.respect_sysimage_versions — Function
Pkg.respect_sysimage_versions(b::Bool=true)

Enable (b=true) or disable (b=false) respecting versions that are in the sysimage (enabled by default).

If this option is enabled, Pkg will only install packages that have been put into the sysimage (e.g. via PackageCompiler) at the version of the package in the sysimage. Also, trying to add a package at a URL or develop a package that is in the sysimage will error.

source
Pkg.project — Function
Pkg.project()::ProjectInfo

This feature is considered experimental.

Request a ProjectInfo struct which contains information about the active project.

ProjectInfo fields

FieldDescription
nameThe project's name
uuidThe project's UUID
versionThe project's version
ispackageWhether the project is a package (has a name and uuid)
dependenciesThe project's direct dependencies as a Dict which maps dependency name to dependency UUID
pathThe location of the project file which defines the active project
source
Pkg.undo — Function
undo()

Undoes the latest change to the active project. Only states in the current session are stored, up to a maximum of 50 states.

See also: redo.

source
Pkg.redo — Function
redo()

Redoes the changes from the latest undo.

source
Pkg.setprotocol! — Function
setprotocol!(;
+Pkg.precompile(["Foo", "Bar"])
source
Pkg.offline — Function
Pkg.offline(b::Bool=true)

Enable (b=true) or disable (b=false) offline mode.

In offline mode Pkg tries to do as much as possible without connecting to internet. For example, when adding a package Pkg only considers versions that are already downloaded in version resolution.

To work in offline mode across Julia sessions you can set the environment variable JULIA_PKG_OFFLINE to "true".

source
Pkg.why — Function
Pkg.why(pkg::Union{String, Vector{String}})
+Pkg.why(pkg::Union{PackageSpec, Vector{PackageSpec}})

Show the reason why this package is in the manifest. The output is all the different ways to reach the package through the dependency graph starting from the dependencies.

Julia 1.9

This function requires at least Julia 1.9.

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

This feature is considered experimental.

Query the dependency graph of the active project. The result is a Dict that maps a package UUID to a PackageInfo struct representing the dependency (a package).

PackageInfo fields

FieldDescription
nameThe name of the package
versionThe version of the package (this is Nothing for stdlibs)
tree_hashA file hash of the package directory tree
is_direct_depThe package is a direct dependency
is_pinnedWhether a package is pinned
is_tracking_pathWhether a package is tracking a path
is_tracking_repoWhether a package is tracking a repository
is_tracking_registryWhether a package is being tracked by registry i.e. not by path nor by repository
git_revisionThe git revision when tracking by repository
git_sourceThe git source when tracking by repository
sourceThe directory containing the source code for that package
dependenciesThe dependencies of that package as a vector of UUIDs
source
Pkg.respect_sysimage_versions — Function
Pkg.respect_sysimage_versions(b::Bool=true)

Enable (b=true) or disable (b=false) respecting versions that are in the sysimage (enabled by default).

If this option is enabled, Pkg will only install packages that have been put into the sysimage (e.g. via PackageCompiler) at the version of the package in the sysimage. Also, trying to add a package at a URL or develop a package that is in the sysimage will error.

source
Pkg.project — Function
Pkg.project()::ProjectInfo

This feature is considered experimental.

Request a ProjectInfo struct which contains information about the active project.

ProjectInfo fields

FieldDescription
nameThe project's name
uuidThe project's UUID
versionThe project's version
ispackageWhether the project is a package (has a name and uuid)
dependenciesThe project's direct dependencies as a Dict which maps dependency name to dependency UUID
pathThe location of the project file which defines the active project
source
Pkg.undo — Function
undo()

Undoes the latest change to the active project. Only states in the current session are stored, up to a maximum of 50 states.

See also: redo.

source
Pkg.redo — Function
redo()

Redoes the changes from the latest undo.

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

Set the protocol used to access hosted packages when adding a url or developing a package. Defaults to delegating the choice to the package developer (protocol === nothing). Other choices for protocol are "https" or "git".

Examples

julia> Pkg.setprotocol!(domain = "github.com", protocol = "ssh")
 
-julia> Pkg.setprotocol!(domain = "gitlab.mycompany.com")
source
Pkg.PackageSpec — Type
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:

ExplicitConcise
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:

REPLAPI
PackagePackageSpec("Package")
Package@0.2PackageSpec(name="Package", version="0.2")
-PackageSpec(name="Package", version=v"0.2.1")
Package=a67d...PackageSpec(name="Package", uuid="a67d...")
Package#masterPackageSpec(name="Package", rev="master")
local/path#featurePackageSpec(path="local/path"; rev="feature")
www.mypkg.comPackageSpec(url="www.mypkg.com")
--major PackagePackageSpec(name="Package", version=UPLEVEL_MAJOR)
source
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 Pkg.rm, Pkg.update and Pkg.status.

source
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.

source

Registry API Reference

The functional API for registries uses RegistrySpecs, 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.

Examples

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

REPLAPI
MyRegistryRegistrySpec("MyRegistry")
MyRegistry=a67d...RegistrySpec(name="MyRegistry", uuid="a67d...")
local/pathRegistrySpec(path="local/path")
www.myregistry.comRegistrySpec(url="www.myregistry.com")
source
Pkg.Registry.add — Function
Pkg.Registry.add(registry::RegistrySpec)

Add new package registries.

The no-argument Pkg.Registry.add() will install the default registries.

Examples

Pkg.Registry.add("General")
+julia> Pkg.setprotocol!(domain = "gitlab.mycompany.com")
source
Pkg.PackageSpec — Type
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:

ExplicitConcise
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:

REPLAPI
PackagePackageSpec("Package")
Package@0.2PackageSpec(name="Package", version="0.2")
-PackageSpec(name="Package", version=v"0.2.1")
Package=a67d...PackageSpec(name="Package", uuid="a67d...")
Package#masterPackageSpec(name="Package", rev="master")
local/path#featurePackageSpec(path="local/path"; rev="feature")
www.mypkg.comPackageSpec(url="www.mypkg.com")
--major PackagePackageSpec(name="Package", version=UPLEVEL_MAJOR)
source
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 Pkg.rm, Pkg.update and Pkg.status.

source
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.

source

Registry API Reference

The functional API for registries uses RegistrySpecs, 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.

Examples

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

REPLAPI
MyRegistryRegistrySpec("MyRegistry")
MyRegistry=a67d...RegistrySpec(name="MyRegistry", uuid="a67d...")
local/pathRegistrySpec(path="local/path")
www.myregistry.comRegistrySpec(url="www.myregistry.com")
source
Pkg.Registry.add — Function
Pkg.Registry.add(registry::RegistrySpec)

Add new package registries.

The no-argument Pkg.Registry.add() will install the default registries.

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"))
source
Pkg.Registry.rm — Function
Pkg.Registry.rm(registry::String)
+Pkg.Registry.add(RegistrySpec(url = "https://github.com/JuliaRegistries/General.git"))
source
Pkg.Registry.rm — Function
Pkg.Registry.rm(registry::String)
 Pkg.Registry.rm(registry::RegistrySpec)

Remove registries.

Examples

Pkg.Registry.rm("General")
-Pkg.Registry.rm(RegistrySpec(uuid = "23338594-aafe-5451-b93e-139f81909106"))
source
Pkg.Registry.update — Function
Pkg.Registry.update()
+Pkg.Registry.rm(RegistrySpec(uuid = "23338594-aafe-5451-b93e-139f81909106"))
source
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.

Examples

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

Display information about available registries.

Examples

Pkg.Registry.status()
source

Artifacts API Reference

Pkg.Artifacts.create_artifact — Function
create_artifact(f::Function)

Creates a new artifact by running f(artifact_path), hashing the result, and moving it to the artifact store (~/.julia/artifacts on a typical installation). Returns the identifying tree hash of this artifact.

source
Pkg.Artifacts.remove_artifact — Function
remove_artifact(hash::SHA1; honor_overrides::Bool=false)

Removes the given artifact (identified by its SHA1 git tree hash) from disk. Note that if an artifact is installed in multiple depots, it will be removed from all of them. If an overridden artifact is requested for removal, it will be silently ignored; this method will never attempt to remove an overridden artifact.

In general, we recommend that you use Pkg.gc() to manage artifact installations and do not use remove_artifact() directly, as it can be difficult to know if an artifact is being used by another package.

source
Pkg.Artifacts.verify_artifact — Function
verify_artifact(hash::SHA1; honor_overrides::Bool=false)

Verifies that the given artifact (identified by its SHA1 git tree hash) is installed on- disk, and retains its integrity. If the given artifact is overridden, skips the verification unless honor_overrides is set to true.

source
Pkg.Artifacts.bind_artifact! — Function
bind_artifact!(artifacts_toml::String, name::String, hash::SHA1;
+Pkg.Registry.update(RegistrySpec(uuid = "23338594-aafe-5451-b93e-139f81909106"))
source
Pkg.Registry.status — Function
Pkg.Registry.status()

Display information about available registries.

Examples

Pkg.Registry.status()
source

Artifacts API Reference

Pkg.Artifacts.create_artifact — Function
create_artifact(f::Function)

Creates a new artifact by running f(artifact_path), hashing the result, and moving it to the artifact store (~/.julia/artifacts on a typical installation). Returns the identifying tree hash of this artifact.

source
Pkg.Artifacts.remove_artifact — Function
remove_artifact(hash::SHA1; honor_overrides::Bool=false)

Removes the given artifact (identified by its SHA1 git tree hash) from disk. Note that if an artifact is installed in multiple depots, it will be removed from all of them. If an overridden artifact is requested for removal, it will be silently ignored; this method will never attempt to remove an overridden artifact.

In general, we recommend that you use Pkg.gc() to manage artifact installations and do not use remove_artifact() directly, as it can be difficult to know if an artifact is being used by another package.

source
Pkg.Artifacts.verify_artifact — Function
verify_artifact(hash::SHA1; honor_overrides::Bool=false)

Verifies that the given artifact (identified by its SHA1 git tree hash) is installed on- disk, and retains its integrity. If the given artifact is overridden, skips the verification unless honor_overrides is set to true.

source
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)

Writes a mapping of name -> hash within the given (Julia)Artifacts.toml file. If platform is not nothing, this artifact is marked as platform-specific, and will be a multi-mapping. It is valid to bind multiple artifacts with the same name, but different platforms and hash'es within the same artifacts_toml. If force is set to true, this will overwrite a pre-existant mapping, otherwise an error is raised.

download_info is an optional vector that contains tuples of URLs and a hash. These URLs will be listed as possible locations where this artifact can be obtained. If lazy is set to true, even if download information is available, this artifact will not be downloaded until it is accessed via the artifact"name" syntax, or ensure_artifact_installed() is called upon it.

source
Pkg.Artifacts.unbind_artifact! — Function
unbind_artifact!(artifacts_toml::String, name::String; platform = nothing)

Unbind the given name from an (Julia)Artifacts.toml file. Silently fails if no such binding exists within the file.

source
Pkg.Artifacts.download_artifact — Function
download_artifact(tree_hash::SHA1, tarball_url::String, tarball_hash::String;
-                  verbose::Bool = false, io::IO=stderr)

Download/install an artifact into the artifact store. Returns true on success, returns an error object on failure.

Julia 1.8

As of Julia 1.8 this function returns the error object rather than false when failure occurs

source
Pkg.Artifacts.ensure_artifact_installed — Function
ensure_artifact_installed(name::String, artifacts_toml::String;
+               force::Bool = false)

Writes a mapping of name -> hash within the given (Julia)Artifacts.toml file. If platform is not nothing, this artifact is marked as platform-specific, and will be a multi-mapping. It is valid to bind multiple artifacts with the same name, but different platforms and hash'es within the same artifacts_toml. If force is set to true, this will overwrite a pre-existant mapping, otherwise an error is raised.

download_info is an optional vector that contains tuples of URLs and a hash. These URLs will be listed as possible locations where this artifact can be obtained. If lazy is set to true, even if download information is available, this artifact will not be downloaded until it is accessed via the artifact"name" syntax, or ensure_artifact_installed() is called upon it.

source
Pkg.Artifacts.unbind_artifact! — Function
unbind_artifact!(artifacts_toml::String, name::String; platform = nothing)

Unbind the given name from an (Julia)Artifacts.toml file. Silently fails if no such binding exists within the file.

source
Pkg.Artifacts.download_artifact — Function
download_artifact(tree_hash::SHA1, tarball_url::String, tarball_hash::String;
+                  verbose::Bool = false, io::IO=stderr)

Download/install an artifact into the artifact store. Returns true on success, returns an error object on failure.

Julia 1.8

As of Julia 1.8 this function returns the error object rather than false when failure occurs

source
Pkg.Artifacts.ensure_artifact_installed — Function
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)

Ensures an artifact is installed, downloading it via the download information stored in artifacts_toml if necessary. Throws an error if unable to install.

source
Pkg.Artifacts.ensure_all_artifacts_installed — Function
ensure_all_artifacts_installed(artifacts_toml::String;
+                          io::IO=stderr)

Ensures an artifact is installed, downloading it via the download information stored in artifacts_toml if necessary. Throws an error if unable to install.

source
Pkg.Artifacts.ensure_all_artifacts_installed — Function
ensure_all_artifacts_installed(artifacts_toml::String;
                                platform = HostPlatform(),
                                pkg_uuid = nothing,
                                include_lazy = false,
@@ -77,4 +77,4 @@
                                io::IO=stderr)

Installs all non-lazy artifacts from a given (Julia)Artifacts.toml file. package_uuid must be provided to properly support overrides from Overrides.toml entries in depots.

If include_lazy is set to true, then lazy packages will be installed as well.

This function is deprecated and should be replaced with the following snippet:

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
Warning

This function is deprecated in Julia 1.6 and will be removed in a future version. Use select_downloadable_artifacts() and ensure_artifact_installed() instead.

source
Pkg.Artifacts.archive_artifact — Function
archive_artifact(hash::SHA1, tarball_path::String; honor_overrides::Bool=false)

Archive an artifact into a tarball stored at tarball_path, returns the SHA256 of the resultant tarball as a hexadecimal string. Throws an error if the artifact does not exist. If the artifact is overridden, throws an error unless honor_overrides is set.

source
+end
Warning

This function is deprecated in Julia 1.6 and will be removed in a future version. Use select_downloadable_artifacts() and ensure_artifact_installed() instead.

source
Pkg.Artifacts.archive_artifact — Function
archive_artifact(hash::SHA1, tarball_path::String; honor_overrides::Bool=false)

Archive an artifact into a tarball stored at tarball_path, returns the SHA256 of the resultant tarball as a hexadecimal string. Throws an error if the artifact does not exist. If the artifact is overridden, throws an error unless honor_overrides is set.

source
diff --git a/dev/artifacts/index.html b/dev/artifacts/index.html index 2627bca987..8ed3f1655c 100644 --- a/dev/artifacts/index.html +++ b/dev/artifacts/index.html @@ -137,4 +137,4 @@ function __init__() p = augment_platform!(HostPlatform()) global my_artifact_dir = @artifact_str("MyArtifact", p) -end

This ensures that the same artifact is used by your code as Pkg attempted to install.

Artifact selection hooks are only allowed to use Base, Artifacts, Libdl, and TOML. They are not allowed to use any other standard libraries, and they are not allowed to use any packages (including the package to which they belong).

+end

This ensures that the same artifact is used by your code as Pkg attempted to install.

Artifact selection hooks are only allowed to use Base, Artifacts, Libdl, and TOML. They are not allowed to use any other standard libraries, and they are not allowed to use any packages (including the package to which they belong).

diff --git a/dev/basedocs/index.html b/dev/basedocs/index.html index 71da96e208..197ed4e933 100644 --- a/dev/basedocs/index.html +++ b/dev/basedocs/index.html @@ -28,4 +28,4 @@ (tutorial) pkg> status Status `~/tutorial/Project.toml` [7876af07] Example v0.5.3 - [682c06a0] JSON v0.21.3

We can see that the tutorial environment now contains Example and JSON.

Note

If you have the same package (at the same version) installed in multiple environments, the package will only be downloaded and stored on the hard drive once. This makes environments very lightweight and effectively free to create. Only using the default environment with a huge number of packages in it is a common beginners mistake in Julia. Learning how to use environments effectively will improve your experience with Julia packages.

For more information about environments, see the Working with Environments section of the documentation.

If you are ever stuck, you can ask Pkg for help:

(@v1.9) pkg> ?

You should see a list of available commands along with short descriptions. You can ask for more detailed help by specifying a command:

(@v1.9) pkg> ?develop

This guide should help you get started with Pkg. Pkg has much more to offer in terms of powerful package management, read the full manual to learn more!

+ [682c06a0] JSON v0.21.3

We can see that the tutorial environment now contains Example and JSON.

Note

If you have the same package (at the same version) installed in multiple environments, the package will only be downloaded and stored on the hard drive once. This makes environments very lightweight and effectively free to create. Only using the default environment with a huge number of packages in it is a common beginners mistake in Julia. Learning how to use environments effectively will improve your experience with Julia packages.

For more information about environments, see the Working with Environments section of the documentation.

If you are ever stuck, you can ask Pkg for help:

(@v1.9) pkg> ?

You should see a list of available commands along with short descriptions. You can ask for more detailed help by specifying a command:

(@v1.9) pkg> ?develop

This guide should help you get started with Pkg. Pkg has much more to offer in terms of powerful package management, read the full manual to learn more!

diff --git a/dev/compatibility/index.html b/dev/compatibility/index.html index 0f0ae66e8b..e33044d2b9 100644 --- a/dev/compatibility/index.html +++ b/dev/compatibility/index.html @@ -43,4 +43,4 @@ PkgA = "0.2 - 0.5" # 0.2.0 - 0.5.* = [0.2.0, 0.6.0) PkgA = "0.2 - 0" # 0.2.0 - 0.*.* = [0.2.0, 1.0.0)

Fixing conflicts

Version conflicts were introduced previously with an example of a conflict arising in a package D used by two other packages, B and C. Our analysis of the error message revealed that B is using an outdated version of D. To fix it, the first thing to try is to pkg> dev B so that you can modify B and its compatibility requirements. If you open its Project.toml file in an editor, you would probably notice something like

[compat]
 D = "0.1"

Usually the first step is to modify this to something like

[compat]
-D = "0.1, 0.2"

This indicates that B is compatible with both versions 0.1 and version 0.2; if you pkg> up this would fix the package error. However, there is one major concern you need to address first: perhaps there was an incompatible change in v0.2 of D that breaks B. Before proceeding further, you should update all packages and then run B's tests, scanning the output of pkg> test B to be sure that v0.2 of D is in fact being used. (It is possible that an additional dependency of D pins it to v0.1, and you wouldn't want to be misled into thinking that you had tested B on the newer version.) If the new version was used and the tests still pass, you can assume that B didn't need any further updating to accommodate v0.2 of D; you can safely submit this change as a pull request to B so that a new release is made. If instead an error is thrown, it indicates that B requires more extensive updates to be compatible with the latest version of D; those updates will need to be completed before it becomes possible to use both A and B simultaneously. You can, though, continue to use them independently of one another.

+D = "0.1, 0.2"

This indicates that B is compatible with both versions 0.1 and version 0.2; if you pkg> up this would fix the package error. However, there is one major concern you need to address first: perhaps there was an incompatible change in v0.2 of D that breaks B. Before proceeding further, you should update all packages and then run B's tests, scanning the output of pkg> test B to be sure that v0.2 of D is in fact being used. (It is possible that an additional dependency of D pins it to v0.1, and you wouldn't want to be misled into thinking that you had tested B on the newer version.) If the new version was used and the tests still pass, you can assume that B didn't need any further updating to accommodate v0.2 of D; you can safely submit this change as a pull request to B so that a new release is made. If instead an error is thrown, it indicates that B requires more extensive updates to be compatible with the latest version of D; those updates will need to be completed before it becomes possible to use both A and B simultaneously. You can, though, continue to use them independently of one another.

diff --git a/dev/creating-packages/index.html b/dev/creating-packages/index.html index b810282a38..2ea8fe49ae 100644 --- a/dev/creating-packages/index.html +++ b/dev/creating-packages/index.html @@ -160,4 +160,4 @@ end end

  • Make the following change in the conditionally-loaded code:

    isdefined(Base, :get_extension) ? (using Contour) : (using ..Contour)

    • The package should now work with Requires.jl on Julia versions before extensions were introduced and with extensions on more recent Julia versions.

    Transition from normal dependency to extension

    This section is relevant if you have a normal dependency that you want to transition be an extension (while still having the dependency be a normal dependency on Julia versions that do not support extensions). This is done by making the following changes (using the example above):

    Using an extension while supporting older Julia versions

    In the case where one wants to use an extension (without worrying about the feature of the extension begin available on older Julia versions) while still supporting older Julia versions the packages under [weakdeps] should be duplicated into [extras]. This is an unfortunate duplication, but without doing this the project verifier under older Julia versions will throw an error if it finds packages under [compat] that is not listed in [extras].

    Package naming guidelines

    Package names should be sensible to most Julia users, even to those who are not domain experts. The following guidelines apply to the General registry but may be useful for other package registries as well.

    Since the General registry belongs to the entire community, people may have opinions about your package name when you publish it, especially if it's ambiguous or can be confused with something other than what it is. Usually, you will then get suggestions for a new name that may fit your package better.

    1. Avoid jargon. In particular, avoid acronyms unless there is minimal possibility of confusion.

    2. Avoid using Julia in your package name or prefixing it with Ju.

    3. Packages that provide most of their functionality in association with a new type should have pluralized names.

    4. Err on the side of clarity, even if clarity seems long-winded to you.

    5. A less systematic name may suit a package that implements one of several possible approaches to its domain.

    6. Packages that wrap external libraries or programs should be named after those libraries or programs.

    7. Avoid naming a package closely to an existing package

    Registering packages

    Once a package is ready it can be registered with the General Registry (see also the FAQ). Currently, packages are submitted via Registrator. In addition to Registrator, TagBot helps manage the process of tagging releases.

    Best Practices

    Packages should avoid mutating their own state (writing to files within their package directory). Packages should, in general, not assume that they are located in a writable location (e.g. if installed as part of a system-wide depot) or even a stable one (e.g. if they are bundled into a system image by PackageCompiler.jl). To support the various use cases in the Julia package ecosystem, the Pkg developers have created a number of auxiliary packages and techniques to help package authors create self-contained, immutable, and relocatable packages:

    +end

    Using an extension while supporting older Julia versions

    In the case where one wants to use an extension (without worrying about the feature of the extension begin available on older Julia versions) while still supporting older Julia versions the packages under [weakdeps] should be duplicated into [extras]. This is an unfortunate duplication, but without doing this the project verifier under older Julia versions will throw an error if it finds packages under [compat] that is not listed in [extras].

    Package naming guidelines

    Package names should be sensible to most Julia users, even to those who are not domain experts. The following guidelines apply to the General registry but may be useful for other package registries as well.

    Since the General registry belongs to the entire community, people may have opinions about your package name when you publish it, especially if it's ambiguous or can be confused with something other than what it is. Usually, you will then get suggestions for a new name that may fit your package better.

    1. Avoid jargon. In particular, avoid acronyms unless there is minimal possibility of confusion.

    2. Avoid using Julia in your package name or prefixing it with Ju.

    3. Packages that provide most of their functionality in association with a new type should have pluralized names.

    4. Err on the side of clarity, even if clarity seems long-winded to you.

    5. A less systematic name may suit a package that implements one of several possible approaches to its domain.

    6. Packages that wrap external libraries or programs should be named after those libraries or programs.

    7. Avoid naming a package closely to an existing package

    Registering packages

    Once a package is ready it can be registered with the General Registry (see also the FAQ). Currently, packages are submitted via Registrator. In addition to Registrator, TagBot helps manage the process of tagging releases.

    Best Practices

    Packages should avoid mutating their own state (writing to files within their package directory). Packages should, in general, not assume that they are located in a writable location (e.g. if installed as part of a system-wide depot) or even a stable one (e.g. if they are bundled into a system image by PackageCompiler.jl). To support the various use cases in the Julia package ecosystem, the Pkg developers have created a number of auxiliary packages and techniques to help package authors create self-contained, immutable, and relocatable packages:

    diff --git a/dev/environments/index.html b/dev/environments/index.html index 668f1afe8f..57cf168794 100644 --- a/dev/environments/index.html +++ b/dev/environments/index.html @@ -75,4 +75,4 @@ ◑ IntegralArrays ◒ RegionTrees ◐ ChangesOfVariables - ◓ PaddedViews

    The exception is the develop command, which neither builds nor precompiles the package. When that happens is left up to the user to decide.

    If a given package version errors during auto-precompilation, Pkg will remember for the following times it automatically tries and will skip that package with a brief warning. Manual precompilation can be used to force these packages to be retried, as pkg> precompile will always retry all packages.

    To disable the auto-precompilation, set ENV["JULIA_PKG_PRECOMPILE_AUTO"]=0.

    Precompiling new versions of loaded packages

    If a package that has been updated is already loaded in the session, the precompilation process will go ahead and precompile the new version, and any packages that depend on it, but will note that the package cannot be used until session restart.

    + ◓ PaddedViews

    The exception is the develop command, which neither builds nor precompiles the package. When that happens is left up to the user to decide.

    If a given package version errors during auto-precompilation, Pkg will remember for the following times it automatically tries and will skip that package with a brief warning. Manual precompilation can be used to force these packages to be retried, as pkg> precompile will always retry all packages.

    To disable the auto-precompilation, set ENV["JULIA_PKG_PRECOMPILE_AUTO"]=0.

    Precompiling new versions of loaded packages

    If a package that has been updated is already loaded in the session, the precompilation process will go ahead and precompile the new version, and any packages that depend on it, but will note that the package cannot be used until session restart.

    diff --git a/dev/getting-started/index.html b/dev/getting-started/index.html index be2edb5536..39faaf9c12 100644 --- a/dev/getting-started/index.html +++ b/dev/getting-started/index.html @@ -28,4 +28,4 @@ (tutorial) pkg> status Status `~/tutorial/Project.toml` [7876af07] Example v0.5.3 - [682c06a0] JSON v0.21.3

    We can see that the tutorial environment now contains Example and JSON.

    Note

    If you have the same package (at the same version) installed in multiple environments, the package will only be downloaded and stored on the hard drive once. This makes environments very lightweight and effectively free to create. Only using the default environment with a huge number of packages in it is a common beginners mistake in Julia. Learning how to use environments effectively will improve your experience with Julia packages.

    For more information about environments, see the Working with Environments section of the documentation.

    Asking for Help

    If you are ever stuck, you can ask Pkg for help:

    (@v1.9) pkg> ?

    You should see a list of available commands along with short descriptions. You can ask for more detailed help by specifying a command:

    (@v1.9) pkg> ?develop

    This guide should help you get started with Pkg. Pkg has much more to offer in terms of powerful package management, read the full manual to learn more!

    + [682c06a0] JSON v0.21.3

    We can see that the tutorial environment now contains Example and JSON.

    Note

    If you have the same package (at the same version) installed in multiple environments, the package will only be downloaded and stored on the hard drive once. This makes environments very lightweight and effectively free to create. Only using the default environment with a huge number of packages in it is a common beginners mistake in Julia. Learning how to use environments effectively will improve your experience with Julia packages.

    For more information about environments, see the Working with Environments section of the documentation.

    Asking for Help

    If you are ever stuck, you can ask Pkg for help:

    (@v1.9) pkg> ?

    You should see a list of available commands along with short descriptions. You can ask for more detailed help by specifying a command:

    (@v1.9) pkg> ?develop

    This guide should help you get started with Pkg. Pkg has much more to offer in terms of powerful package management, read the full manual to learn more!

    diff --git a/dev/glossary/index.html b/dev/glossary/index.html index e4e3a0b8b9..c184c4b750 100644 --- a/dev/glossary/index.html +++ b/dev/glossary/index.html @@ -1,2 +1,2 @@ -9. Glossary · Pkg.jl
    Edit on GitHub

    9. Glossary

    Project: a source tree with a standard layout, including a src directory for the main body of Julia code, a test directory for testing the project, a docs directory for documentation files, and optionally a deps directory for a build script and its outputs. A project will typically also have a project file and may optionally have a manifest file:

    • Project file: a file in the root directory of a project, named Project.toml (or JuliaProject.toml), describing metadata about the project, including its name, UUID (for packages), authors, license, and the names and UUIDs of packages and libraries that it depends on.

    • Manifest file: a file in the root directory of a project, named Manifest.toml (or JuliaManifest.toml), describing a complete dependency graph and exact versions of each package and library used by a project.

    Package: a project which provides reusable functionality that can be used by other Julia projects via import X or using X. A package should have a project file with a uuid entry giving its package UUID. This UUID is used to identify the package in projects that depend on it.

    Note

    For legacy reasons, it is possible to load a package without a project file or UUID from the REPL or the top-level of a script. It is not possible, however, to load a package without a project file or UUID from a project with them. Once you've loaded from a project file, everything needs a project file and UUID.

    Application: a project which provides standalone functionality not intended to be reused by other Julia projects. For example a web application or a command-line utility, or simulation/analytics code accompanying a scientific paper. An application may have a UUID but does not need one. An application may also provide global configuration options for packages it depends on. Packages, on the other hand, may not provide global configuration since that could conflict with the configuration of the main application.

    Note

    Projects vs. Packages vs. Applications:

    1. Project is an umbrella term: packages and applications are kinds of projects.
    2. Packages should have UUIDs, applications can have UUIDs but don't need them.
    3. Applications can provide global configuration, whereas packages cannot.

    Environment: the combination of the top-level name map provided by a project file combined with the dependency graph and map from packages to their entry points provided by a manifest file. For more detail see the manual section on code loading.

    • Explicit environment: an environment in the form of an explicit project file and an optional corresponding manifest file together in a directory. If the manifest file is absent then the implied dependency graph and location maps are empty.

    • Implicit environment: an environment provided as a directory (without a project file or manifest file) containing packages with entry points of the form X.jl, X.jl/src/X.jl or X/src/X.jl. The top-level name map is implied by these entry points. The dependency graph is implied by the existence of project files inside of these package directories, e.g. X.jl/Project.toml or X/Project.toml. The dependencies of the X package are the dependencies in the corresponding project file if there is one. The location map is implied by the entry points themselves.

    Registry: a source tree with a standard layout recording metadata about a registered set of packages, the tagged versions of them which are available, and which versions of packages are compatible or incompatible with each other. A registry is indexed by package name and UUID, and has a directory for each registered package providing the following metadata about it:

    • name – e.g. DataFrames
    • UUID – e.g. a93c6f00-e57d-5684-b7b6-d8193f3e46c0
    • repository – e.g. https://github.com/JuliaData/DataFrames.jl.git
    • versions – a list of all registered version tags

    For each registered version of a package, the following information is provided:

    • its semantic version number – e.g. v1.2.3
    • its git tree SHA-1 hash – e.g. 7ffb18ea3245ef98e368b02b81e8a86543a11103
    • a map from names to UUIDs of dependencies
    • which versions of other packages it is compatible/incompatible with

    Dependencies and compatibility are stored in a compressed but human-readable format using ranges of package versions.

    Depot: a directory on a system where various package-related resources live, including:

    • environments: shared named environments (e.g. v1.0, devtools)
    • clones: bare clones of package repositories
    • compiled: cached compiled package images (.ji files)
    • config: global configuration files (e.g. startup.jl)
    • dev: default directory for package development
    • logs: log files (e.g. manifest_usage.toml, repl_history.jl)
    • packages: installed package versions
    • registries: clones of registries (e.g. General)

    Load path: a stack of environments where package identities, their dependencies, and entry points are searched for. The load path is controlled in Julia by the LOAD_PATH global variable which is populated at startup based on the value of the JULIA_LOAD_PATH environment variable. The first entry is your primary environment, often the current project, while later entries provide additional packages one may want to use from the REPL or top-level scripts.

    Depot path: a stack of depot locations where the package manager, as well as Julia's code loading mechanisms, look for registries, installed packages, named environments, repo clones, cached compiled package images, and configuration files. The depot path is controlled by the Julia DEPOT_PATH global variable which is populated at startup based on the value of the JULIA_DEPOT_PATH environment variable. The first entry is the “user depot” and should be writable by and owned by the current user. The user depot is where: registries are cloned, new package versions are installed, named environments are created and updated, package repositories are cloned, newly compiled package image files are saved, log files are written, development packages are checked out by default, and global configuration data is saved. Later entries in the depot path are treated as read-only and are appropriate for registries, packages, etc. installed and managed by system administrators.

    +9. Glossary · Pkg.jl
    Edit on GitHub

    9. Glossary

    Project: a source tree with a standard layout, including a src directory for the main body of Julia code, a test directory for testing the project, a docs directory for documentation files, and optionally a deps directory for a build script and its outputs. A project will typically also have a project file and may optionally have a manifest file:

    • Project file: a file in the root directory of a project, named Project.toml (or JuliaProject.toml), describing metadata about the project, including its name, UUID (for packages), authors, license, and the names and UUIDs of packages and libraries that it depends on.

    • Manifest file: a file in the root directory of a project, named Manifest.toml (or JuliaManifest.toml), describing a complete dependency graph and exact versions of each package and library used by a project.

    Package: a project which provides reusable functionality that can be used by other Julia projects via import X or using X. A package should have a project file with a uuid entry giving its package UUID. This UUID is used to identify the package in projects that depend on it.

    Note

    For legacy reasons, it is possible to load a package without a project file or UUID from the REPL or the top-level of a script. It is not possible, however, to load a package without a project file or UUID from a project with them. Once you've loaded from a project file, everything needs a project file and UUID.

    Application: a project which provides standalone functionality not intended to be reused by other Julia projects. For example a web application or a command-line utility, or simulation/analytics code accompanying a scientific paper. An application may have a UUID but does not need one. An application may also provide global configuration options for packages it depends on. Packages, on the other hand, may not provide global configuration since that could conflict with the configuration of the main application.

    Note

    Projects vs. Packages vs. Applications:

    1. Project is an umbrella term: packages and applications are kinds of projects.
    2. Packages should have UUIDs, applications can have UUIDs but don't need them.
    3. Applications can provide global configuration, whereas packages cannot.

    Environment: the combination of the top-level name map provided by a project file combined with the dependency graph and map from packages to their entry points provided by a manifest file. For more detail see the manual section on code loading.

    • Explicit environment: an environment in the form of an explicit project file and an optional corresponding manifest file together in a directory. If the manifest file is absent then the implied dependency graph and location maps are empty.

    • Implicit environment: an environment provided as a directory (without a project file or manifest file) containing packages with entry points of the form X.jl, X.jl/src/X.jl or X/src/X.jl. The top-level name map is implied by these entry points. The dependency graph is implied by the existence of project files inside of these package directories, e.g. X.jl/Project.toml or X/Project.toml. The dependencies of the X package are the dependencies in the corresponding project file if there is one. The location map is implied by the entry points themselves.

    Registry: a source tree with a standard layout recording metadata about a registered set of packages, the tagged versions of them which are available, and which versions of packages are compatible or incompatible with each other. A registry is indexed by package name and UUID, and has a directory for each registered package providing the following metadata about it:

    • name – e.g. DataFrames
    • UUID – e.g. a93c6f00-e57d-5684-b7b6-d8193f3e46c0
    • repository – e.g. https://github.com/JuliaData/DataFrames.jl.git
    • versions – a list of all registered version tags

    For each registered version of a package, the following information is provided:

    • its semantic version number – e.g. v1.2.3
    • its git tree SHA-1 hash – e.g. 7ffb18ea3245ef98e368b02b81e8a86543a11103
    • a map from names to UUIDs of dependencies
    • which versions of other packages it is compatible/incompatible with

    Dependencies and compatibility are stored in a compressed but human-readable format using ranges of package versions.

    Depot: a directory on a system where various package-related resources live, including:

    • environments: shared named environments (e.g. v1.0, devtools)
    • clones: bare clones of package repositories
    • compiled: cached compiled package images (.ji files)
    • config: global configuration files (e.g. startup.jl)
    • dev: default directory for package development
    • logs: log files (e.g. manifest_usage.toml, repl_history.jl)
    • packages: installed package versions
    • registries: clones of registries (e.g. General)

    Load path: a stack of environments where package identities, their dependencies, and entry points are searched for. The load path is controlled in Julia by the LOAD_PATH global variable which is populated at startup based on the value of the JULIA_LOAD_PATH environment variable. The first entry is your primary environment, often the current project, while later entries provide additional packages one may want to use from the REPL or top-level scripts.

    Depot path: a stack of depot locations where the package manager, as well as Julia's code loading mechanisms, look for registries, installed packages, named environments, repo clones, cached compiled package images, and configuration files. The depot path is controlled by the Julia DEPOT_PATH global variable which is populated at startup based on the value of the JULIA_DEPOT_PATH environment variable. The first entry is the “user depot” and should be writable by and owned by the current user. The user depot is where: registries are cloned, new package versions are installed, named environments are created and updated, package repositories are cloned, newly compiled package image files are saved, log files are written, development packages are checked out by default, and global configuration data is saved. Later entries in the depot path are treated as read-only and are appropriate for registries, packages, etc. installed and managed by system administrators.

    diff --git a/dev/index.html b/dev/index.html index 7aa919832f..70715a8eaf 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -1. Introduction · Pkg.jl
    Edit on GitHub

    1. Introduction

    Welcome to the documentation for Pkg, Julia's package manager. The documentation covers many things, for example managing package installations, developing packages, working with package registries and more.

    Throughout the manual the REPL interface to Pkg, the Pkg REPL mode, is used in the examples. There is also a functional API, which is preferred when not working interactively. This API is documented in the API Reference section.

    Background and Design

    Unlike traditional package managers, which install and manage a single global set of packages, Pkg is designed around “environments”: independent sets of packages that can be local to an individual project or shared and selected by name. The exact set of packages and versions in an environment is captured in a manifest file which can be checked into a project repository and tracked in version control, significantly improving reproducibility of projects. If you’ve ever tried to run code you haven’t used in a while only to find that you can’t get anything to work because you’ve updated or uninstalled some of the packages your project was using, you’ll understand the motivation for this approach. In Pkg, since each project maintains its own independent set of package versions, you’ll never have this problem again. Moreover, if you check out a project on a new system, you can simply materialize the environment described by its manifest file and immediately be up and running with a known-good set of dependencies.

    Since environments are managed and updated independently from each other, “dependency hell” is significantly alleviated in Pkg. If you want to use the latest and greatest version of some package in a new project but you’re stuck on an older version in a different project, that’s no problem – since they have separate environments they can just use different versions, which are both installed at the same time in different locations on your system. The location of each package version is canonical, so when environments use the same versions of packages, they can share installations, avoiding unnecessary duplication of the package. Old package versions that are no longer used by any environments are periodically “garbage collected” by the package manager.

    Pkg’s approach to local environments may be familiar to people who have used Python’s virtualenv or Ruby’s bundler. In Julia, instead of hacking the language’s code loading mechanisms to support environments, we have the benefit that Julia natively understands them. In addition, Julia environments are “stackable”: you can overlay one environment with another and thereby have access to additional packages outside of the primary environment. This makes it easy to work on a project, which provides the primary environment, while still having access from the REPL to all your usual dev tools like profilers, debuggers, and so on, just by having an environment including these dev tools later in the load path.

    Last but not least, Pkg is designed to support federated package registries. This means that it allows multiple registries managed by different parties to interact seamlessly. In particular, this includes private registries which can live behind corporate firewalls. You can install and update your own packages from a private registry with exactly the same tools and workflows that you use to install and manage official Julia packages. If you urgently need to apply a hotfix for a public package that’s critical to your company’s product, you can tag a private version of it in your company’s internal registry and get a fix to your developers and ops teams quickly and easily without having to wait for an upstream patch to be accepted and published. Once an official fix is published, however, you can just upgrade your dependencies and you'll be back on an official release again.

    +1. Introduction · Pkg.jl
    Edit on GitHub

    1. Introduction

    Welcome to the documentation for Pkg, Julia's package manager. The documentation covers many things, for example managing package installations, developing packages, working with package registries and more.

    Throughout the manual the REPL interface to Pkg, the Pkg REPL mode, is used in the examples. There is also a functional API, which is preferred when not working interactively. This API is documented in the API Reference section.

    Background and Design

    Unlike traditional package managers, which install and manage a single global set of packages, Pkg is designed around “environments”: independent sets of packages that can be local to an individual project or shared and selected by name. The exact set of packages and versions in an environment is captured in a manifest file which can be checked into a project repository and tracked in version control, significantly improving reproducibility of projects. If you’ve ever tried to run code you haven’t used in a while only to find that you can’t get anything to work because you’ve updated or uninstalled some of the packages your project was using, you’ll understand the motivation for this approach. In Pkg, since each project maintains its own independent set of package versions, you’ll never have this problem again. Moreover, if you check out a project on a new system, you can simply materialize the environment described by its manifest file and immediately be up and running with a known-good set of dependencies.

    Since environments are managed and updated independently from each other, “dependency hell” is significantly alleviated in Pkg. If you want to use the latest and greatest version of some package in a new project but you’re stuck on an older version in a different project, that’s no problem – since they have separate environments they can just use different versions, which are both installed at the same time in different locations on your system. The location of each package version is canonical, so when environments use the same versions of packages, they can share installations, avoiding unnecessary duplication of the package. Old package versions that are no longer used by any environments are periodically “garbage collected” by the package manager.

    Pkg’s approach to local environments may be familiar to people who have used Python’s virtualenv or Ruby’s bundler. In Julia, instead of hacking the language’s code loading mechanisms to support environments, we have the benefit that Julia natively understands them. In addition, Julia environments are “stackable”: you can overlay one environment with another and thereby have access to additional packages outside of the primary environment. This makes it easy to work on a project, which provides the primary environment, while still having access from the REPL to all your usual dev tools like profilers, debuggers, and so on, just by having an environment including these dev tools later in the load path.

    Last but not least, Pkg is designed to support federated package registries. This means that it allows multiple registries managed by different parties to interact seamlessly. In particular, this includes private registries which can live behind corporate firewalls. You can install and update your own packages from a private registry with exactly the same tools and workflows that you use to install and manage official Julia packages. If you urgently need to apply a hotfix for a public package that’s critical to your company’s product, you can tag a private version of it in your company’s internal registry and get a fix to your developers and ops teams quickly and easily without having to wait for an upstream patch to be accepted and published. Once an official fix is published, however, you can just upgrade your dependencies and you'll be back on an official release again.

    diff --git a/dev/managing-packages/index.html b/dev/managing-packages/index.html index 87e1012ecd..c79e875a78 100644 --- a/dev/managing-packages/index.html +++ b/dev/managing-packages/index.html @@ -144,4 +144,4 @@ # unset to always download data from original sources julia> ENV["JULIA_PKG_SERVER"] = "" -""

    For clarification, some sources are not provided by Pkg server

    Note

    If you have a new registry installed via pkg server, then it's impossible for old Julia versions to update the registry because Julia before 1.4 doesn't know how to fetch new data. Hence, for users that frequently switch between multiple Julia versions, it is recommended to still use git-controlled registries.

    For the deployment of pkg server, please refer to PkgServer.jl.

    +""

    For clarification, some sources are not provided by Pkg server

    Note

    If you have a new registry installed via pkg server, then it's impossible for old Julia versions to update the registry because Julia before 1.4 doesn't know how to fetch new data. Hence, for users that frequently switch between multiple Julia versions, it is recommended to still use git-controlled registries.

    For the deployment of pkg server, please refer to PkgServer.jl.

    diff --git a/dev/registries/index.html b/dev/registries/index.html index 0a950dd93b..3590ef100e 100644 --- a/dev/registries/index.html +++ b/dev/registries/index.html @@ -27,4 +27,4 @@ import Pkg -Pkg.Registry.update()

    Creating and maintaining registries

    Pkg only provides client facilities for registries, rather than functionality to create or maintain them. However, Registrator.jl and LocalRegistry.jl provide ways to create and update registries, and RegistryCI.jl provides automated testing and merging functionality for maintaining a registry.

    +Pkg.Registry.update()

    Creating and maintaining registries

    Pkg only provides client facilities for registries, rather than functionality to create or maintain them. However, Registrator.jl and LocalRegistry.jl provide ways to create and update registries, and RegistryCI.jl provides automated testing and merging functionality for maintaining a registry.

    diff --git a/dev/repl/index.html b/dev/repl/index.html index d611f50bf8..9a21823f0e 100644 --- a/dev/repl/index.html +++ b/dev/repl/index.html @@ -226,4 +226,4 @@ [st|status] [-d|--diff] [-e|--extensions] [-p|--project] [pkgs...] [st|status] [-d|--diff] [-e|--extensions] [-m|--manifest] [pkgs...] [st|status] [-c|--compat] [pkgs...]

    Show the status of the current environment. Packages marked with ⌃ have new versions that may be installed, e.g. via pkg> up. Those marked with ⌅ have new versions available, but cannot be installed due to compatibility constraints. To see why use pkg> status --outdated which shows any packages that are not at their latest version and if any packages are holding them back.

    Use pkg> status --extensions to show dependencies with extensions and what extension dependencies of those that are currently loaded.

    In --project mode (default), the status of the project file is summarized. In --manifest mode the output also includes the recursive dependencies of added packages given in the manifest. If there are any packages listed as arguments the output will be limited to those packages. The --diff option will, if the environment is in a git repository, limit the output to the difference as compared to the last git commit. The --compat option alone shows project compat entries.

    Julia 1.8

    The ⌃ and ⌅ indicators were added in Julia 1.8. The --outdated and --compat options require at least Julia 1.8.

    - + diff --git a/dev/search/index.html b/dev/search/index.html index 5f77000281..6e7abe8219 100644 --- a/dev/search/index.html +++ b/dev/search/index.html @@ -1,2 +1,2 @@ -Search · Pkg.jl

    Loading search...

      +Search · Pkg.jl

      Loading search...

        diff --git a/dev/toml-files/index.html b/dev/toml-files/index.html index d527b0f54f..885fa206e9 100644 --- a/dev/toml-files/index.html +++ b/dev/toml-files/index.html @@ -45,4 +45,4 @@ [[deps.B]] uuid = "f41f7b98-334e-11e9-1257-49272045fb24" [[deps.B]] -uuid = "edca9bc6-334e-11e9-3554-9595dbb4349c"

        There is now an array of the two B packages, and the [deps] section for A has been expanded to be explicit about which B package A depends on.

        +uuid = "edca9bc6-334e-11e9-3554-9595dbb4349c"

        There is now an array of the two B packages, and the [deps] section for A has been expanded to be explicit about which B package A depends on.