Merge pull request #31010 from JuliaLang/sk/load-path-docs

complete, accurate documentation of LOAD_PATH and JULIA_LOAD_PATH

Author: StefanKarpinski

base/initdefs.jl

@@ -76,7 +76,36 @@ const DEFAULT_LOAD_PATH = ["@", "@v#.#", "@stdlib"]
     LOAD_PATH
 
 An array of paths for `using` and `import` statements to consider as project
-environments or package directories when loading code. See [Code Loading](@ref Code-Loading).
+environments or package directories when loading code. It is populated based on
+the [`JULIA_LOAD_PATH`](@ref JULIA_LOAD_PATH) environment variable if set;
+otherwise it defaults to `["@", "@v#.#", "@stdlib"]`. Entries starting with `@`
+have special meanings:
+
+- `@` refers to the "current active environment", the initial value of which is
+  initially determined by the [`JULIA_PROJECT`](@ref JULIA_PROJECT) environment
+  variable or the `--project` command-line option.
+
+- `@stdlib` expands to the absolute path of the current Julia installation's
+  standard library directory.
+
+- `@name` refers to a named environment, which are stored in depots (see
+  [`JULIA_DEPOT_PATH`](@ref JULIA_DEPOT_PATH)) under the `environments`
+  subdirectory. The user's named environments are stored in
+  `~/.julia/environments` so `@name` would refer to the environment in
+  `~/.julia/environments/name` if it exists and contains a `Project.toml` file.
+  If `name` contains `#` characters, then they are replaced with the major, minor
+  and patch components of the Julia version number. For example, if you are
+  running Julia 1.2 then `@v#.#` expands to `@v1.2` and will look for an
+  environment by that name, typically at `~/.julia/environments/v1.2`.
+
+The fully expanded value of `LOAD_PATH` that is searched for projects and packages
+can be seen by calling the `Base.load_path()` function.
+
+See also:
+[`JULIA_LOAD_PATH`](@ref JULIA_LOAD_PATH),
+[`JULIA_PROJECT`](@ref JULIA_PROJECT),
+[`JULIA_DEPOT_PATH`](@ref JULIA_DEPOT_PATH), and
+[Code Loading](@ref Code-Loading).
 """
 const LOAD_PATH = copy(DEFAULT_LOAD_PATH)
 const HOME_PROJECT = Ref{Union{String,Nothing}}(nothing)

doc/src/manual/environment-variables.md

@@ -75,27 +75,40 @@ and a global configuration search path of
 
 ### `JULIA_PROJECT`
 
-A directory path that points to the current Julia project. Setting this
-environment variable has the same effect as specifying the `--project` start-up
-option, but `--project` has higher precedence.  If the variable is set to `@.` then
-Julia tries to find a project directory that contains `Project.toml` or
-`JuliaProject.toml` file from the current directory and its parents.  See also
+A directory path that indicates which project should be the initial active project.
+Setting this environment variable has the same effect as specifying the `--project`
+start-up option, but `--project` has higher precedence. If the variable is set to `@.`
+then Julia tries to find a project directory that contains `Project.toml` or
+`JuliaProject.toml` file from the current directory and its parents. See also
 the chapter on [Code Loading](@ref).
 
 !!! note
 
-    `JULIA_PROJECT` must be defined before starting julia; defining it in `startup.jl` is too late in the startup process.
+    `JULIA_PROJECT` must be defined before starting julia; defining it in `startup.jl`
+    is too late in the startup process.
 
 ### `JULIA_LOAD_PATH`
 
-A separated list of absolute paths that are to be appended to the variable
-[`LOAD_PATH`](@ref). (In Unix-like systems, `:` is the path separator; in
-Windows systems, `;` is the path separator.) The `LOAD_PATH` variable is where
-[`Base.require`](@ref) and `Base.load_in_path()` look for code; it defaults to
-the absolute path
-`$JULIA_HOME/../share/julia/stdlib/v$(VERSION.major).$(VERSION.minor)` so that,
-e.g., version 0.7 of Julia on a Linux system with a Julia executable at
-`/bin/julia` will have a default `LOAD_PATH` of `/share/julia/stdlib/v0.7`.
+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
+```sh
+export JULIA_LOAD_PATH="/foo/bar:$JULIA_LOAD_PATH"
+```
+If the `JULIA_LOAD_PATH` environment variable is already set, its old value will be
+prepended with `/foo/bar`. On the other hand, if `JULIA_LOAD_PATH` is not set, then
+it will be set to `/foo/bar:` which will expand to a `LOAD_PATH` value of
+`["/foo/bar", "@", "@v#.#", "@stdlib"]`. If `JULIA_LOAD_PATH` is set to the empty
+string, it expands to an empty `LOAD_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 load path via
+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_HISTORY`
 

doc/src/manual/modules.md

@@ -183,19 +183,6 @@ look for `Utils` in `Parent`'s enclosing module rather than in `Parent` itself.
 
 Note that relative-import qualifiers are only valid in `using` and `import` statements.
 
-### Module file paths
-
-The global variable [`LOAD_PATH`](@ref) contains the directories Julia searches for modules when calling
-`require`. It can be extended using [`push!`](@ref):
-
-```julia
-push!(LOAD_PATH, "/Path/To/My/Module/")
-```
-
-Putting this statement in the file `~/.julia/config/startup.jl` will extend [`LOAD_PATH`](@ref) on
-every Julia startup. Alternatively, the module load path can be extended by defining the environment
-variable `JULIA_LOAD_PATH`.
-
 ### Namespace miscellanea
 
 If a name is qualified (e.g. `Base.sin`), then it can be accessed even if it is not exported.