From 2550925dd43a7e1589487edb43e42aad66408132 Mon Sep 17 00:00:00 2001 From: Stefan Karpinski Date: Thu, 7 Feb 2019 19:40:58 -0500 Subject: [PATCH 1/3] accurate documentation for JULIA_LOAD_PATH --- doc/src/manual/environment-variables.md | 41 ++++++++++++++++--------- 1 file changed, 27 insertions(+), 14 deletions(-) diff --git a/doc/src/manual/environment-variables.md b/doc/src/manual/environment-variables.md index 5bc6e619d4ab3..3deef381ffbb2 100644 --- a/doc/src/manual/environment-variables.md +++ b/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` From 6a4ccf3c5baa9e2efe22ed07d44d94190afa1854 Mon Sep 17 00:00:00 2001 From: Stefan Karpinski Date: Thu, 7 Feb 2019 19:45:38 -0500 Subject: [PATCH 2/3] Delete misleading section on "module file path" This was never accurate and doesn't really belong in the modules section since modules have nothing to do with the load path other than the fact that packages define a module and packages the load path affects what packages can be loaded. --- doc/src/manual/modules.md | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/doc/src/manual/modules.md b/doc/src/manual/modules.md index ef073cbe6db23..62a509edb8fff 100644 --- a/doc/src/manual/modules.md +++ b/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. From 695842f15b4298c3c29f062fecd209767ed778d8 Mon Sep 17 00:00:00 2001 From: Stefan Karpinski Date: Thu, 7 Feb 2019 20:12:24 -0500 Subject: [PATCH 3/3] complete documentation of LOAD_PATH --- base/initdefs.jl | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/base/initdefs.jl b/base/initdefs.jl index 2952b27e37920..56bb85af594fd 100644 --- a/base/initdefs.jl +++ b/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)