From c3984126a45e6da3f81150f44ba1d47affcf287d Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Sun, 22 Sep 2024 12:18:38 +0000 Subject: [PATCH] build based on ef9f76c --- dev/.documenter-siteinfo.json | 2 +- dev/api/index.html | 2 +- dev/artifacts/index.html | 2 +- dev/basedocs/index.html | 2 +- dev/compatibility/index.html | 2 +- dev/creating-packages/index.html | 2 +- dev/environments/index.html | 2 +- dev/getting-started/index.html | 2 +- dev/glossary/index.html | 2 +- dev/index.html | 2 +- dev/managing-packages/index.html | 2 +- dev/registries/index.html | 2 +- dev/repl/index.html | 2 +- dev/toml-files/index.html | 2 +- 14 files changed, 14 insertions(+), 14 deletions(-) diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 1752c8d7ed..7b421dd3e1 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.12.0-DEV.1233","generation_timestamp":"2024-09-22T12:16:28","documenter_version":"1.7.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.12.0-DEV.1233","generation_timestamp":"2024-09-22T12:17:08","documenter_version":"1.7.0"}} \ No newline at end of file diff --git a/dev/api/index.html b/dev/api/index.html index 7faf75d17f..3744fef1cc 100644 --- a/dev/api/index.html +++ b/dev/api/index.html @@ -82,4 +82,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.

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.

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

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.

diff --git a/dev/artifacts/index.html b/dev/artifacts/index.html index 07f2e67a60..ed9a9c65a8 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 6e270422c2..3c757f625a 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. Using only 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. Using only 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 a354300914..54707d3a91 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 2e51fdb891..c086f9ce69 100644 --- a/dev/creating-packages/index.html +++ b/dev/creating-packages/index.html @@ -179,4 +179,4 @@ end end

  • Make the following change in the conditionally-loaded code in ContourExt.jl:

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

  • Add Requires to [weakdeps] in your Project.toml file, so that it is listed in both [deps] and [weakdeps]. Julia 1.9+ knows to not install it as a regular dependency, whereas earlier versions will consider it a dependency.

    • 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 being 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 rules

    Package names should be sensible to most Julia users, even to those who are not domain experts. The following rules 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.

      • It's ok to say USA if you're talking about the USA.
      • It's not ok to say PMA, even if you're talking about positive mental attitude.

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

      • It is usually clear from context and to your users that the package is a Julia package.
      • Package names already have a .jl extension, which communicates to users that Package.jl is a Julia package.
      • Having Julia in the name can imply that the package is connected to, or endorsed by, contributors to the Julia language itself.

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

      • DataFrames provides the DataFrame type.
      • BloomFilters provides the BloomFilter type.
      • In contrast, JuliaParser provides no new type, but instead new functionality in the JuliaParser.parse() function.

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

      • RandomMatrices is a less ambiguous name than RndMat or RMT, even though the latter are shorter.

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

      • Julia does not have a single comprehensive plotting package. Instead, Gadfly, PyPlot, Winston and other packages each implement a unique approach based on a particular design philosophy.
      • In contrast, SortingAlgorithms provides a consistent interface to use many well-established sorting algorithms.

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

      • CPLEX.jl wraps the CPLEX library, which can be identified easily in a web search.
      • MATLAB.jl provides an interface to call the MATLAB engine from within Julia.

    7. Avoid naming a package closely to an existing package

      • Websocket is too close to WebSockets and can be confusing to users. Rather use a new name such as SimpleWebsockets.

    8. Avoid using a distinctive name that is already in use in a well known, unrelated project.

      • Don't use the names Tkinter.jl, TkinterGUI.jl, etc. for a package that is unrelated to the popular tkinter python package, even if it provides bindings to Tcl/Tk. A package name of Tkinter.jl would only be appropriate if the package used Python's library to accomplish its work or was spearheaded by the same community of developers.
      • It's okay to name a package HTTP.jl even though it is unrelated to the popular rust crate http because in most usages the name "http" refers to the hypertext transfer protocol, not to the http rust crate.
      • It's okay to name a package OpenSSL.jl if it provides an interface to the OpenSSL library, even without explicit affiliation with the creators of the OpenSSL (provided there's no copyright or trademark infringement etc.)

    9. Packages should follow the Stylistic Conventions.

      • The package name begin with a capital letter and word separation is shown with upper camel case
      • Packages that provide the functionality of a project from another language should use the Julia convention
      • Packages that provide pre-built libraries and executables can keep orignal name, but should get _jllas a suffix. For example pandoc_jll wraps pandoc. However, note that the generation and release of most JLL packages is handled by the Yggdrasil system.

    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 being 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 rules

    Package names should be sensible to most Julia users, even to those who are not domain experts. The following rules 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.

      • It's ok to say USA if you're talking about the USA.
      • It's not ok to say PMA, even if you're talking about positive mental attitude.

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

      • It is usually clear from context and to your users that the package is a Julia package.
      • Package names already have a .jl extension, which communicates to users that Package.jl is a Julia package.
      • Having Julia in the name can imply that the package is connected to, or endorsed by, contributors to the Julia language itself.

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

      • DataFrames provides the DataFrame type.
      • BloomFilters provides the BloomFilter type.
      • In contrast, JuliaParser provides no new type, but instead new functionality in the JuliaParser.parse() function.

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

      • RandomMatrices is a less ambiguous name than RndMat or RMT, even though the latter are shorter.

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

      • Julia does not have a single comprehensive plotting package. Instead, Gadfly, PyPlot, Winston and other packages each implement a unique approach based on a particular design philosophy.
      • In contrast, SortingAlgorithms provides a consistent interface to use many well-established sorting algorithms.

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

      • CPLEX.jl wraps the CPLEX library, which can be identified easily in a web search.
      • MATLAB.jl provides an interface to call the MATLAB engine from within Julia.

    7. Avoid naming a package closely to an existing package

      • Websocket is too close to WebSockets and can be confusing to users. Rather use a new name such as SimpleWebsockets.

    8. Avoid using a distinctive name that is already in use in a well known, unrelated project.

      • Don't use the names Tkinter.jl, TkinterGUI.jl, etc. for a package that is unrelated to the popular tkinter python package, even if it provides bindings to Tcl/Tk. A package name of Tkinter.jl would only be appropriate if the package used Python's library to accomplish its work or was spearheaded by the same community of developers.
      • It's okay to name a package HTTP.jl even though it is unrelated to the popular rust crate http because in most usages the name "http" refers to the hypertext transfer protocol, not to the http rust crate.
      • It's okay to name a package OpenSSL.jl if it provides an interface to the OpenSSL library, even without explicit affiliation with the creators of the OpenSSL (provided there's no copyright or trademark infringement etc.)

    9. Packages should follow the Stylistic Conventions.

      • The package name begin with a capital letter and word separation is shown with upper camel case
      • Packages that provide the functionality of a project from another language should use the Julia convention
      • Packages that provide pre-built libraries and executables can keep orignal name, but should get _jllas a suffix. For example pandoc_jll wraps pandoc. However, note that the generation and release of most JLL packages is handled by the Yggdrasil system.

    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 edfc8fc257..70d6281ad3 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.

    The indicators next to the package names displayed during precompilation indicate the status of that package's precompilation.

    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.

    The indicators next to the package names displayed during precompilation indicate the status of that package's precompilation.

    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 fe14ab73a4..00e0efc508 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. Using only 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. Using only 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 b7687b5719..1f72b37ba5 100644 --- a/dev/glossary/index.html +++ b/dev/glossary/index.html @@ -1,2 +1,2 @@ -9. Glossary · Pkg.jl
    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. The file name may also be suffixed by -v{major}.{minor}.toml which julia will prefer if the version matches VERSION, allowing multiple environments to be maintained for different julia versions.

    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 set and change the global configurations of packages it depends on. Packages, on the other hand, may not change the global state of their dependencies 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
    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. The file name may also be suffixed by -v{major}.{minor}.toml which julia will prefer if the version matches VERSION, allowing multiple environments to be maintained for different julia versions.

    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 set and change the global configurations of packages it depends on. Packages, on the other hand, may not change the global state of their dependencies 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 b08f91fe60..2d16dfdf24 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -1. Introduction · Pkg.jl
    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
    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 60ff3a3229..8acf5e8420 100644 --- a/dev/managing-packages/index.html +++ b/dev/managing-packages/index.html @@ -156,4 +156,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 b270aec9ff..12579559cd 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 edf7942ed8..2c723e4a05 100644 --- a/dev/repl/index.html +++ b/dev/repl/index.html @@ -229,4 +229,4 @@ [st|status] [-d|--diff] [--workspace] [-e|--extensions] [-p|--project] [pkgs...] [st|status] [-d|--diff] [--workspace] [-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. The --workspace option shows the (merged) status of packages in the workspace.

    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/toml-files/index.html b/dev/toml-files/index.html index 96b2e51e2e..62c791d537 100644 --- a/dev/toml-files/index.html +++ b/dev/toml-files/index.html @@ -48,4 +48,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.