update DEPOT_PATH and JULIA_DEPOT_PATH docs

Author: StefanKarpinski

base/initdefs.jl

@@ -41,6 +41,37 @@ isinteractive() = (is_interactive::Bool)
 
 ## package depots (registries, packages, environments) ##
 
+"""
+    DEPOT_PATH
+
+A stack of "depot" locations where the package manager, as well as Julia's code
+loading mechanisms, look for package registries, installed packages, named
+environments, repo clones, cached compiled package images, and configuration
+files. By default it includes:
+
+1. `~/.julia` where `~` is the user home as appropriate on the system;
+2. an architecture-specific shared system directory, e.g. `/usr/local/share/julia`;
+3. an architecture-independent shared system directory, e.g. `/usr/share/julia`.
+
+So `DEPOT_PATH` might be:
+```
+[joinpath(homedir(), ".julia"), "/usr/local/share/julia", "/usr/share/julia"]
+```
+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 repos 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.
+
+`DEPOT_PATH` is populated based on the [`JULIA_DEPOT_PATH`](@ref JULIA_DEPOT_PATH)
+environment variable if set.
+
+See also:
+[`JULIA_DEPOT_PATH`](@ref JULIA_DEPOT_PATH), and
+[Code Loading](@ref Code-Loading).
+"""
 const DEPOT_PATH = String[]
 
 function append_default_depot_path!(DEPOT_PATH)

doc/src/base/constants.md

@@ -6,6 +6,7 @@ Base.PROGRAM_FILE
 Base.ARGS
 Base.C_NULL
 Base.VERSION
+Base.DEPOT_PATH
 Base.LOAD_PATH
 Base.Sys.BINDIR
 Base.Sys.CPU_THREADS

doc/src/manual/environment-variables.md

@@ -91,12 +91,13 @@ the chapter on [Code Loading](@ref).
 
 The `JULIA_LOAD_PATH` environment variable is used to populate the global Julia
 [`LOAD_PATH`](@ref) variable, which determines which packages can be loaded via
-`import` and `using` (see [Code Loading](@ref)). Unlike the shell `PATH` variable,
-empty entries in `JULIA_LOAD_PATH` are expanded to the default value of `LOAD_PATH`,
-`["@", "@v#.#", "@stdlib"]` when populating `LOAD_PATH`. This allows easy appending,
-prepending, etc. of the load path value in shell scripts regardless of whether
-`JULIA_LOAD_PATH` is already set or not. For example, to prepend the directory
-`/foo/bar` to `LOAD_PATH` just do
+`import` and `using` (see [Code Loading](@ref)).
+
+Unlike the shell `PATH` variable, empty entries in `JULIA_LOAD_PATH` are expanded to
+the default value of `LOAD_PATH`, `["@", "@v#.#", "@stdlib"]` when populating
+`LOAD_PATH`. This allows easy appending, prepending, etc. of the load path value in
+shell scripts regardless of whether `JULIA_LOAD_PATH` is already set or not. For
+example, to prepend the directory `/foo/bar` to `LOAD_PATH` just do
 ```sh
 export JULIA_LOAD_PATH="/foo/bar:$JULIA_LOAD_PATH"
 ```
@@ -110,6 +111,32 @@ This behavior was chosen so that it would be possible to set an empty load path
 the environment variable. If you want the default load path, either unset the
 environment variable or if it must have a value, set it to the string `:`.
 
+### `JULIA_DEPOT_PATH`
+
+The `JULIA_DEPOT_PATH` environment variable is used to populate the global Julia
+[`DEPOT_PATH`](@ref) variable, which controls where the package manager, as well
+as Julia's code loading mechanisms, look for package registries, installed
+packages, named environments, repo clones, cached compiled package images, and
+configuration files.
+
+Unlike the shell `PATH` variable but similar to `JULIA_LOAD_PATH`, empty entries in
+`JULIA_DEPOT_PATH` are expanded to the default value of `DEPOT_PATH`. This allows
+easy appending, prepending, etc. of the depot path value in shell scripts regardless
+of whether `JULIA_DEPOT_PATH` is already set or not. For example, to prepend the
+directory `/foo/bar` to `DEPOT_PATH` just do
+```sh
+export JULIA_DEPOT_PATH="/foo/bar:$JULIA_DEPOT_PATH"
+```
+If the `JULIA_DEPOT_PATH` environment variable is already set, its old value will be
+prepended with `/foo/bar`. On the other hand, if `JULIA_DEPOT_PATH` is not set, then
+it will be set to `/foo/bar:` which will have the effect of prepending `/foo/bar` to
+the default depot path. If `JULIA_DEPOT_PATH` is set to the empty string, it expands
+to an empty `DEPOT_PATH` array. In other words, the empty string is interpreted as a
+zero-element array, not a one-element array of the empty string. This behavior was
+chosen so that it would be possible to set an empty depot path via the environment
+variable. If you want the default depot path, either unset the environment variable
+or if it must have a value, set it to the string `:`.
+
 ### `JULIA_HISTORY`
 
 The absolute path `REPL.find_hist_file()` of the REPL's history file. If
@@ -128,25 +155,9 @@ by default `1`, and larger values correspond to larger amounts of time.
 
 Suppose the value of `$JULIA_PKGRESOLVE_ACCURACY` is `n`. Then
 
-*   the number of pre-decimation iterations is `20*n`,
-*   the number of iterations between decimation steps is `10*n`, and
-*   at decimation steps, at most one in every `20*n` packages is decimated.
-
-### `JULIA_DEPOT_PATH`
-
-A stack of depot locations where the package manager, as well as Julia's code loading
-mechanisms, look for package registries, installed packages, named environments,
-repo clones, cached compiled package images, and configuration files.
-
-The depot path is controlled by Julia's `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 repos 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.
+* the number of pre-decimation iterations is `20*n`,
+* the number of iterations between decimation steps is `10*n`, and
+* at decimation steps, at most one in every `20*n` packages is decimated.
 
 
 ## External applications