From 00c94b3d9c891fea5a910592ba0bd130f41c5ad0 Mon Sep 17 00:00:00 2001 From: Kiaran B Dave Date: Fri, 20 Jan 2017 14:45:28 -0500 Subject: [PATCH 01/11] documentation for environment variables --- doc/src/index.md | 1 + doc/src/manual/environment-variables.md | 138 ++++++++++++++++++++++++ doc/src/manual/index.md | 1 + 3 files changed, 140 insertions(+) create mode 100644 doc/src/manual/environment-variables.md diff --git a/doc/src/index.md b/doc/src/index.md index a08246094d703..e5bffa064c27d 100644 --- a/doc/src/index.md +++ b/doc/src/index.md @@ -28,6 +28,7 @@ * [Running External Programs](@ref) * [Calling C and Fortran Code](@ref) * [Handling Operating System Variation](@ref) + * [Handling Operating System Variation](@ref) * [Interacting With Julia](@ref) * [Embedding Julia](@ref) * [Packages](@ref) diff --git a/doc/src/manual/environment-variables.md b/doc/src/manual/environment-variables.md new file mode 100644 index 0000000000000..476fbd9e5b227 --- /dev/null +++ b/doc/src/manual/environment-variables.md @@ -0,0 +1,138 @@ +# Environment Variables in Julia + +The environment variables that Julia uses generally start with `JULIA`. If [`Base.versioninfo()`](https://github.com/JuliaLang/julia/blob/master/base/interactiveutil.jl#L247) is called with `verbose` equal to `true`, then the output will list all environment variables for which `JULIA` appears in the name. + +## File locations + +### `JULIA_HOME` +The absolute path of the directory containing the Julia executable, which sets the global variable [`Base.JULIA_HOME`](https://github.com/JuliaLang/julia/blob/master/base/initdefs.jl#L90). If `$JULIA_HOME` is not set, then `Base.JULIA_HOME` defaults to its compile-time value. + +The executable itself is one of +``` +$JULIA_HOME/julia +$JULIA_HOME/julia-debug +``` +by default. + +The global variable [`Base.DATAROOTDIR`](https://github.com/JuliaLang/julia/blob/master/base/Makefile#L62) determines a relative path from `Base.JULIA_HOME` to the data directory associated with Julia; then the directory. Then the path +``` +$JULIA_HOME/$DATAROOTDIR/julia/base +``` +determines the directory in which Julia initially searches for source files (via [`Base.find_source_file()`](https://github.com/JuliaLang/julia/blob/master/base/loading.jl#L124)). + +Likewise, the global variable [`Base.SYSCONFDIR`](https://github.com/JuliaLang/julia/blob/master/base/Makefile#L61) internal variable determines a relative path to the configuration file directory. Then Julia searches for a `juliarc.jl` file at + +``` +$JULIA_HOME/$SYSCONFDIR/julia/juliarc.jl +$JULIA_HOME/../etc/julia/juliarc.jl +``` +by default (via [`Base.load_juliarc()`](https://github.com/JuliaLang/julia/blob/master/base/client.jl#L316) ). + +For example, a Linux installation with a Julia executable located at `/bin/julia`, a `DATAROOTDIR` of `../share`, and a `SYSCONFDIR` of `../etc` will have `JULIA_HOME` set to `/bin`, a source-file search path of +``` +/share/julia/base +``` +and a global configuration search path of +``` +/etc/julia/juliarc.jl +``` + +### `JULIA_LOAD_PATH` +A separated list of absolute paths that are to be appended to the variable [`Base.LOAD_PATH`](https://github.com/JuliaLang/julia/blob/master/base/initdefs.jl#L35). (In Unix-like systems, the path separator is `:`; in windows systems, the path separator is `;`.) The `Base.LOAD_PATH` variable is where [`Base.require()`](https://github.com/JuliaLang/julia/blob/master/base/require.jl#L41) and [`Base.load_in_path()`](https://github.com/JuliaLang/julia/blob/master/base/require.jl#L6) look for code; it defaults to the absolute paths + +``` +$JULIA_HOME/../local/share/julia/site/v$(Base.VERSION.major).$(Base.VERSION.minor) +$JULIA_HOME/../share/julia/site/v$(Base.VERSION.major).$(Base.VERSION.minor) +``` +so that, e.g., version 0.5 of Julia on a Linux system with a Julia executable at `/bin/julia` will have a default `Base.LOAD_PATH` of +``` +/local/share/julia/site/v0.5 +/share/julia/site/v0.5 +``` + +### `JULIA_PKGDIR` +The path of the parent directory [`Dir._pkgroot()`](https://github.com/JuliaLang/julia/blob/master/base/pkg/dir.jl#L10) for the version-specific Julia package repositories. If the path is relative, then it is taken with respect to the working directory. If `JULIA_PKGIR` is not specified, then `_pkgroot()` defaults to +``` +$HOME/.julia +``` +Then the repository location [`Pkg.dir()`](https://github.com/JuliaLang/julia/blob/master/base/pkg/pkg.jl#L50) for a given Julia version is +``` +$JULIA_PKGDIR/v$(Base.VERSION.major).$(Base.VERSION.minor) +``` + +For example, for a Linux user whose home directory is `/home/alice`, the directory containing the package repositories would by default be +``` +/home/alice/.julia +``` +and the package repository for version 0.5 of Julia would be +``` +/home/alice/.julia/v0.5 +``` + +### `JULIA_HISTORY` +The absolute path [`Base.find_hist_file()`](https://github.com/JuliaLang/julia/blob/master/base/REPL.jl#L615) of the REPL's history file. If `JULIA_HISTORY` is not specified, then `Base.find_hist_file()` defaults to +``` +$HOME/.julia_history +``` + +### `JULIA_PKGRESOLVE_ACCURACY` +A positive `Int` that determines how much time the max-sum subroutine [`MaxSum.maxsum()`](https://github.com/JuliaLang/julia/blob/master/base/pkg/resolve/maxsum.jl#L442) of the package dependency resolver [`Resolve.resolve()`](https://github.com/JuliaLang/julia/blob/master/base/pkg/resolve.jl#L15) will devote to attempting satisfying constraints before giving up: this value is 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. + +## External applications + +### `JULIA_SHELL` +The absolute path of the shell with which Julia should execute external commands (via [`Base.repl_cmd()`](https://github.com/JuliaLang/julia/blob/master/base/client.jl#L91)). Defaults to the environment variable `$SHELL`, and falls back to `/bin/sh` if `$SHELL` is unset. + +*Note:* the `fish` shell is unsupported. + +### `JULIA_EDITOR`, `VISUAL`, `EDITOR` +The editor returned by [`Base.editor()`](https://github.com/JuliaLang/julia/blob/master/base/interactiveutil.jl#L12) and used in, e.g., [`Base.edit()`](https://github.com/JuliaLang/julia/blob/master/base/interactiveutil.jl#L33). `JULIA_EDITOR` takes precedence over `VISUAL`, which in turn takes precedence over `EDITOR`. If none of these environment variables is set, then the editor is taken to be `open` on Windows and OS X, or `/etc/alternatives/editor` if it exists, or `emacs` otherwise. + +**Warning:** `JULIA_EDITOR` is *not* used in the determination of the editor for [`Pkg.edit()`](https://github.com/JuliaLang/julia/blob/master/base/pkg/entry.jl#L36): this function checks `VISUAL` and `EDITOR` alone. + +## Parallelization + +### `JULIA_CPU_CORES` +Overrides the global variable [`Sys.CPU_CORES`](https://github.com/JuliaLang/julia/blob/master/base/sysinfo.jl#L62), the number of logical CPU cores available. + +### `JULIA_WORKER_TIMEOUT` +A `Float64` that sets the value of [`Base.worker_timeout()`](https://github.com/JuliaLang/julia/blob/master/base/multi.jl#L1566) (default: `60.0`). This function gives the number of a seconds a worker process will wait for a master process to establish a connection before dying. + +## REPL formatting +Environment variables that determine how REPL output should be formatted at the terminal. Generally, these variables should be set to [ANSI terminal escape sequences](http://ascii-table.com/ansi-escape-sequences.php). + +### `JULIA_ERROR_COLOR` +The formatting [`Base.error_color()`](https://github.com/JuliaLang/julia/blob/master/base/client.jl#L80) (default: light red, `"\033[91m"`) that errors should have at the terminal. + +### `JULIA_WARN_COLOR` +The formatting [`Base.warn_color()`](https://github.com/JuliaLang/julia/blob/master/base/client.jl#L81) (default: yellow, `"\033[93m"`) that warnings should have at the terminal. + +### `JULIA_INFO_COLOR` +The formatting [`Base.info_color()`](https://github.com/JuliaLang/julia/blob/master/base/client.jl#L82) (default: cyan, `"\033[36m"`) that info should have at the terminal. + +### `JULIA_INPUT_COLOR` +The formatting [`Base.input_color()`](https://github.com/JuliaLang/julia/blob/master/base/client.jl#L85) (default: normal, `"\033[0m"`) that input should have at the terminal. + +*Note:* Input is hardcoded to be bold (`"\033[1m"`). + +### `JULIA_ANSWER_COLOR` +The formatting [`Base.answer_color()`](https://github.com/JuliaLang/julia/blob/master/base/client.jl#L86) (default: normal, `"\033[0m"`) that output should have at the terminal. + +*Note:* Output is hardcoded to be bold (`"\033[1m"`). + +### `JULIA_STACKFRAME_LINEINFO_COLOR` +The formatting [`Base.stackframe_lineinfo_color()`](https://github.com/JuliaLang/julia/blob/master/base/client.jl#L88) (default: bold, `"\033[1m"`) that line info should have during a stack trace at the terminal. + +### `JULIA_STACKFRAME_FUNCTION_COLOR` +The formatting [`Base.stackframe_function_color()`](https://github.com/JuliaLang/julia/blob/master/base/client.jl#L89) (default: bold, `"\033[1m"`) that function calls should have during a stack trace at the terminal. + +## Debugging + +### `JULIA_DEBUG_LOADING` +If set, then Julia prints detailed information about the cache in the loading process of [`Base.require()`](https://github.com/JuliaLang/julia/blob/master/base/loading.jl#L373). diff --git a/doc/src/manual/index.md b/doc/src/manual/index.md index c516ad473e0e8..37a8b0b67862e 100644 --- a/doc/src/manual/index.md +++ b/doc/src/manual/index.md @@ -26,6 +26,7 @@ * [Running External Programs](@ref) * [Calling C and Fortran Code](@ref) * [Handling Operating System Variation](@ref) + * [Environment Variables](@ref) * [Interacting With Julia](@ref) * [Embedding Julia](@ref) * [Packages](@ref) From d73ce9a4d6accd303e5dc0ad3fb7fd388a8be355 Mon Sep 17 00:00:00 2001 From: Kiaran B Dave Date: Fri, 20 Jan 2017 14:50:14 -0500 Subject: [PATCH 02/11] small typo --- doc/src/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/src/index.md b/doc/src/index.md index e5bffa064c27d..5e82bb3a484a6 100644 --- a/doc/src/index.md +++ b/doc/src/index.md @@ -28,7 +28,7 @@ * [Running External Programs](@ref) * [Calling C and Fortran Code](@ref) * [Handling Operating System Variation](@ref) - * [Handling Operating System Variation](@ref) + * [Environment Variables](@ref) * [Interacting With Julia](@ref) * [Embedding Julia](@ref) * [Packages](@ref) From 248a2649a14e34e156177e91d3ab129851857c0d Mon Sep 17 00:00:00 2001 From: Kiaran B Dave Date: Fri, 20 Jan 2017 14:55:17 -0500 Subject: [PATCH 03/11] forgot about make.jl --- doc/make.jl | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/make.jl b/doc/make.jl index 956c7707c87ec..132153b0b668a 100644 --- a/doc/make.jl +++ b/doc/make.jl @@ -46,6 +46,7 @@ const PAGES = [ "manual/running-external-programs.md", "manual/calling-c-and-fortran-code.md", "manual/handling-operating-system-variation.md", + "manual/environment-variables.md", "manual/interacting-with-julia.md", "manual/embedding.md", "manual/packages.md", From 797eaf026a76d7feec70b8e73284fefe0ed34bc9 Mon Sep 17 00:00:00 2001 From: Kiaran B Dave Date: Fri, 20 Jan 2017 16:31:09 -0500 Subject: [PATCH 04/11] Line width to 80 characters; strip trailing spaces; line breaks after h3 --- doc/src/manual/environment-variables.md | 160 +++++++++++++++++------- 1 file changed, 114 insertions(+), 46 deletions(-) diff --git a/doc/src/manual/environment-variables.md b/doc/src/manual/environment-variables.md index 476fbd9e5b227..ab1f69b89d7b5 100644 --- a/doc/src/manual/environment-variables.md +++ b/doc/src/manual/environment-variables.md @@ -1,34 +1,42 @@ # Environment Variables in Julia -The environment variables that Julia uses generally start with `JULIA`. If [`Base.versioninfo()`](https://github.com/JuliaLang/julia/blob/master/base/interactiveutil.jl#L247) is called with `verbose` equal to `true`, then the output will list all environment variables for which `JULIA` appears in the name. +The environment variables that Julia uses generally start with `JULIA`. If +`Base.versioninfo()` is called with `verbose` equal to `true`, then the output +will list all environment variables for which `JULIA` appears in the name. ## File locations ### `JULIA_HOME` -The absolute path of the directory containing the Julia executable, which sets the global variable [`Base.JULIA_HOME`](https://github.com/JuliaLang/julia/blob/master/base/initdefs.jl#L90). If `$JULIA_HOME` is not set, then `Base.JULIA_HOME` defaults to its compile-time value. -The executable itself is one of -``` -$JULIA_HOME/julia -$JULIA_HOME/julia-debug -``` +The absolute path of the directory containing the Julia +executable, which sets the global variable [`Base.JULIA_HOME`](@ref). If +`$JULIA_HOME` is not set, then `Base.JULIA_HOME` defaults to its compile-time +value. + +The executable itself is one of +``` +$JULIA_HOME/julia $JULIA_HOME/julia-debug +``` by default. -The global variable [`Base.DATAROOTDIR`](https://github.com/JuliaLang/julia/blob/master/base/Makefile#L62) determines a relative path from `Base.JULIA_HOME` to the data directory associated with Julia; then the directory. Then the path +The global variable `Base.DATAROOTDIR` determines a relative path from +`Base.JULIA_HOME` to the data directory associated with Julia. Then the path ``` $JULIA_HOME/$DATAROOTDIR/julia/base ``` -determines the directory in which Julia initially searches for source files (via [`Base.find_source_file()`](https://github.com/JuliaLang/julia/blob/master/base/loading.jl#L124)). - -Likewise, the global variable [`Base.SYSCONFDIR`](https://github.com/JuliaLang/julia/blob/master/base/Makefile#L61) internal variable determines a relative path to the configuration file directory. Then Julia searches for a `juliarc.jl` file at +determines the directory in which Julia +initially searches for source files (via `Base.find_source_file()`). +Likewise, the global variable `Base.SYSCONFDIR` determines a relative path to +the configuration file directory. Then Julia searches for a `juliarc.jl` file at ``` -$JULIA_HOME/$SYSCONFDIR/julia/juliarc.jl -$JULIA_HOME/../etc/julia/juliarc.jl +$JULIA_HOME/$SYSCONFDIR/julia/juliarc.jl $JULIA_HOME/../etc/julia/juliarc.jl ``` -by default (via [`Base.load_juliarc()`](https://github.com/JuliaLang/julia/blob/master/base/client.jl#L316) ). +by default (via `Base.load_juliarc()`). -For example, a Linux installation with a Julia executable located at `/bin/julia`, a `DATAROOTDIR` of `../share`, and a `SYSCONFDIR` of `../etc` will have `JULIA_HOME` set to `/bin`, a source-file search path of +For example, a Linux installation with a Julia executable located at +`/bin/julia`, a `DATAROOTDIR` of `../share`, and a `SYSCONFDIR` of `../etc` will +have `JULIA_HOME` set to `/bin`, a source-file search path of ``` /share/julia/base ``` @@ -38,29 +46,39 @@ and a global configuration search path of ``` ### `JULIA_LOAD_PATH` -A separated list of absolute paths that are to be appended to the variable [`Base.LOAD_PATH`](https://github.com/JuliaLang/julia/blob/master/base/initdefs.jl#L35). (In Unix-like systems, the path separator is `:`; in windows systems, the path separator is `;`.) The `Base.LOAD_PATH` variable is where [`Base.require()`](https://github.com/JuliaLang/julia/blob/master/base/require.jl#L41) and [`Base.load_in_path()`](https://github.com/JuliaLang/julia/blob/master/base/require.jl#L6) look for code; it defaults to the absolute paths +A separated list of absolute paths that are to be appended +to the variable [`Base.LOAD_PATH`](@ref). (In Unix-like systems, the path +separator is `:`; in Windows systems, the path separator is `;`.) The +`Base.LOAD_PATH` variable is where [`Base.require()`](@ref Base.require) and +`Base.load_in_path()` look for code; it defaults to the absolute paths ``` $JULIA_HOME/../local/share/julia/site/v$(Base.VERSION.major).$(Base.VERSION.minor) $JULIA_HOME/../share/julia/site/v$(Base.VERSION.major).$(Base.VERSION.minor) ``` -so that, e.g., version 0.5 of Julia on a Linux system with a Julia executable at `/bin/julia` will have a default `Base.LOAD_PATH` of +so that, e. g., version 0.5 of Julia on a Linux system with a Julia executable at +`/bin/julia` will have a default `Base.LOAD_PATH` of ``` -/local/share/julia/site/v0.5 -/share/julia/site/v0.5 +/local/share/julia/site/v0.5 /share/julia/site/v0.5 ``` ### `JULIA_PKGDIR` -The path of the parent directory [`Dir._pkgroot()`](https://github.com/JuliaLang/julia/blob/master/base/pkg/dir.jl#L10) for the version-specific Julia package repositories. If the path is relative, then it is taken with respect to the working directory. If `JULIA_PKGIR` is not specified, then `_pkgroot()` defaults to + +The path of the parent directory `Dir._pkgroot()` for the +version-specific Julia package repositories. If the path is relative, then it is +taken with respect to the working directory. If `JULIA_PKGDIR` is not specified, +then `_pkgroot()` defaults to ``` $HOME/.julia ``` -Then the repository location [`Pkg.dir()`](https://github.com/JuliaLang/julia/blob/master/base/pkg/pkg.jl#L50) for a given Julia version is +Then the repository location +[`Base.Pkg.dir()`](@ref Base.Pkg.dir) for a given Julia version is ``` $JULIA_PKGDIR/v$(Base.VERSION.major).$(Base.VERSION.minor) ``` -For example, for a Linux user whose home directory is `/home/alice`, the directory containing the package repositories would by default be +For example, for a Linux user whose home directory is `/home/alice`, the +directory containing the package repositories would by default be ``` /home/alice/.julia ``` @@ -70,69 +88,119 @@ and the package repository for version 0.5 of Julia would be ``` ### `JULIA_HISTORY` -The absolute path [`Base.find_hist_file()`](https://github.com/JuliaLang/julia/blob/master/base/REPL.jl#L615) of the REPL's history file. If `JULIA_HISTORY` is not specified, then `Base.find_hist_file()` defaults to + +The absolute path `Base.find_hist_file()` of the REPL's +history file. If `JULIA_HISTORY` is not specified, then `Base.find_hist_file()` +defaults to ``` $HOME/.julia_history ``` ### `JULIA_PKGRESOLVE_ACCURACY` -A positive `Int` that determines how much time the max-sum subroutine [`MaxSum.maxsum()`](https://github.com/JuliaLang/julia/blob/master/base/pkg/resolve/maxsum.jl#L442) of the package dependency resolver [`Resolve.resolve()`](https://github.com/JuliaLang/julia/blob/master/base/pkg/resolve.jl#L15) will devote to attempting satisfying constraints before giving up: this value is by default `1`, and larger values correspond to larger amounts of time. + +A positive `Int` that determines how much time +the max-sum subroutine `MaxSum.maxsum()` of the package dependency resolver +[`Base.Pkg.resolve()`](@ref Base.Pkg.resolve) will devote to attempting +satisfying constraints before giving up: this value is 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. +* at decimation steps, at most one in every `20*n` packages is decimated. ## External applications ### `JULIA_SHELL` -The absolute path of the shell with which Julia should execute external commands (via [`Base.repl_cmd()`](https://github.com/JuliaLang/julia/blob/master/base/client.jl#L91)). Defaults to the environment variable `$SHELL`, and falls back to `/bin/sh` if `$SHELL` is unset. + +The absolute path of the shell with which Julia should execute +external commands (via `Base.repl_cmd()`). Defaults to the environment variable +`$SHELL`, and falls back to `/bin/sh` if `$SHELL` is unset. *Note:* the `fish` shell is unsupported. ### `JULIA_EDITOR`, `VISUAL`, `EDITOR` -The editor returned by [`Base.editor()`](https://github.com/JuliaLang/julia/blob/master/base/interactiveutil.jl#L12) and used in, e.g., [`Base.edit()`](https://github.com/JuliaLang/julia/blob/master/base/interactiveutil.jl#L33). `JULIA_EDITOR` takes precedence over `VISUAL`, which in turn takes precedence over `EDITOR`. If none of these environment variables is set, then the editor is taken to be `open` on Windows and OS X, or `/etc/alternatives/editor` if it exists, or `emacs` otherwise. -**Warning:** `JULIA_EDITOR` is *not* used in the determination of the editor for [`Pkg.edit()`](https://github.com/JuliaLang/julia/blob/master/base/pkg/entry.jl#L36): this function checks `VISUAL` and `EDITOR` alone. +The editor returned by `Base.editor()` +and used in, e.g., [`Base.edit()`](@ref Base.edit). + +`JULIA_EDITOR` takes +precedence over `VISUAL`, which in turn takes precedence over `EDITOR`. If none +of these environment variables is set, then the editor is taken to be `open` on +Windows and OS X, or `/etc/alternatives/editor` if it exists, or `emacs` +otherwise. + +**Warning:** `JULIA_EDITOR` is *not* used in the determination of the editor for +[`Base.Pkg.edit()`](@ref Base.Pkg.edit): this function checks `VISUAL` and +`EDITOR` alone. ## Parallelization ### `JULIA_CPU_CORES` -Overrides the global variable [`Sys.CPU_CORES`](https://github.com/JuliaLang/julia/blob/master/base/sysinfo.jl#L62), the number of logical CPU cores available. + +Overrides the global variable +[`Base.Sys.CPU_CORES`](@ref), the number of logical CPU cores available. ### `JULIA_WORKER_TIMEOUT` -A `Float64` that sets the value of [`Base.worker_timeout()`](https://github.com/JuliaLang/julia/blob/master/base/multi.jl#L1566) (default: `60.0`). This function gives the number of a seconds a worker process will wait for a master process to establish a connection before dying. + +A `Float64` that sets the value of +`Base.worker_timeout()` (default: `60.0`). This function gives the number of +a seconds a worker process will wait for a master process to establish +a connection before dying. ## REPL formatting -Environment variables that determine how REPL output should be formatted at the terminal. Generally, these variables should be set to [ANSI terminal escape sequences](http://ascii-table.com/ansi-escape-sequences.php). -### `JULIA_ERROR_COLOR` -The formatting [`Base.error_color()`](https://github.com/JuliaLang/julia/blob/master/base/client.jl#L80) (default: light red, `"\033[91m"`) that errors should have at the terminal. +Environment variables that determine how REPL output should +be formatted at the terminal. Generally, these variables should be set to [ANSI +terminal escape sequences](http://ascii-table.com/ansi-escape-sequences.php). +The Julia base package provides a high-level interface with much of the same +functionality: see the section on [Interacting With Julia](@ref). + +### `JULIA_ERROR_COLOR` + +The formatting `Base.error_color()` (default: light +red, `"\033[91m"`) that errors should have at the terminal. + +### `JULIA_WARN_COLOR` + +The formatting `Base.warn_color()` (default: yellow, +`"\033[93m"`) that warnings should have at the terminal. -### `JULIA_WARN_COLOR` -The formatting [`Base.warn_color()`](https://github.com/JuliaLang/julia/blob/master/base/client.jl#L81) (default: yellow, `"\033[93m"`) that warnings should have at the terminal. +### `JULIA_INFO_COLOR` -### `JULIA_INFO_COLOR` -The formatting [`Base.info_color()`](https://github.com/JuliaLang/julia/blob/master/base/client.jl#L82) (default: cyan, `"\033[36m"`) that info should have at the terminal. +The formatting `Base.info_color()` (default: cyan, +`"\033[36m"`) that info should have at the terminal. -### `JULIA_INPUT_COLOR` -The formatting [`Base.input_color()`](https://github.com/JuliaLang/julia/blob/master/base/client.jl#L85) (default: normal, `"\033[0m"`) that input should have at the terminal. +### `JULIA_INPUT_COLOR` + +The formatting `Base.input_color()` (default: normal, +`"\033[0m"`) that input should have at the terminal. *Note:* Input is hardcoded to be bold (`"\033[1m"`). -### `JULIA_ANSWER_COLOR` -The formatting [`Base.answer_color()`](https://github.com/JuliaLang/julia/blob/master/base/client.jl#L86) (default: normal, `"\033[0m"`) that output should have at the terminal. +### `JULIA_ANSWER_COLOR` + +The formatting `Base.answer_color()` (default: +normal, `"\033[0m"`) that output should have at the terminal. *Note:* Output is hardcoded to be bold (`"\033[1m"`). -### `JULIA_STACKFRAME_LINEINFO_COLOR` -The formatting [`Base.stackframe_lineinfo_color()`](https://github.com/JuliaLang/julia/blob/master/base/client.jl#L88) (default: bold, `"\033[1m"`) that line info should have during a stack trace at the terminal. +### `JULIA_STACKFRAME_LINEINFO_COLOR` + +The formatting +`Base.stackframe_lineinfo_color()` (default: bold, `"\033[1m"`) that line info +should have during a stack trace at the terminal. -### `JULIA_STACKFRAME_FUNCTION_COLOR` -The formatting [`Base.stackframe_function_color()`](https://github.com/JuliaLang/julia/blob/master/base/client.jl#L89) (default: bold, `"\033[1m"`) that function calls should have during a stack trace at the terminal. +### `JULIA_STACKFRAME_FUNCTION_COLOR` + +The formatting +`Base.stackframe_function_color()` (default: bold, `"\033[1m"`) that function +calls should have during a stack trace at the terminal. ## Debugging ### `JULIA_DEBUG_LOADING` -If set, then Julia prints detailed information about the cache in the loading process of [`Base.require()`](https://github.com/JuliaLang/julia/blob/master/base/loading.jl#L373). + +If set, then Julia prints detailed information about +the cache in the loading process of [`Base.require()`](@ref Base.require). From 3e9d96e2e46a4768d0145822931a9ca193ca46fb Mon Sep 17 00:00:00 2001 From: Kiaran B Dave Date: Sat, 21 Jan 2017 00:34:35 -0500 Subject: [PATCH 05/11] added threading/debugging entries and cross-references. --- doc/src/manual/environment-variables.md | 139 +++++++++++++++++++----- 1 file changed, 114 insertions(+), 25 deletions(-) diff --git a/doc/src/manual/environment-variables.md b/doc/src/manual/environment-variables.md index ab1f69b89d7b5..cd71139cc2ce4 100644 --- a/doc/src/manual/environment-variables.md +++ b/doc/src/manual/environment-variables.md @@ -1,8 +1,9 @@ # Environment Variables in Julia The environment variables that Julia uses generally start with `JULIA`. If -`Base.versioninfo()` is called with `verbose` equal to `true`, then the output -will list all environment variables for which `JULIA` appears in the name. +[`Base.versioninfo()`](@ref) is called with `verbose` equal to `true`, then the +output will list all environment variables for which `JULIA` appears in the name. + ## File locations @@ -14,13 +15,13 @@ executable, which sets the global variable [`Base.JULIA_HOME`](@ref). If value. The executable itself is one of -``` +``` $JULIA_HOME/julia $JULIA_HOME/julia-debug -``` +``` by default. The global variable `Base.DATAROOTDIR` determines a relative path from -`Base.JULIA_HOME` to the data directory associated with Julia. Then the path +`Base.JULIA_HOME` to the data directory associated with Julia. Then the path ``` $JULIA_HOME/$DATAROOTDIR/julia/base ``` @@ -57,7 +58,7 @@ $JULIA_HOME/../local/share/julia/site/v$(Base.VERSION.major).$(Base.VERSION.mino $JULIA_HOME/../share/julia/site/v$(Base.VERSION.major).$(Base.VERSION.minor) ``` so that, e. g., version 0.5 of Julia on a Linux system with a Julia executable at -`/bin/julia` will have a default `Base.LOAD_PATH` of +`/bin/julia` will have a default `Base.LOAD_PATH` of ``` /local/share/julia/site/v0.5 /share/julia/site/v0.5 ``` @@ -66,8 +67,8 @@ so that, e. g., version 0.5 of Julia on a Linux system with a Julia executable The path of the parent directory `Dir._pkgroot()` for the version-specific Julia package repositories. If the path is relative, then it is -taken with respect to the working directory. If `JULIA_PKGDIR` is not specified, -then `_pkgroot()` defaults to +taken with respect to the working directory. If `$JULIA_PKGDIR` is not set, then +`_pkgroot()` defaults to ``` $HOME/.julia ``` @@ -90,7 +91,7 @@ and the package repository for version 0.5 of Julia would be ### `JULIA_HISTORY` The absolute path `Base.find_hist_file()` of the REPL's -history file. If `JULIA_HISTORY` is not specified, then `Base.find_hist_file()` +history file. If `$JULIA_HISTORY` is not set, then `Base.find_hist_file()` defaults to ``` $HOME/.julia_history @@ -104,7 +105,7 @@ the max-sum subroutine `MaxSum.maxsum()` of the package dependency resolver satisfying constraints before giving up: this value is by default `1`, and larger values correspond to larger amounts of time. -Suppose the value of `JULIA_PKGRESOLVE_ACCURACY` is `n`. Then +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 @@ -125,15 +126,14 @@ external commands (via `Base.repl_cmd()`). Defaults to the environment variable The editor returned by `Base.editor()` and used in, e.g., [`Base.edit()`](@ref Base.edit). -`JULIA_EDITOR` takes -precedence over `VISUAL`, which in turn takes precedence over `EDITOR`. If none -of these environment variables is set, then the editor is taken to be `open` on -Windows and OS X, or `/etc/alternatives/editor` if it exists, or `emacs` -otherwise. +`$JULIA_EDITOR` takes precedence over `$VISUAL`, which in turn takes precedence +over `$EDITOR`. If none of these environment variables is set, then the editor +is taken to be `open` on Windows and OS X, or `/etc/alternatives/editor` if it +exists, or `emacs` otherwise. -**Warning:** `JULIA_EDITOR` is *not* used in the determination of the editor for -[`Base.Pkg.edit()`](@ref Base.Pkg.edit): this function checks `VISUAL` and -`EDITOR` alone. +*Note:* `$JULIA_EDITOR` is *not* used in the determination of the editor for +[`Base.Pkg.edit()`](@ref Base.Pkg.edit): this function checks `$VISUAL` and +`$EDITOR` alone. ## Parallelization @@ -149,13 +149,35 @@ A `Float64` that sets the value of a seconds a worker process will wait for a master process to establish a connection before dying. +### `JULIA_NUM_THREADS` + +An unsigned 64-bit integer that sets the maximum number of threads available to +Julia. If `$JULIA_NUM_THREADS` exceeds the number of available physical CPU +cores, then the number of threads is set to the number of cores. If +`$JULIA_NUM_THREADS` is not positive or is not set, or if the number of CPU +cores cannot be determined through system calls, then the number of threads is +set to `1`. + +### `JULIA_THREAD_SLEEP_THRESHOLD` + +If set to a string that starts with the case-insensitive substring `"infinite"`, +then spinning threads never sleep. Otherwise, `$JULIA_THREAD_SLEEP_THRESHOLD` is +interpreted as an unsigned 64-bit integer and gives, in nanoseconds, the amount +of time after which spinning threads should sleep. + +### `JULIA_EXCLUSIVE` + +If set to anything besides `0`, then Julia's thread policy is consistent with +running on a dedicated machine: the master thread is on proc 0, and threads are +affinitized. Otherwise, Julia lets the operating system handle thread policy. + ## REPL formatting -Environment variables that determine how REPL output should -be formatted at the terminal. Generally, these variables should be set to [ANSI -terminal escape sequences](http://ascii-table.com/ansi-escape-sequences.php). -The Julia base package provides a high-level interface with much of the same -functionality: see the section on [Interacting With Julia](@ref). +Environment variables that determine how REPL output should be formatted at the +terminal. Generally, these variables should be set to [ANSI terminal escape +sequences](http://ascii-table.com/ansi-escape-sequences.php). The Julia base +package provides a high-level interface with much of the same functionality: see +the section on [Interacting With Julia](@ref). ### `JULIA_ERROR_COLOR` @@ -175,7 +197,7 @@ The formatting `Base.info_color()` (default: cyan, ### `JULIA_INPUT_COLOR` The formatting `Base.input_color()` (default: normal, -`"\033[0m"`) that input should have at the terminal. +`"\033[0m"`) that input should have at the terminal. *Note:* Input is hardcoded to be bold (`"\033[1m"`). @@ -198,9 +220,76 @@ The formatting `Base.stackframe_function_color()` (default: bold, `"\033[1m"`) that function calls should have during a stack trace at the terminal. -## Debugging +## Debugging and profiling + +### `JULIA_GC_ALLOC_POOL`, `JULIA_GC_ALLOC_OTHER`, `JULIA_GC_ALLOC_PRINT` + +If set, these environment variables take strings that optionally start with the +character `'r'`, followed by a string interpolation of the form `"%d:%d:%d"` +(that is, three signed 64-bit integers separated by colons). This triple of +integers `a:b:c` represents the arithmetic sequence `a`, `a + b`, `a + 2*b`, ... +`c`. + +* If it's the `n`th time that `jl_gc_pool_alloc()` has been called, and `n` + belongs to the arithmetic sequence `$JULIA_GC_ALLOC_POOL`, then garbage + collection is forced. +* If it's the `n`th time that `maybe_collect()` has been called, and `n` + belongs to the arithmetic sequence `$JULIA_GC_ALLOC_OTHER`, then garbage + collection is forced. +* If it's the `n`th time that `jl_gc_collect()` has been called, and `n` + belongs to the arithmetic sequence `$JULIA_GC_ALLOC_PRINT`, then counts for + for the number of calls to `jl_gc_pool_alloc()` and `maybe_collect()` are + printed. + +If the character `'r'` appears as above, then the interval between garbage +collection events is randomized. + +*Note:* These environment variables only have an effect if Julia was compiled +with garbage-collection debugging (that is, if `WITH_GC_DEBUG_ENV` is set to `1` +in the build configuration). + +### `JULIA_GC_NO_GENERATIONAL` + +If set to anything besides `0`, then the Julia garbage collector never performs +"quick sweeps" of memory. + +*Note:* This environment variable only has an effect if Julia was compiled with +garbage-collection debugging (that is, if `WITH_GC_DEBUG_ENV` is set to `1` in +the build configuration). + +### `JULIA_GC_WAIT_FOR_DEBUGGER` + +If set to anything besides `0`, then the Julia garbage collector will wait for +the debugger to attach instead of aborting whenever there's a critical error. + +*Note:* This environment variable only has an effect if Julia was compiled with +garbage-collection debugging (that is, if `WITH_GC_DEBUG_ENV` is set to `1` in +the build configuration). + +### `ENABLE_JITPROFILING` + +If set to anything besides `0`, then the compiler will create and register an +event listener for just-in-time (JIT) profiling. + +*Note:* This environment variable only has an effect if Julia was compiled with +JIT profiling support, using either + +* Intel's [VTune™ + Amplifier](https://software.intel.com/en-us/intel-vtune-amplifier-xe) + (`USE_INTEL_JITEVENTS` set to `1` in the build configuration), or +* [OProfile](http://oprofile.sourceforge.net/news/) (`USE_OPROFILE_JITEVENTS` + set to `1` in the build configuration). + +### `JULIA_LLVM_ARGS` + +Arguments to be passed to the LLVM backend. + +*Note:* this environment variable has an effect only if Julia was compiled with +`JL_DEBUG_BUILD` set. ### `JULIA_DEBUG_LOADING` If set, then Julia prints detailed information about the cache in the loading process of [`Base.require()`](@ref Base.require). + + From ba92166d55dd8091865fffe1e8b000d246bb9971 Mon Sep 17 00:00:00 2001 From: Kiaran B Dave Date: Sun, 22 Jan 2017 12:47:36 -0500 Subject: [PATCH 06/11] Increase text width to 92 columns, cull spurious line breaks, switch to admonition syntax, simplify cross-references, fix title. --- doc/src/manual/environment-variables.md | 199 +++++++++++++----------- 1 file changed, 108 insertions(+), 91 deletions(-) diff --git a/doc/src/manual/environment-variables.md b/doc/src/manual/environment-variables.md index cd71139cc2ce4..2ebf503a4059c 100644 --- a/doc/src/manual/environment-variables.md +++ b/doc/src/manual/environment-variables.md @@ -1,153 +1,172 @@ -# Environment Variables in Julia +# Environment Variables The environment variables that Julia uses generally start with `JULIA`. If -[`Base.versioninfo()`](@ref) is called with `verbose` equal to `true`, then the -output will list all environment variables for which `JULIA` appears in the name. - +[`Base.versioninfo`](@ref) is called with `verbose` equal to `true`, then the +output will list all environment variables for which `JULIA` appears in the +name. ## File locations ### `JULIA_HOME` -The absolute path of the directory containing the Julia -executable, which sets the global variable [`Base.JULIA_HOME`](@ref). If -`$JULIA_HOME` is not set, then `Base.JULIA_HOME` defaults to its compile-time -value. +The absolute path of the directory containing the Julia executable, which sets +the global variable [`Base.JULIA_HOME`](@ref). If `$JULIA_HOME` is not set, +then `Base.JULIA_HOME` defaults to its compile-time value. The executable itself is one of + ``` -$JULIA_HOME/julia $JULIA_HOME/julia-debug +$JULIA_HOME/julia +$JULIA_HOME/julia-debug ``` + by default. The global variable `Base.DATAROOTDIR` determines a relative path from `Base.JULIA_HOME` to the data directory associated with Julia. Then the path + ``` $JULIA_HOME/$DATAROOTDIR/julia/base ``` -determines the directory in which Julia -initially searches for source files (via `Base.find_source_file()`). + +determines the directory in which Julia initially searches for source files +(via `Base.find_source_file()`). Likewise, the global variable `Base.SYSCONFDIR` determines a relative path to -the configuration file directory. Then Julia searches for a `juliarc.jl` file at +the configuration file directory. Then Julia searches for a `juliarc.jl` file +at + ``` -$JULIA_HOME/$SYSCONFDIR/julia/juliarc.jl $JULIA_HOME/../etc/julia/juliarc.jl +$JULIA_HOME/$SYSCONFDIR/julia/juliarc.jl +$JULIA_HOME/../etc/julia/juliarc.jl ``` + by default (via `Base.load_juliarc()`). For example, a Linux installation with a Julia executable located at -`/bin/julia`, a `DATAROOTDIR` of `../share`, and a `SYSCONFDIR` of `../etc` will -have `JULIA_HOME` set to `/bin`, a source-file search path of +`/bin/julia`, a `DATAROOTDIR` of `../share`, and a `SYSCONFDIR` of `../etc` +will have `JULIA_HOME` set to `/bin`, a source-file search path of + ``` /share/julia/base ``` + and a global configuration search path of + ``` /etc/julia/juliarc.jl ``` ### `JULIA_LOAD_PATH` -A separated list of absolute paths that are to be appended -to the variable [`Base.LOAD_PATH`](@ref). (In Unix-like systems, the path -separator is `:`; in Windows systems, the path separator is `;`.) The -`Base.LOAD_PATH` variable is where [`Base.require()`](@ref Base.require) and -`Base.load_in_path()` look for code; it defaults to the absolute paths +A separated list of absolute paths that are to be appended to the variable +[`Base.LOAD_PATH`](@ref). (In Unix-like systems, the path separator is `:`; in +Windows systems, the path separator is `;`.) The `Base.LOAD_PATH` variable is +where [`Base.require`](@ref) and `Base.load_in_path()` look for +code; it defaults to the absolute paths + ``` $JULIA_HOME/../local/share/julia/site/v$(Base.VERSION.major).$(Base.VERSION.minor) $JULIA_HOME/../share/julia/site/v$(Base.VERSION.major).$(Base.VERSION.minor) ``` -so that, e. g., version 0.5 of Julia on a Linux system with a Julia executable at -`/bin/julia` will have a default `Base.LOAD_PATH` of + +so that, e. g., version 0.5 of Julia on a Linux system with a Julia executable +at `/bin/julia` will have a default `Base.LOAD_PATH` of + ``` -/local/share/julia/site/v0.5 /share/julia/site/v0.5 +/local/share/julia/site/v0.5 +/share/julia/site/v0.5 ``` ### `JULIA_PKGDIR` -The path of the parent directory `Dir._pkgroot()` for the -version-specific Julia package repositories. If the path is relative, then it is -taken with respect to the working directory. If `$JULIA_PKGDIR` is not set, then +The path of the parent directory `Dir._pkgroot()` for the version-specific +Julia package repositories. If the path is relative, then it is taken with +respect to the working directory. If `$JULIA_PKGDIR` is not set, then `_pkgroot()` defaults to + ``` $HOME/.julia ``` -Then the repository location -[`Base.Pkg.dir()`](@ref Base.Pkg.dir) for a given Julia version is + +Then the repository location [`Base.Pkg.dir`](@ref) for a given +Julia version is + ``` $JULIA_PKGDIR/v$(Base.VERSION.major).$(Base.VERSION.minor) ``` For example, for a Linux user whose home directory is `/home/alice`, the directory containing the package repositories would by default be + ``` /home/alice/.julia ``` + and the package repository for version 0.5 of Julia would be + ``` /home/alice/.julia/v0.5 ``` ### `JULIA_HISTORY` -The absolute path `Base.find_hist_file()` of the REPL's -history file. If `$JULIA_HISTORY` is not set, then `Base.find_hist_file()` -defaults to +The absolute path `Base.find_hist_file()` of the REPL's history file. If +`$JULIA_HISTORY` is not set, then `Base.find_hist_file()` defaults to + ``` $HOME/.julia_history ``` ### `JULIA_PKGRESOLVE_ACCURACY` -A positive `Int` that determines how much time -the max-sum subroutine `MaxSum.maxsum()` of the package dependency resolver -[`Base.Pkg.resolve()`](@ref Base.Pkg.resolve) will devote to attempting +A positive `Int` that determines how much time the max-sum subroutine +`MaxSum.maxsum()` of the package dependency resolver +[`Base.Pkg.resolve`](@ref) will devote to attempting satisfying constraints before giving up: this value is 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 +* 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 ### `JULIA_SHELL` -The absolute path of the shell with which Julia should execute -external commands (via `Base.repl_cmd()`). Defaults to the environment variable +The absolute path of the shell with which Julia should execute external +commands (via `Base.repl_cmd()`). Defaults to the environment variable `$SHELL`, and falls back to `/bin/sh` if `$SHELL` is unset. -*Note:* the `fish` shell is unsupported. +!!! note the `fish` shell is unsupported. ### `JULIA_EDITOR`, `VISUAL`, `EDITOR` -The editor returned by `Base.editor()` -and used in, e.g., [`Base.edit()`](@ref Base.edit). +The editor returned by `Base.editor()` and used in, e.g., [`Base.edit`](@ref). `$JULIA_EDITOR` takes precedence over `$VISUAL`, which in turn takes precedence over `$EDITOR`. If none of these environment variables is set, then the editor is taken to be `open` on Windows and OS X, or `/etc/alternatives/editor` if it exists, or `emacs` otherwise. -*Note:* `$JULIA_EDITOR` is *not* used in the determination of the editor for -[`Base.Pkg.edit()`](@ref Base.Pkg.edit): this function checks `$VISUAL` and -`$EDITOR` alone. +!!! note `$JULIA_EDITOR` is *not* used in the determination of the editor for + [`Base.Pkg.edit`](@ref): this function checks `$VISUAL` and `$EDITOR` + alone. ## Parallelization ### `JULIA_CPU_CORES` -Overrides the global variable -[`Base.Sys.CPU_CORES`](@ref), the number of logical CPU cores available. +Overrides the global variable [`Base.Sys.CPU_CORES`](@ref), the number of +logical CPU cores available. ### `JULIA_WORKER_TIMEOUT` -A `Float64` that sets the value of -`Base.worker_timeout()` (default: `60.0`). This function gives the number of -a seconds a worker process will wait for a master process to establish -a connection before dying. +A `Float64` that sets the value of `Base.worker_timeout()` (default: `60.0`). +This function gives the number of a seconds a worker process will wait for +a master process to establish a connection before dying. ### `JULIA_NUM_THREADS` @@ -160,10 +179,11 @@ set to `1`. ### `JULIA_THREAD_SLEEP_THRESHOLD` -If set to a string that starts with the case-insensitive substring `"infinite"`, -then spinning threads never sleep. Otherwise, `$JULIA_THREAD_SLEEP_THRESHOLD` is -interpreted as an unsigned 64-bit integer and gives, in nanoseconds, the amount -of time after which spinning threads should sleep. +If set to a string that starts with the case-insensitive substring +`"infinite"`, then spinning threads never sleep. Otherwise, +`$JULIA_THREAD_SLEEP_THRESHOLD` is interpreted as an unsigned 64-bit integer +and gives, in nanoseconds, the amount of time after which spinning threads +should sleep. ### `JULIA_EXCLUSIVE` @@ -176,49 +196,47 @@ affinitized. Otherwise, Julia lets the operating system handle thread policy. Environment variables that determine how REPL output should be formatted at the terminal. Generally, these variables should be set to [ANSI terminal escape sequences](http://ascii-table.com/ansi-escape-sequences.php). The Julia base -package provides a high-level interface with much of the same functionality: see -the section on [Interacting With Julia](@ref). +package provides a high-level interface with much of the same functionality: +see the section on [Interacting With Julia](@ref). ### `JULIA_ERROR_COLOR` -The formatting `Base.error_color()` (default: light -red, `"\033[91m"`) that errors should have at the terminal. +The formatting `Base.error_color()` (default: light red, `"\033[91m"`) that +errors should have at the terminal. ### `JULIA_WARN_COLOR` -The formatting `Base.warn_color()` (default: yellow, -`"\033[93m"`) that warnings should have at the terminal. +The formatting `Base.warn_color()` (default: yellow, `"\033[93m"`) that +warnings should have at the terminal. ### `JULIA_INFO_COLOR` -The formatting `Base.info_color()` (default: cyan, -`"\033[36m"`) that info should have at the terminal. +The formatting `Base.info_color()` (default: cyan, `"\033[36m"`) that info +should have at the terminal. ### `JULIA_INPUT_COLOR` -The formatting `Base.input_color()` (default: normal, -`"\033[0m"`) that input should have at the terminal. +The formatting `Base.input_color()` (default: normal, `"\033[0m"`) that input +should have at the terminal. -*Note:* Input is hardcoded to be bold (`"\033[1m"`). +!!! note input is hardcoded to be bold (`"\033[1m"`). ### `JULIA_ANSWER_COLOR` -The formatting `Base.answer_color()` (default: -normal, `"\033[0m"`) that output should have at the terminal. +The formatting `Base.answer_color()` (default: normal, `"\033[0m"`) that output +should have at the terminal. -*Note:* Output is hardcoded to be bold (`"\033[1m"`). +!!! note output is hardcoded to be bold (`"\033[1m"`). ### `JULIA_STACKFRAME_LINEINFO_COLOR` -The formatting -`Base.stackframe_lineinfo_color()` (default: bold, `"\033[1m"`) that line info -should have during a stack trace at the terminal. +The formatting `Base.stackframe_lineinfo_color()` (default: bold, `"\033[1m"`) +that line info should have during a stack trace at the terminal. ### `JULIA_STACKFRAME_FUNCTION_COLOR` -The formatting -`Base.stackframe_function_color()` (default: bold, `"\033[1m"`) that function -calls should have during a stack trace at the terminal. +The formatting `Base.stackframe_function_color()` (default: bold, `"\033[1m"`) +that function calls should have during a stack trace at the terminal. ## Debugging and profiling @@ -227,8 +245,8 @@ calls should have during a stack trace at the terminal. If set, these environment variables take strings that optionally start with the character `'r'`, followed by a string interpolation of the form `"%d:%d:%d"` (that is, three signed 64-bit integers separated by colons). This triple of -integers `a:b:c` represents the arithmetic sequence `a`, `a + b`, `a + 2*b`, ... -`c`. +integers `a:b:c` represents the arithmetic sequence `a`, `a + b`, `a + 2*b`, +... `c`. * If it's the `n`th time that `jl_gc_pool_alloc()` has been called, and `n` belongs to the arithmetic sequence `$JULIA_GC_ALLOC_POOL`, then garbage @@ -244,35 +262,35 @@ integers `a:b:c` represents the arithmetic sequence `a`, `a + b`, `a + 2*b`, ... If the character `'r'` appears as above, then the interval between garbage collection events is randomized. -*Note:* These environment variables only have an effect if Julia was compiled -with garbage-collection debugging (that is, if `WITH_GC_DEBUG_ENV` is set to `1` -in the build configuration). +!!! note these environment variables only have an effect if Julia was compiled + with garbage-collection debugging (that is, if `WITH_GC_DEBUG_ENV` is set + to `1` in the build configuration). ### `JULIA_GC_NO_GENERATIONAL` If set to anything besides `0`, then the Julia garbage collector never performs "quick sweeps" of memory. -*Note:* This environment variable only has an effect if Julia was compiled with -garbage-collection debugging (that is, if `WITH_GC_DEBUG_ENV` is set to `1` in -the build configuration). +!!! note this environment variable only has an effect if Julia was compiled + with garbage-collection debugging (that is, if `WITH_GC_DEBUG_ENV` is set + to `1` in the build configuration). ### `JULIA_GC_WAIT_FOR_DEBUGGER` If set to anything besides `0`, then the Julia garbage collector will wait for the debugger to attach instead of aborting whenever there's a critical error. -*Note:* This environment variable only has an effect if Julia was compiled with -garbage-collection debugging (that is, if `WITH_GC_DEBUG_ENV` is set to `1` in -the build configuration). +!!! note this environment variable only has an effect if Julia was compiled + with garbage-collection debugging (that is, if `WITH_GC_DEBUG_ENV` is set + to `1` in the build configuration). ### `ENABLE_JITPROFILING` If set to anything besides `0`, then the compiler will create and register an event listener for just-in-time (JIT) profiling. -*Note:* This environment variable only has an effect if Julia was compiled with -JIT profiling support, using either +!!! note this environment variable only has an effect if Julia was compiled + with JIT profiling support, using either * Intel's [VTune™ Amplifier](https://software.intel.com/en-us/intel-vtune-amplifier-xe) @@ -284,12 +302,11 @@ JIT profiling support, using either Arguments to be passed to the LLVM backend. -*Note:* this environment variable has an effect only if Julia was compiled with -`JL_DEBUG_BUILD` set. +!!! note this environment variable has an effect only if Julia was compiled with + `JL_DEBUG_BUILD` set. ### `JULIA_DEBUG_LOADING` -If set, then Julia prints detailed information about -the cache in the loading process of [`Base.require()`](@ref Base.require). - +If set, then Julia prints detailed information about the cache in the loading +process of [`Base.require`](@ref). From f153d5b9944b4711a6ced805c810bcdf8271ce4b Mon Sep 17 00:00:00 2001 From: Kiaran B Dave Date: Sun, 22 Jan 2017 14:53:21 -0500 Subject: [PATCH 07/11] Trailing whitespace --- doc/src/manual/environment-variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/src/manual/environment-variables.md b/doc/src/manual/environment-variables.md index 2ebf503a4059c..a3b47ab6859e3 100644 --- a/doc/src/manual/environment-variables.md +++ b/doc/src/manual/environment-variables.md @@ -129,7 +129,7 @@ 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 +* 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 From 063e2be86f4c58757a04adc2ab93f1542eeca312 Mon Sep 17 00:00:00 2001 From: Kiaran B Dave Date: Tue, 24 Jan 2017 12:50:55 -0500 Subject: [PATCH 08/11] Admonition line breaks; editor envvar heading. --- doc/src/manual/environment-variables.md | 38 ++++++++++++++++++------- 1 file changed, 28 insertions(+), 10 deletions(-) diff --git a/doc/src/manual/environment-variables.md b/doc/src/manual/environment-variables.md index a3b47ab6859e3..432057a23d76a 100644 --- a/doc/src/manual/environment-variables.md +++ b/doc/src/manual/environment-variables.md @@ -140,9 +140,11 @@ The absolute path of the shell with which Julia should execute external commands (via `Base.repl_cmd()`). Defaults to the environment variable `$SHELL`, and falls back to `/bin/sh` if `$SHELL` is unset. -!!! note the `fish` shell is unsupported. +!!! note -### `JULIA_EDITOR`, `VISUAL`, `EDITOR` + the `fish` shell is unsupported. + +### `JULIA_EDITOR` The editor returned by `Base.editor()` and used in, e.g., [`Base.edit`](@ref). @@ -151,7 +153,9 @@ over `$EDITOR`. If none of these environment variables is set, then the editor is taken to be `open` on Windows and OS X, or `/etc/alternatives/editor` if it exists, or `emacs` otherwise. -!!! note `$JULIA_EDITOR` is *not* used in the determination of the editor for +!!! note + + `$JULIA_EDITOR` is *not* used in the determination of the editor for [`Base.Pkg.edit`](@ref): this function checks `$VISUAL` and `$EDITOR` alone. @@ -219,14 +223,18 @@ should have at the terminal. The formatting `Base.input_color()` (default: normal, `"\033[0m"`) that input should have at the terminal. -!!! note input is hardcoded to be bold (`"\033[1m"`). +!!! note + + input is hardcoded to be bold (`"\033[1m"`). ### `JULIA_ANSWER_COLOR` The formatting `Base.answer_color()` (default: normal, `"\033[0m"`) that output should have at the terminal. -!!! note output is hardcoded to be bold (`"\033[1m"`). +!!! note + + output is hardcoded to be bold (`"\033[1m"`). ### `JULIA_STACKFRAME_LINEINFO_COLOR` @@ -262,7 +270,9 @@ integers `a:b:c` represents the arithmetic sequence `a`, `a + b`, `a + 2*b`, If the character `'r'` appears as above, then the interval between garbage collection events is randomized. -!!! note these environment variables only have an effect if Julia was compiled +!!! note + + these environment variables only have an effect if Julia was compiled with garbage-collection debugging (that is, if `WITH_GC_DEBUG_ENV` is set to `1` in the build configuration). @@ -271,7 +281,9 @@ collection events is randomized. If set to anything besides `0`, then the Julia garbage collector never performs "quick sweeps" of memory. -!!! note this environment variable only has an effect if Julia was compiled +!!! note + + this environment variable only has an effect if Julia was compiled with garbage-collection debugging (that is, if `WITH_GC_DEBUG_ENV` is set to `1` in the build configuration). @@ -280,7 +292,9 @@ If set to anything besides `0`, then the Julia garbage collector never performs If set to anything besides `0`, then the Julia garbage collector will wait for the debugger to attach instead of aborting whenever there's a critical error. -!!! note this environment variable only has an effect if Julia was compiled +!!! note + + this environment variable only has an effect if Julia was compiled with garbage-collection debugging (that is, if `WITH_GC_DEBUG_ENV` is set to `1` in the build configuration). @@ -289,7 +303,9 @@ the debugger to attach instead of aborting whenever there's a critical error. If set to anything besides `0`, then the compiler will create and register an event listener for just-in-time (JIT) profiling. -!!! note this environment variable only has an effect if Julia was compiled +!!! note + + this environment variable only has an effect if Julia was compiled with JIT profiling support, using either * Intel's [VTune™ @@ -302,7 +318,9 @@ event listener for just-in-time (JIT) profiling. Arguments to be passed to the LLVM backend. -!!! note this environment variable has an effect only if Julia was compiled with +!!! note + + this environment variable has an effect only if Julia was compiled with `JL_DEBUG_BUILD` set. ### `JULIA_DEBUG_LOADING` From 672849d125f060b2b7502d23ed4dd687033bb86a Mon Sep 17 00:00:00 2001 From: Kiaran B Dave Date: Fri, 27 Jan 2017 12:39:38 -0500 Subject: [PATCH 09/11] clarify integer types, remove outdated notes, whitespace change --- doc/src/manual/environment-variables.md | 48 ++++++++++--------------- 1 file changed, 18 insertions(+), 30 deletions(-) diff --git a/doc/src/manual/environment-variables.md b/doc/src/manual/environment-variables.md index 432057a23d76a..13d7b3bb33fe6 100644 --- a/doc/src/manual/environment-variables.md +++ b/doc/src/manual/environment-variables.md @@ -70,7 +70,7 @@ $JULIA_HOME/../local/share/julia/site/v$(Base.VERSION.major).$(Base.VERSION.mino $JULIA_HOME/../share/julia/site/v$(Base.VERSION.major).$(Base.VERSION.minor) ``` -so that, e. g., version 0.5 of Julia on a Linux system with a Julia executable +so that, e.g., version 0.5 of Julia on a Linux system with a Julia executable at `/bin/julia` will have a default `Base.LOAD_PATH` of ``` @@ -140,10 +140,6 @@ The absolute path of the shell with which Julia should execute external commands (via `Base.repl_cmd()`). Defaults to the environment variable `$SHELL`, and falls back to `/bin/sh` if `$SHELL` is unset. -!!! note - - the `fish` shell is unsupported. - ### `JULIA_EDITOR` The editor returned by `Base.editor()` and used in, e.g., [`Base.edit`](@ref). @@ -174,10 +170,10 @@ a master process to establish a connection before dying. ### `JULIA_NUM_THREADS` -An unsigned 64-bit integer that sets the maximum number of threads available to -Julia. If `$JULIA_NUM_THREADS` exceeds the number of available physical CPU -cores, then the number of threads is set to the number of cores. If -`$JULIA_NUM_THREADS` is not positive or is not set, or if the number of CPU +An unsigned 64-bit integer (`uint64_t`) that sets the maximum number of threads +available to Julia. If `$JULIA_NUM_THREADS` exceeds the number of available +physical CPU cores, then the number of threads is set to the number of cores. +If `$JULIA_NUM_THREADS` is not positive or is not set, or if the number of CPU cores cannot be determined through system calls, then the number of threads is set to `1`. @@ -186,8 +182,8 @@ set to `1`. If set to a string that starts with the case-insensitive substring `"infinite"`, then spinning threads never sleep. Otherwise, `$JULIA_THREAD_SLEEP_THRESHOLD` is interpreted as an unsigned 64-bit integer -and gives, in nanoseconds, the amount of time after which spinning threads -should sleep. +(`uint64_t`) and gives, in nanoseconds, the amount of time after which spinning +threads should sleep. ### `JULIA_EXCLUSIVE` @@ -223,19 +219,11 @@ should have at the terminal. The formatting `Base.input_color()` (default: normal, `"\033[0m"`) that input should have at the terminal. -!!! note - - input is hardcoded to be bold (`"\033[1m"`). - ### `JULIA_ANSWER_COLOR` The formatting `Base.answer_color()` (default: normal, `"\033[0m"`) that output should have at the terminal. -!!! note - - output is hardcoded to be bold (`"\033[1m"`). - ### `JULIA_STACKFRAME_LINEINFO_COLOR` The formatting `Base.stackframe_lineinfo_color()` (default: bold, `"\033[1m"`) @@ -251,21 +239,21 @@ that function calls should have during a stack trace at the terminal. ### `JULIA_GC_ALLOC_POOL`, `JULIA_GC_ALLOC_OTHER`, `JULIA_GC_ALLOC_PRINT` If set, these environment variables take strings that optionally start with the -character `'r'`, followed by a string interpolation of the form `"%d:%d:%d"` -(that is, three signed 64-bit integers separated by colons). This triple of -integers `a:b:c` represents the arithmetic sequence `a`, `a + b`, `a + 2*b`, -... `c`. +character `'r'`, followed by a string interpolation of a colon-separated list +of three signed 64-bit integers (`int64_t`). This triple of integers `a:b:c` +represents the arithmetic sequence `a`, `a + b`, `a ++ 2*b`, ... `c`. * If it's the `n`th time that `jl_gc_pool_alloc()` has been called, and `n` - belongs to the arithmetic sequence `$JULIA_GC_ALLOC_POOL`, then garbage - collection is forced. + belongs to the arithmetic sequence represented by `$JULIA_GC_ALLOC_POOL`, + then garbage collection is forced. * If it's the `n`th time that `maybe_collect()` has been called, and `n` - belongs to the arithmetic sequence `$JULIA_GC_ALLOC_OTHER`, then garbage - collection is forced. + belongs to the arithmetic sequence represented by `$JULIA_GC_ALLOC_OTHER`, + then garbage collection is forced. * If it's the `n`th time that `jl_gc_collect()` has been called, and `n` - belongs to the arithmetic sequence `$JULIA_GC_ALLOC_PRINT`, then counts for - for the number of calls to `jl_gc_pool_alloc()` and `maybe_collect()` are - printed. + belongs to the arithmetic sequence represented by `$JULIA_GC_ALLOC_PRINT`, + then counts for for the number of calls to `jl_gc_pool_alloc()` and + `maybe_collect()` are printed. If the character `'r'` appears as above, then the interval between garbage collection events is randomized. From fe9b0d1a5c80aa220da6ab5c31691d0febbe01b9 Mon Sep 17 00:00:00 2001 From: Kiaran B Dave Date: Fri, 27 Jan 2017 12:46:52 -0500 Subject: [PATCH 10/11] whitespace --- doc/src/manual/environment-variables.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/src/manual/environment-variables.md b/doc/src/manual/environment-variables.md index 13d7b3bb33fe6..e912a5fcddbbf 100644 --- a/doc/src/manual/environment-variables.md +++ b/doc/src/manual/environment-variables.md @@ -241,8 +241,7 @@ that function calls should have during a stack trace at the terminal. If set, these environment variables take strings that optionally start with the character `'r'`, followed by a string interpolation of a colon-separated list of three signed 64-bit integers (`int64_t`). This triple of integers `a:b:c` -represents the arithmetic sequence `a`, `a + b`, `a -+ 2*b`, ... `c`. +represents the arithmetic sequence `a`, `a + b`, `a + 2*b`, ... `c`. * If it's the `n`th time that `jl_gc_pool_alloc()` has been called, and `n` belongs to the arithmetic sequence represented by `$JULIA_GC_ALLOC_POOL`, From 1935def8d45a722309d0e3f043e76558d2a93a83 Mon Sep 17 00:00:00 2001 From: Kiaran B Dave Date: Tue, 31 Jan 2017 13:28:50 -0500 Subject: [PATCH 11/11] No windows shell, English fixes, delete reference to base, clarify 'r', julia-debug. --- doc/src/manual/environment-variables.md | 250 ++++++++++++------------ 1 file changed, 123 insertions(+), 127 deletions(-) diff --git a/doc/src/manual/environment-variables.md b/doc/src/manual/environment-variables.md index e912a5fcddbbf..c2b00b5789e97 100644 --- a/doc/src/manual/environment-variables.md +++ b/doc/src/manual/environment-variables.md @@ -1,17 +1,16 @@ # Environment Variables The environment variables that Julia uses generally start with `JULIA`. If -[`Base.versioninfo`](@ref) is called with `verbose` equal to `true`, then the -output will list all environment variables for which `JULIA` appears in the -name. +[`Base.versioninfo`](@ref) is called with `verbose` equal to `true`, then the output will +list all environment variables for which `JULIA` appears in the name. ## File locations ### `JULIA_HOME` -The absolute path of the directory containing the Julia executable, which sets -the global variable [`Base.JULIA_HOME`](@ref). If `$JULIA_HOME` is not set, -then `Base.JULIA_HOME` defaults to its compile-time value. +The absolute path of the directory containing the Julia executable, which sets the global +variable [`Base.JULIA_HOME`](@ref). If `$JULIA_HOME` is not set, then `Base.JULIA_HOME` +defaults to its compile-time value. The executable itself is one of @@ -22,19 +21,18 @@ $JULIA_HOME/julia-debug by default. -The global variable `Base.DATAROOTDIR` determines a relative path from -`Base.JULIA_HOME` to the data directory associated with Julia. Then the path +The global variable `Base.DATAROOTDIR` determines a relative path from `Base.JULIA_HOME` to +the data directory associated with Julia. Then the path ``` $JULIA_HOME/$DATAROOTDIR/julia/base ``` -determines the directory in which Julia initially searches for source files -(via `Base.find_source_file()`). +determines the directory in which Julia initially searches for source files (via +`Base.find_source_file()`). -Likewise, the global variable `Base.SYSCONFDIR` determines a relative path to -the configuration file directory. Then Julia searches for a `juliarc.jl` file -at +Likewise, the global variable `Base.SYSCONFDIR` determines a relative path to the +configuration file directory. Then Julia searches for a `juliarc.jl` file at ``` $JULIA_HOME/$SYSCONFDIR/julia/juliarc.jl @@ -43,9 +41,9 @@ $JULIA_HOME/../etc/julia/juliarc.jl by default (via `Base.load_juliarc()`). -For example, a Linux installation with a Julia executable located at -`/bin/julia`, a `DATAROOTDIR` of `../share`, and a `SYSCONFDIR` of `../etc` -will have `JULIA_HOME` set to `/bin`, a source-file search path of +For example, a Linux installation with a Julia executable located at `/bin/julia`, +a `DATAROOTDIR` of `../share`, and a `SYSCONFDIR` of `../etc` will have `JULIA_HOME` set to +`/bin`, a source-file search path of ``` /share/julia/base @@ -60,18 +58,18 @@ and a global configuration search path of ### `JULIA_LOAD_PATH` A separated list of absolute paths that are to be appended to the variable -[`Base.LOAD_PATH`](@ref). (In Unix-like systems, the path separator is `:`; in -Windows systems, the path separator is `;`.) The `Base.LOAD_PATH` variable is -where [`Base.require`](@ref) and `Base.load_in_path()` look for -code; it defaults to the absolute paths +[`Base.LOAD_PATH`](@ref). (In Unix-like systems, the path separator is `:`; in Windows +systems, the path separator is `;`.) The `Base.LOAD_PATH` variable is where +[`Base.require`](@ref) and `Base.load_in_path()` look for code; it defaults to the absolute +paths ``` $JULIA_HOME/../local/share/julia/site/v$(Base.VERSION.major).$(Base.VERSION.minor) $JULIA_HOME/../share/julia/site/v$(Base.VERSION.major).$(Base.VERSION.minor) ``` -so that, e.g., version 0.5 of Julia on a Linux system with a Julia executable -at `/bin/julia` will have a default `Base.LOAD_PATH` of +so that, e.g., version 0.5 of Julia on a Linux system with a Julia executable at +`/bin/julia` will have a default `Base.LOAD_PATH` of ``` /local/share/julia/site/v0.5 @@ -80,24 +78,22 @@ at `/bin/julia` will have a default `Base.LOAD_PATH` of ### `JULIA_PKGDIR` -The path of the parent directory `Dir._pkgroot()` for the version-specific -Julia package repositories. If the path is relative, then it is taken with -respect to the working directory. If `$JULIA_PKGDIR` is not set, then -`_pkgroot()` defaults to +The path of the parent directory `Dir._pkgroot()` for the version-specific Julia package +repositories. If the path is relative, then it is taken with respect to the working +directory. If `$JULIA_PKGDIR` is not set, then `_pkgroot()` defaults to ``` $HOME/.julia ``` -Then the repository location [`Base.Pkg.dir`](@ref) for a given -Julia version is +Then the repository location [`Base.Pkg.dir`](@ref) for a given Julia version is ``` $JULIA_PKGDIR/v$(Base.VERSION.major).$(Base.VERSION.minor) ``` -For example, for a Linux user whose home directory is `/home/alice`, the -directory containing the package repositories would by default be +For example, for a Linux user whose home directory is `/home/alice`, the directory +containing the package repositories would by default be ``` /home/alice/.julia @@ -111,8 +107,8 @@ and the package repository for version 0.5 of Julia would be ### `JULIA_HISTORY` -The absolute path `Base.find_hist_file()` of the REPL's history file. If -`$JULIA_HISTORY` is not set, then `Base.find_hist_file()` defaults to +The absolute path `Base.find_hist_file()` of the REPL's history file. If `$JULIA_HISTORY` is +not set, then `Base.find_hist_file()` defaults to ``` $HOME/.julia_history @@ -120,11 +116,10 @@ $HOME/.julia_history ### `JULIA_PKGRESOLVE_ACCURACY` -A positive `Int` that determines how much time the max-sum subroutine -`MaxSum.maxsum()` of the package dependency resolver -[`Base.Pkg.resolve`](@ref) will devote to attempting -satisfying constraints before giving up: this value is by default `1`, and -larger values correspond to larger amounts of time. +A positive `Int` that determines how much time the max-sum subroutine `MaxSum.maxsum()` of +the package dependency resolver [`Base.Pkg.resolve`](@ref) will devote to attempting +satisfying constraints before giving up: this value is by default `1`, and larger values +correspond to larger amounts of time. Suppose the value of `$JULIA_PKGRESOLVE_ACCURACY` is `n`. Then @@ -136,170 +131,170 @@ Suppose the value of `$JULIA_PKGRESOLVE_ACCURACY` is `n`. Then ### `JULIA_SHELL` -The absolute path of the shell with which Julia should execute external -commands (via `Base.repl_cmd()`). Defaults to the environment variable -`$SHELL`, and falls back to `/bin/sh` if `$SHELL` is unset. +The absolute path of the shell with which Julia should execute external commands (via +`Base.repl_cmd()`). Defaults to the environment variable `$SHELL`, and falls back to +`/bin/sh` if `$SHELL` is unset. + +!!! note + + On Windows, this environment variable is ignored, and external commands are executed + directly. ### `JULIA_EDITOR` The editor returned by `Base.editor()` and used in, e.g., [`Base.edit`](@ref). -`$JULIA_EDITOR` takes precedence over `$VISUAL`, which in turn takes precedence -over `$EDITOR`. If none of these environment variables is set, then the editor -is taken to be `open` on Windows and OS X, or `/etc/alternatives/editor` if it -exists, or `emacs` otherwise. +`$JULIA_EDITOR` takes precedence over `$VISUAL`, which in turn takes precedence over +`$EDITOR`. If none of these environment variables is set, then the editor is taken to be +`open` on Windows and OS X, or `/etc/alternatives/editor` if it exists, or `emacs` +otherwise. !!! note `$JULIA_EDITOR` is *not* used in the determination of the editor for - [`Base.Pkg.edit`](@ref): this function checks `$VISUAL` and `$EDITOR` - alone. + [`Base.Pkg.edit`](@ref): this function checks `$VISUAL` and `$EDITOR` alone. ## Parallelization ### `JULIA_CPU_CORES` -Overrides the global variable [`Base.Sys.CPU_CORES`](@ref), the number of -logical CPU cores available. +Overrides the global variable [`Base.Sys.CPU_CORES`](@ref), the number of logical CPU cores +available. ### `JULIA_WORKER_TIMEOUT` -A `Float64` that sets the value of `Base.worker_timeout()` (default: `60.0`). -This function gives the number of a seconds a worker process will wait for -a master process to establish a connection before dying. +A `Float64` that sets the value of `Base.worker_timeout()` (default: `60.0`). This function +gives the number of seconds a worker process will wait for a master process to establish +a connection before dying. ### `JULIA_NUM_THREADS` -An unsigned 64-bit integer (`uint64_t`) that sets the maximum number of threads -available to Julia. If `$JULIA_NUM_THREADS` exceeds the number of available -physical CPU cores, then the number of threads is set to the number of cores. -If `$JULIA_NUM_THREADS` is not positive or is not set, or if the number of CPU -cores cannot be determined through system calls, then the number of threads is -set to `1`. +An unsigned 64-bit integer (`uint64_t`) that sets the maximum number of threads available to +Julia. If `$JULIA_NUM_THREADS` exceeds the number of available physical CPU cores, then the +number of threads is set to the number of cores. If `$JULIA_NUM_THREADS` is not positive or +is not set, or if the number of CPU cores cannot be determined through system calls, then +the number of threads is set to `1`. ### `JULIA_THREAD_SLEEP_THRESHOLD` -If set to a string that starts with the case-insensitive substring -`"infinite"`, then spinning threads never sleep. Otherwise, -`$JULIA_THREAD_SLEEP_THRESHOLD` is interpreted as an unsigned 64-bit integer -(`uint64_t`) and gives, in nanoseconds, the amount of time after which spinning -threads should sleep. +If set to a string that starts with the case-insensitive substring `"infinite"`, then +spinning threads never sleep. Otherwise, `$JULIA_THREAD_SLEEP_THRESHOLD` is interpreted as +an unsigned 64-bit integer (`uint64_t`) and gives, in nanoseconds, the amount of time after +which spinning threads should sleep. ### `JULIA_EXCLUSIVE` -If set to anything besides `0`, then Julia's thread policy is consistent with -running on a dedicated machine: the master thread is on proc 0, and threads are -affinitized. Otherwise, Julia lets the operating system handle thread policy. +If set to anything besides `0`, then Julia's thread policy is consistent with running on +a dedicated machine: the master thread is on proc 0, and threads are affinitized. Otherwise, +Julia lets the operating system handle thread policy. ## REPL formatting -Environment variables that determine how REPL output should be formatted at the -terminal. Generally, these variables should be set to [ANSI terminal escape -sequences](http://ascii-table.com/ansi-escape-sequences.php). The Julia base -package provides a high-level interface with much of the same functionality: -see the section on [Interacting With Julia](@ref). +Environment variables that determine how REPL output should be formatted at the terminal. +Generally, these variables should be set to [ANSI terminal escape +sequences](http://ascii-table.com/ansi-escape-sequences.php). Julia provides a high-level +interface with much of the same functionality: see the section on [Interacting With +Julia](@ref). ### `JULIA_ERROR_COLOR` -The formatting `Base.error_color()` (default: light red, `"\033[91m"`) that -errors should have at the terminal. +The formatting `Base.error_color()` (default: light red, `"\033[91m"`) that errors should +have at the terminal. ### `JULIA_WARN_COLOR` -The formatting `Base.warn_color()` (default: yellow, `"\033[93m"`) that -warnings should have at the terminal. +The formatting `Base.warn_color()` (default: yellow, `"\033[93m"`) that warnings should have +at the terminal. ### `JULIA_INFO_COLOR` -The formatting `Base.info_color()` (default: cyan, `"\033[36m"`) that info -should have at the terminal. +The formatting `Base.info_color()` (default: cyan, `"\033[36m"`) that info should have at +the terminal. ### `JULIA_INPUT_COLOR` -The formatting `Base.input_color()` (default: normal, `"\033[0m"`) that input -should have at the terminal. +The formatting `Base.input_color()` (default: normal, `"\033[0m"`) that input should have at +the terminal. ### `JULIA_ANSWER_COLOR` -The formatting `Base.answer_color()` (default: normal, `"\033[0m"`) that output -should have at the terminal. +The formatting `Base.answer_color()` (default: normal, `"\033[0m"`) that output should have +at the terminal. ### `JULIA_STACKFRAME_LINEINFO_COLOR` -The formatting `Base.stackframe_lineinfo_color()` (default: bold, `"\033[1m"`) -that line info should have during a stack trace at the terminal. +The formatting `Base.stackframe_lineinfo_color()` (default: bold, `"\033[1m"`) that line +info should have during a stack trace at the terminal. ### `JULIA_STACKFRAME_FUNCTION_COLOR` -The formatting `Base.stackframe_function_color()` (default: bold, `"\033[1m"`) -that function calls should have during a stack trace at the terminal. +The formatting `Base.stackframe_function_color()` (default: bold, `"\033[1m"`) that function +calls should have during a stack trace at the terminal. ## Debugging and profiling ### `JULIA_GC_ALLOC_POOL`, `JULIA_GC_ALLOC_OTHER`, `JULIA_GC_ALLOC_PRINT` -If set, these environment variables take strings that optionally start with the -character `'r'`, followed by a string interpolation of a colon-separated list -of three signed 64-bit integers (`int64_t`). This triple of integers `a:b:c` -represents the arithmetic sequence `a`, `a + b`, `a + 2*b`, ... `c`. - -* If it's the `n`th time that `jl_gc_pool_alloc()` has been called, and `n` - belongs to the arithmetic sequence represented by `$JULIA_GC_ALLOC_POOL`, - then garbage collection is forced. -* If it's the `n`th time that `maybe_collect()` has been called, and `n` - belongs to the arithmetic sequence represented by `$JULIA_GC_ALLOC_OTHER`, - then garbage collection is forced. -* If it's the `n`th time that `jl_gc_collect()` has been called, and `n` - belongs to the arithmetic sequence represented by `$JULIA_GC_ALLOC_PRINT`, - then counts for for the number of calls to `jl_gc_pool_alloc()` and - `maybe_collect()` are printed. - -If the character `'r'` appears as above, then the interval between garbage -collection events is randomized. +If set, these environment variables take strings that optionally start with the character +`'r'`, followed by a string interpolation of a colon-separated list of three signed 64-bit +integers (`int64_t`). This triple of integers `a:b:c` represents the arithmetic sequence +`a`, `a + b`, `a + 2*b`, ... `c`. + +* If it's the `n`th time that `jl_gc_pool_alloc()` has been called, and `n` belongs to the + arithmetic sequence represented by `$JULIA_GC_ALLOC_POOL`, then garbage collection is + forced. +* If it's the `n`th time that `maybe_collect()` has been called, and `n` belongs to the + arithmetic sequence represented by `$JULIA_GC_ALLOC_OTHER`, then garbage collection is + forced. +* If it's the `n`th time that `jl_gc_collect()` has been called, and `n` belongs to the + arithmetic sequence represented by `$JULIA_GC_ALLOC_PRINT`, then counts for the number + of calls to `jl_gc_pool_alloc()` and `maybe_collect()` are printed. + +If the value of the environment variable begins with the character `'r'`, then the interval +between garbage collection events is randomized. !!! note - these environment variables only have an effect if Julia was compiled - with garbage-collection debugging (that is, if `WITH_GC_DEBUG_ENV` is set - to `1` in the build configuration). + These environment variables only have an effect if Julia was compiled with + garbage-collection debugging (that is, if `WITH_GC_DEBUG_ENV` is set to `1` in the build + configuration). ### `JULIA_GC_NO_GENERATIONAL` -If set to anything besides `0`, then the Julia garbage collector never performs -"quick sweeps" of memory. +If set to anything besides `0`, then the Julia garbage collector never performs "quick +sweeps" of memory. !!! note - this environment variable only has an effect if Julia was compiled - with garbage-collection debugging (that is, if `WITH_GC_DEBUG_ENV` is set - to `1` in the build configuration). + This environment variable only has an effect if Julia was compiled with + garbage-collection debugging (that is, if `WITH_GC_DEBUG_ENV` is set to `1` in the build + configuration). ### `JULIA_GC_WAIT_FOR_DEBUGGER` -If set to anything besides `0`, then the Julia garbage collector will wait for -the debugger to attach instead of aborting whenever there's a critical error. +If set to anything besides `0`, then the Julia garbage collector will wait for the debugger +to attach instead of aborting whenever there's a critical error. !!! note - this environment variable only has an effect if Julia was compiled - with garbage-collection debugging (that is, if `WITH_GC_DEBUG_ENV` is set - to `1` in the build configuration). + This environment variable only has an effect if Julia was compiled with + garbage-collection debugging (that is, if `WITH_GC_DEBUG_ENV` is set to `1` in the build + configuration). ### `ENABLE_JITPROFILING` -If set to anything besides `0`, then the compiler will create and register an -event listener for just-in-time (JIT) profiling. +If set to anything besides `0`, then the compiler will create and register an event listener +for just-in-time (JIT) profiling. !!! note - this environment variable only has an effect if Julia was compiled - with JIT profiling support, using either + This environment variable only has an effect if Julia was compiled with JIT profiling + support, using either -* Intel's [VTune™ - Amplifier](https://software.intel.com/en-us/intel-vtune-amplifier-xe) +* Intel's [VTune™ Amplifier](https://software.intel.com/en-us/intel-vtune-amplifier-xe) (`USE_INTEL_JITEVENTS` set to `1` in the build configuration), or -* [OProfile](http://oprofile.sourceforge.net/news/) (`USE_OPROFILE_JITEVENTS` - set to `1` in the build configuration). +* [OProfile](http://oprofile.sourceforge.net/news/) (`USE_OPROFILE_JITEVENTS` set to `1` + in the build configuration). ### `JULIA_LLVM_ARGS` @@ -307,11 +302,12 @@ Arguments to be passed to the LLVM backend. !!! note - this environment variable has an effect only if Julia was compiled with - `JL_DEBUG_BUILD` set. + This environment variable has an effect only if Julia was compiled with `JL_DEBUG_BUILD` + set—in particular, the `julia-debug` executable is always compiled with this build + variable. ### `JULIA_DEBUG_LOADING` -If set, then Julia prints detailed information about the cache in the loading -process of [`Base.require`](@ref). +If set, then Julia prints detailed information about the cache in the loading process of +[`Base.require`](@ref).