Doc environment variables #20162

kbdave314 · 2017-01-20T20:05:51Z

Adds a documentation section for environment variables and their defaults.

Fix #5432
Fix #19988

ararslan · 2017-01-20T20:18:46Z

Hey @kbdave314, great first Julia PR! This is very comprehensive and well thought out. I have just a few minor stylistic comments to ensure consistency with the other markdown files in the manual. Overall nice work here!

ararslan · 2017-01-20T20:20:32Z

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.


Typically we put line breaks to keep the line length down. Markdown renders a single newline as a space, so it works out just fine.

ararslan · 2017-01-20T20:21:28Z

doc/src/manual/environment-variables.md

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


It's a little mixed in the existing markdown files, but I think in general we should be using a single space after periods (or a line break—that also works) rather than two spaces.

ararslan · 2017-01-20T20:22:09Z

doc/src/manual/environment-variables.md

+
+## File locations
+
+### `JULIA_HOME`


For consistency with the other files it would be good to add a line break after the headings. It should render the same, it's just a consistency thing.

ararslan · 2017-01-20T20:23:05Z

doc/src/manual/environment-variables.md

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


There's an extra space here after the URL and before the outer closing parenthesis.

ararslan · 2017-01-20T20:24:11Z

doc/src/manual/environment-variables.md

+## 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`


These have 3 spaces after the hashes. Was that intentional? For consistency it would be better to use a single space.

ararslan · 2017-01-20T20:27:43Z

doc/src/manual/environment-variables.md

+```
+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 idea behind linking the function and variable names to locations in the source code is a good one, but the problem is that any edits to those files will change what's at the given line. It would get kind of messy for every PR to track the line numbers and update this file accordingly. So perhaps it would be better to link to documentation for the functions and/or variables if they're available, otherwise don't provide a link.

kshyatt · 2017-01-21T00:02:07Z

doc/src/manual/environment-variables.md

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


Have a link here?

kshyatt · 2017-01-21T00:03:36Z

doc/src/manual/environment-variables.md

+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


Should this be !!! warning?

kshyatt · 2017-01-21T00:05:34Z

This is a really great first PR. Welcome to Julia!

MichaelHatherly

Re: line wrapping, the manual is generally wrapped at about 92 chars rather than 80. That's just a general guideline though, so don't worry about changing that now unless it makes the paragraphs "flow" better.

Some other minor style comments in line.

MichaelHatherly · 2017-01-21T06:45:53Z

doc/src/manual/environment-variables.md

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


Double blank line can be reduced to a single one for consistency with the rest of the docs.

MichaelHatherly · 2017-01-21T06:50:09Z

doc/src/manual/environment-variables.md

+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


(@ref Base.require) should be able to be changed to just (@ref). The trailing () in Base.require() can be removed I think, since there is no zero-arg require method.

(Same applies to the other "named" @refs further down as well.)

MichaelHatherly · 2017-01-21T06:52:56Z

doc/src/manual/environment-variables.md

+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


Could perhaps use an admonition here for the note, i.e. !!! note syntax (see docs for details). Same applies to some of the other notes further down.

MichaelHatherly · 2017-01-21T06:56:07Z

doc/src/manual/environment-variables.md

@@ -0,0 +1,295 @@
+# Environment Variables in Julia


Either this title should change to # Environment Variables or the @refs that are meant to link here should be changed to [Environment Variables in Julia](@ref) otherwise the docs build will probably fail.

MichaelHatherly · 2017-01-21T07:06:35Z

doc/src/manual/environment-variables.md

+`$JULIA_HOME` is not set, then `Base.JULIA_HOME` defaults to its compile-time
+value.
+
+The executable itself is one of


Most of the docs leave a single blank line before and after triple backtick blocks. Makes it a bit easier to see where code blocks start and end if they don't specify a language.

…to admonition syntax, simplify cross-references, fix title.

omus · 2017-01-23T21:45:33Z

doc/src/manual/environment-variables.md

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


Related to #19984

omus · 2017-01-23T21:45:59Z

doc/src/manual/environment-variables.md

+
+!!! note the `fish` shell is unsupported.
+
+### `JULIA_EDITOR`, `VISUAL`, `EDITOR`


I would take VISUAL and EDITOR out of the heading as they aren't Julia specific ENV variables.

MichaelHatherly · 2017-01-24T12:18:54Z

doc/src/manual/environment-variables.md

+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


Syntax here should be

!!! note `$JULIA_EDITOR` is *not* used in the determination of the editor for [`Base.Pkg.edit`](@ref): this function checks `$VISUAL` and `$EDITOR` alone.

so the admonition body text needs to be written on a newline rather than running on from !!! note.

Same for the other admonitions in the file.

KristofferC

Very nice work. Only a few comments from me.

KristofferC · 2017-01-27T07:03:25Z

doc/src/manual/environment-variables.md

+
+!!! note
+
+    the `fish` shell is unsupported.


Support for fish shell was just merged

though not well tested

KristofferC · 2017-01-27T07:04:12Z

doc/src/manual/environment-variables.md

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


e.g. perhaps (no space)

KristofferC · 2017-01-27T07:05:28Z

doc/src/manual/environment-variables.md

+
+!!! note
+
+    input is hardcoded to be bold (`"\033[1m"`).


Not anymore.

KristofferC · 2017-01-27T07:05:41Z

doc/src/manual/environment-variables.md

+
+!!! note
+
+    output is hardcoded to be bold (`"\033[1m"`).


Not anymore.

StefanKarpinski · 2017-01-27T14:52:28Z

@KristofferC has requested a few small changes. I believe @MichaelHatherly's requested changes have been addressed? This seems very close to being ready to merge...

tkelman · 2017-01-27T15:00:51Z

There are a few places that say "64 bit integer" that may not be accurate on 32 bit Julia, those should be verified.

tkelman · 2017-01-28T03:01:48Z

doc/src/manual/environment-variables.md

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


this isn't quite right, you can move around the compiled executable and Base.JULIA_HOME will reflect the location it gets run from

tkelman · 2017-01-28T03:06:58Z

doc/src/manual/environment-variables.md

+### `JULIA_SHELL`
+
+The absolute path of the shell with which Julia should execute external
+commands (via `Base.repl_cmd()`). Defaults to the environment variable


only on unix - on windows, commands don't go through a shell

tkelman · 2017-01-28T03:07:52Z

doc/src/manual/environment-variables.md

+### `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


number of seconds

tkelman · 2017-01-28T03:12:00Z

doc/src/manual/environment-variables.md

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


"base package" isn't a term we use much, I guess you just mean functions that are under Base?

tkelman · 2017-01-28T03:14:15Z

doc/src/manual/environment-variables.md

+    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


counts for the

tkelman · 2017-01-28T03:14:56Z

doc/src/manual/environment-variables.md

+    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


what is "as above" referring to?

tkelman · 2017-01-28T03:18:58Z

doc/src/manual/environment-variables.md

+!!! note
+
+    this environment variable has an effect only if Julia was compiled with
+    `JL_DEBUG_BUILD` set.


which is enabled when building the julia-debug executable, so julia-debug always has this on

Changes addressed.

…', julia-debug.

kbdave314 · 2017-01-31T18:29:53Z

Still need to fix JULIA_HOME section.

tkelman · 2017-02-01T08:11:56Z

doc/src/manual/environment-variables.md


-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


"the debugger" sounds a little funny, doesn't it wait for any debugger?

tkelman · 2017-02-01T08:13:33Z

doc/src/manual/environment-variables.md

-    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


I'd put spaces around the dash, otherwise it looks like "set-in" is being used as a single hyphenated word

yuyichao · 2017-02-01T21:37:01Z

doc/src/manual/environment-variables.md

+
+### `JULIA_EDITOR`
+
+The editor returned by `Base.editor()` and used in, e.g., [`Base.edit`](@ref).


Should mention that this is a command and not a path.

GregPlowman · 2017-02-02T22:14:49Z

doc/src/manual/environment-variables.md

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


Should this be Base.REPL.find_hist_file() ?

fredrikekre · 2017-02-02T22:20:38Z

doc/src/manual/environment-variables.md

@@ -0,0 +1,313 @@
+# Environment Variables
+
+The environment variables that Julia uses generally start with `JULIA`. If


Should we add here in the beginning how to actually set/modify the variables? And perhaps mention that it could be done conveniently in the .juliarc.jl file?

mortenpi · 2017-04-17T22:50:39Z

Could we by any chance have a list of all the variables in the julia --help message as well? That would be convenient for quickly looking up the exact spelling without having to resort to the manual.

m-j-w · 2017-04-21T20:13:30Z

Is there a chance for this to go soon into master? I would find such an overview to really improve the documentation.
@kbdave314 If you don't find the time to address the remaining reviewer comments, I'd be happy to offer my assistance.

tkelman · 2017-04-21T20:18:46Z

@m-j-w I don't think anyone would be offended if you wanted to copy the branch to your fork, address the last few review comments and remaining todo's, and open a new PR. We can keep the attribution and existing commits to recognize the good work that @kbdave314 did to flesh this out.

Doc environment variables (Continuation of #20162)

kbdave314 added 4 commits January 20, 2017 14:45

documentation for environment variables

00c94b3

small typo

d73ce9a

forgot about make.jl

248a264

Merge branch 'master' into doc-environment-variables

3532712

ararslan added the docs This change adds or pertains to documentation label Jan 20, 2017

ararslan reviewed Jan 20, 2017

View reviewed changes

Line width to 80 characters; strip trailing spaces; line breaks after h3

797eaf0

kshyatt reviewed Jan 21, 2017

View reviewed changes

added threading/debugging entries and cross-references.

3e9d96e

MichaelHatherly previously requested changes Jan 21, 2017

View reviewed changes

kbdave314 added 2 commits January 22, 2017 12:47

Increase text width to 92 columns, cull spurious line breaks, switch …

ba92166

…to admonition syntax, simplify cross-references, fix title.

Trailing whitespace

f153d5b

kbdave314 force-pushed the doc-environment-variables branch from b62441f to f153d5b Compare January 22, 2017 23:54

yuyichao mentioned this pull request Jan 23, 2017

Document JULIA_* environment variables #19988

Closed

kbdave314 mentioned this pull request Jan 23, 2017

Julia Pkgs in NixOS NixOS/nixpkgs#20649

Closed

omus reviewed Jan 23, 2017

View reviewed changes

MichaelHatherly reviewed Jan 24, 2017

View reviewed changes

Admonition line breaks; editor envvar heading.

063e2be

KristofferC mentioned this pull request Jan 27, 2017

Improvement to Customizing Colors section #20240

Merged

KristofferC reviewed Jan 27, 2017

View reviewed changes

kbdave314 added 2 commits January 27, 2017 12:39

clarify integer types, remove outdated notes, whitespace change

672849d

whitespace

fe9b0d1

tkelman reviewed Jan 28, 2017

View reviewed changes

No windows shell, English fixes, delete reference to base, clarify 'r…

1935def

…', julia-debug.

tkelman reviewed Feb 1, 2017

View reviewed changes

yuyichao requested changes Feb 1, 2017

View reviewed changes

yuyichao mentioned this pull request Feb 1, 2017

Setting JULIA_EDITOR in Windows #20365

Closed

GregPlowman reviewed Feb 2, 2017

View reviewed changes

fredrikekre reviewed Feb 2, 2017

View reviewed changes

m-j-w mentioned this pull request Apr 21, 2017

Doc environment variables (Continuation of #20162) #21480

Merged

kbdave314 closed this Apr 21, 2017

tkelman added a commit that referenced this pull request Apr 23, 2017

Merge pull request #21480 from m-j-w/doc-environment-variables-continued

e2a4c32

Doc environment variables (Continuation of #20162)

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

		[`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.


		!!! note the `fish` shell is unsupported.

		### `JULIA_EDITOR`, `VISUAL`, `EDITOR`


		### `JULIA_EDITOR`

		The editor returned by `Base.editor()` and used in, e.g., [`Base.edit`](@ref).


		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

		@@ -0,0 +1,313 @@
		# Environment Variables

		The environment variables that Julia uses generally start with `JULIA`. If

Uh oh!

Doc environment variables #20162

Doc environment variables #20162

Uh oh!

Conversation

kbdave314 commented Jan 20, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ararslan commented Jan 20, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kshyatt commented Jan 21, 2017

Uh oh!

MichaelHatherly left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

KristofferC left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

StefanKarpinski commented Jan 27, 2017

Uh oh!

tkelman commented Jan 27, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tkelman Jan 28, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kbdave314 commented Jan 20, 2017 •

edited

Loading

tkelman Jan 28, 2017 •

edited

Loading