Indicate defaults in comandline help (#44223)

Co-authored-by: Gerhard Aigner <aigner@trium.de> Co-authored-by: Jameson Nash <vtjnash@gmail.com> (cherry picked from commit c6b5fa2)
JuliaLang · Mar 7, 2022 · 901ad02 · 901ad02
1 parent 406b293
commit 901ad02
Show file tree

Hide file tree

Showing 4 changed files with 192 additions and 140 deletions.
diff --git a/doc/man/julia.1 b/doc/man/julia.1
@@ -21,16 +21,18 @@
 .\" - diagnostics
 .\" - notes
 
-.TH JULIA 1 2013-12-10 Julia "Julia Programmers' Reference Guide"
+.TH JULIA 1 2022-02-17 JULIA
 
 .\" from the front page of https://julialang.org/
 .SH NAME
 julia - a high-level, high-performance dynamic programming language for technical computing
 
 .SH SYNOPSIS
-julia [option] [program] [args..]
+\fBjulia\fR [OPTIONS...] \fB--\fR [PROGRAMMFILE] [ARGS...]
+
+If a Julia source file is given as a \fIPROGRAMFILE\fP (optionally followed by
+arguments in \fIARGS\fP) Julia will execute the program and exit.
 
-.\" Taken almost verbatim from the front page of https://julialang.org/
 .SH DESCRIPTION
 Julia is a high-level, high-performance dynamic programming language
 for technical computing, with syntax that is familiar to users
@@ -49,10 +51,6 @@ For a more in-depth discussion of the rationale and advantages of Julia
 over other systems, please see the online manual:
 https://docs.julialang.org
 
-If a Julia source file is given as a \fIprogram\fP (optionally followed by
- arguments in \fIargs\fP) Julia will execute the program and exit.
-
-.\" This section was taken nearly verbatim from the output of `julia --help`
 .SH "COMMAND-LINE OPTIONS"
 
 .TP
@@ -63,6 +61,10 @@ Display version information
 -h, --help
 Print help message
 
+.TP
+--help-hidden
+Print uncommon options not shown by `-h`
+
 .TP
 --project[=<dir>/@.]
 Set <dir> as the home project/environment. The default @. option will search
@@ -73,22 +75,27 @@ found.
 -J, --sysimage <file>
 Start up with the given system image file
 
-.TP
---sysimage-native-code={yes|no}
-Use precompiled code from system image if available
-
 .TP
 -H, --home <dir>
 Set location of julia executable
 
 .TP
---startup-file={yes|no}
-Load ~/.julia/config/startup.jl
+--startup-file={yes*|no}
+Load `JULIA_DEPOT_PATH/config/startup.jl`; if `JULIA_DEPOT_PATH`
+environment variable is unset, load `~/.julia/config/startup.jl`
 
 .TP
---handle-signals={yes|no}
+--handle-signals={yes*|no}
 Enable or disable Julia's default signal handlers
 
+.TP
+--sysimage-native-code={yes*|no}
+Use native code from system image if available
+
+.TP
+--compiled-modules={yes*|no}
+Enable or disable incremental precompilation of modules
+
 .TP
 -e, --eval <expr>
 Evaluate <expr>
@@ -106,77 +113,96 @@ Load <file> immediately on all processors
 Enable n threads
 
 .TP
--p, --procs <n>
-Run n local processes
+-p, --procs {N|auto}
+Integer value N launches N additional local worker processes `auto` launches as many workers
+as the number of local CPU threads (logical cores)
 
 .TP
 --machine-file <file>
 Run processes on hosts listed in <file>
 
 .TP
 -i
-Interactive mode; REPL runs and isinteractive() is true
+Interactive mode; REPL runs and `isinteractive()` is true
+
+.TP
+-q, --quiet
+Quiet startup: no banner, suppress REPL warnings
 
 .TP
---banner={yes|no|auto}
+--banner={yes|no|auto*}
 Enable or disable startup banner
 
 .TP
---color={yes|no|auto}
+--color={yes|no|auto*}
 Enable or disable color text
 
 .TP
---history-file={yes|no}
+--history-file={yes*|no}
 Load or save history
 
 .TP
---compile={yes|no|all|min}
-Enable or disable compiler, or request exhaustive or minimal compilation
+--depwarn={yes|no*|error}
+Enable or disable syntax and method deprecation warnings (`error` turns warnings into errors)
 
 .TP
--C, --cpu-target=<target>
-Limit usage of cpu features up to <target>
+--warn-overwrite={yes|no*}
+Enable or disable method overwrite warnings
 
 .TP
--O, --optimize
-Run time-intensive code optimizations
+--warn-scope={yes*|no}
+Enable or disable warning for ambiguous top-level scope
 
 .TP
--O <n>, --optimize=<n>
-Set the optimization level to <n>
+-C, --cpu-target=<target>
+Limit usage of CPU features up to <target>; set to `help` to see the available options
 
 .TP
---min-optlevel=<n>
-Set the minimum optimization level to <n>, overriding per-module settings
+-O, --optimize={0,1,2*,3}
+Set the optimization level (level 3 if `-O` is used without a level)
 
 .TP
--g
-Enable generation of full debug info
+--min-optlevel={0*,1,2,3}
+Set a lower bound on the optimization level
 
 .TP
--g <n>
-Set the level of debug info generation to <n>
+-g {0,1*,2}
+Set the level of debug info generation (level 2 if `-g` is used without a level)
 
 .TP
---inline={yes|no}
-Control whether inlining is permitted (overrides functions declared as @inline)
+--inline={yes*|no}
+Control whether inlining is permitted, including overriding @inline declarations
 
 .TP
---check-bounds={yes|no|auto}
+--check-bounds={yes|no|auto*}
 Emit bounds checks always, never, or respect @inbounds declarations
 
 .TP
 --math-mode={ieee|user}
-Always use IEEE semantics for math (ignoring declarations),
-or adhere to declarations in source code
+Disallow or enable unsafe floating point optimizations (overrides @fastmath declaration)
 
 .TP
---depwarn={yes|no|error}
-Enable or disable syntax and method deprecation warnings ('error' turns warnings into errors)
+--code-coverage[={none*|user|all}]
+Count executions of source lines (omitting setting is equivalent to `user`)
 
 .TP
---warn-overwrite={yes|no}
-Enable or disable method overwrite warnings
+ --code-coverage=tracefile.info
+ Append coverage information to the LCOV tracefile (filename supports format tokens)
+
+.TP
+--track-allocation[={none*|user|all}]
+Count bytes allocated by each source line (omitting setting is equivalent to `user`)
+
+.TP
+--bug-report=KIND
+Launch a bug report session. It can be used to start a REPL, run a script, or evaluate
+expressions. It first tries to use BugReporting.jl installed in current environment and
+fallbacks to the latest compatible BugReporting.jl if not. For more information, see
+--bug-report=help.
+
+.TP
+--compile={yes*|no|all|min}
+Enable or disable JIT compiler, or request exhaustive or minimal compilation
 
 .TP
 --output-o <name>
@@ -186,36 +212,45 @@ Generate an object file (including system image data)
 --output-ji <name>
 Generate a system image data file (.ji)
 
+.TP
+--strip-metadata
+Remove docstrings and source location info from system image
+
+.TP
+--strip-ir
+Remove IR (intermediate representation) of compiled functions
+
+.TP
+--output-unopt-bc <name>
+Generate unoptimized LLVM bitcode (.bc)
+
 .TP
 --output-bc <name>
 Generate LLVM bitcode (.bc)
 
 .TP
---output-incremental={yes|no}
-Generate an incremental output file (rather than complete)
+--output-asm <name>
+Generate an assembly file (.s)
 
 .TP
---code-coverage={none|user|all}, --code-coverage
-Count executions of source lines (omitting setting is equivalent to 'user')
+--output-incremental={yes|no*}
+Generate an incremental output file (rather than complete)
 
 .TP
---track-allocation={none|user|all}, --track-allocation
-Count bytes allocated by each source line
+--trace-compile={stderr,name}
+Print precompile statements for methods compiled during execution or save to a path
 
-.SH FILES
-.I ~/.julia/config/startup.jl
-.RS
-Per user startup file.
-.RE
+.TP
+-image-codegen
+Force generate code in imaging mode
 
-.I /etc/julia/startup.jl
-.RS
-System-wide startup file.
-.RE
+.SH FILES AND ENVIRONMENT
+See https://docs.julialang.org/en/v1/manual/environment-variables/
 
 .SH BUGS
 Please report any bugs using the GitHub issue tracker:
 https://github.com/julialang/julia/issues?state=open
 
+
 .SH AUTHORS
 Contributors: https://github.com/JuliaLang/julia/graphs/contributors
diff --git a/doc/src/manual/command-line-options.md b/doc/src/manual/command-line-options.md
@@ -72,20 +72,20 @@ There are various ways to run Julia code and provide options, similar to those a
 julia [switches] -- [programfile] [args...]
 ```
 
-The following is a complete list of command-line switches available when launching julia, e.g.
-
+The following is a complete list of command-line switches available when launching julia (a '*' marks the default value, if applicable):
 
 |Switch                                 |Description|
 |:---                                   |:---|
 |`-v`, `--version`                      |Display version information|
 |`-h`, `--help`                         |Print command-line options (this message).|
+|`--help-hidden`                        |Uncommon options not shown by `-h`|
 |`--project[={<dir>\|@.}]`              |Set `<dir>` as the home project/environment. The default `@.` option will search through parent directories until a `Project.toml` or `JuliaProject.toml` file is found.|
 |`-J`, `--sysimage <file>`              |Start up with the given system image file|
 |`-H`, `--home <dir>`                   |Set location of `julia` executable|
-|`--startup-file={yes\|no}`             |Load `~/.julia/config/startup.jl`|
-|`--handle-signals={yes\|no}`           |Enable or disable Julia's default signal handlers|
-|`--sysimage-native-code={yes\|no}`     |Use native code from system image if available|
-|`--compiled-modules={yes\|no}`         |Enable or disable incremental precompilation of modules|
+|`--startup-file={yes*\|no}`            |Load `JULIA_DEPOT_PATH/config/startup.jl`; if `JULIA_DEPOT_PATH` environment variable is unset, load `~/.julia/config/startup.jl`|
+|`--handle-signals={yes*\|no}`          |Enable or disable Julia's default signal handlers|
+|`--sysimage-native-code={yes*\|no}`    |Use native code from system image if available|
+|`--compiled-modules={yes*\|no}`        |Enable or disable incremental precompilation of modules|
 |`-e`, `--eval <expr>`                  |Evaluate `<expr>`|
 |`-E`, `--print <expr>`                 |Evaluate `<expr>` and display the result|
 |`-L`, `--load <file>`                  |Load `<file>` immediately on all processors|
@@ -94,22 +94,35 @@ The following is a complete list of command-line switches available when launchi
 |`--machine-file <file>`                |Run processes on hosts listed in `<file>`|
 |`-i`                                   |Interactive mode; REPL runs and `isinteractive()` is true|
 |`-q`, `--quiet`                        |Quiet startup: no banner, suppress REPL warnings|
-|`--banner={yes\|no\|auto}`             |Enable or disable startup banner|
-|`--color={yes\|no\|auto}`              |Enable or disable color text|
-|`--history-file={yes\|no}`             |Load or save history|
-|`--depwarn={yes\|no\|error}`           |Enable or disable syntax and method deprecation warnings (`error` turns warnings into errors)|
-|`--warn-overwrite={yes\|no}`           |Enable or disable method overwrite warnings|
+|`--banner={yes\|no\|auto*}`            |Enable or disable startup banner|
+|`--color={yes\|no\|auto*}`             |Enable or disable color text|
+|`--history-file={yes*\|no}`            |Load or save history|
+|`--depwarn={yes\|no*\|error}`          |Enable or disable syntax and method deprecation warnings (`error` turns warnings into errors)|
+|`--warn-overwrite={yes\|no*}`          |Enable or disable method overwrite warnings|
+|`--warn-scope={yes*\|no}`              |Enable or disable warning for ambiguous top-level scope|
 |`-C`, `--cpu-target <target>`          |Limit usage of CPU features up to `<target>`; set to `help` to see the available options|
-|`-O`, `--optimize={0,1,2,3}`           |Set the optimization level (default level is 2 if unspecified or 3 if used without a level)|
-|`--min-optlevel={0,1,2,3}`             |Set the lower bound on per-module optimization (default is 0)|
-|`-g`, `-g <level>`                     |Enable or set the level of debug info generation (default level is 1 if unspecified or 2 if used without a level)|
+|`-O`, `--optimize={0,1,2*,3}`          |Set the optimization level (level is 3 if `-O` is used without a level)|
+|`--min-optlevel={0*,1,2,3}`            |Set the lower bound on per-module optimization|
+|`-g {0,1*,2}`                          |Set the level of debug info generation (level is 2 if `-g` is used without a level)|
 |`--inline={yes\|no}`                   |Control whether inlining is permitted, including overriding `@inline` declarations|
-|`--check-bounds={yes\|no\|auto}`       |Emit bounds checks always, never, or respect `@inbounds` declarations|
+|`--check-bounds={yes\|no\|auto*}`      |Emit bounds checks always, never, or respect `@inbounds` declarations|
 |`--math-mode={ieee,fast}`              |Disallow or enable unsafe floating point optimizations (overrides `@fastmath` declaration)|
-|`--code-coverage={none\|user\|all}`    |Count executions of source lines|
-|`--code-coverage`                      |equivalent to `--code-coverage=user`|
-|`--track-allocation={none\|user\|all}` |Count bytes allocated by each source line|
-|`--track-allocation`                   |equivalent to `--track-allocation=user`|
+|`--code-coverage[={none*\|user\|all}]` |Count executions of source lines (omitting setting is equivalent to `user`)|
+|`--code-coverage=tracefile.info`       |Append coverage information to the LCOV tracefile (filename supports format tokens).|
+|`--track-allocation[={none*\|user\|all}]` |Count bytes allocated by each source line (omitting setting is equivalent to "user")|
+|`--bug-report=KIND`                    |Launch a bug report session. It can be used to start a REPL, run a script, or evaluate expressions. It first tries to use BugReporting.jl installed in current environment and fallbacks to the latest compatible BugReporting.jl if not. For more nformation, see `--bug-report=help`.|
+|`--compile={yes*\|no\|all\|min}`       |Enable or disable JIT compiler, or request exhaustive or minimal compilation|
+|`--output-o <name>`                    |Generate an object file (including system image data)|
+|`--output-ji <name>`                   |Generate a system image data file (.ji)|
+|`--strip-metadata`                     |Remove docstrings and source location info from system image|
+|`--strip-ir`                           |Remove IR (intermediate representation) of compiled functions|
+|`--output-unopt-bc <name>`             |Generate unoptimized LLVM bitcode (.bc)|
+|`--output-bc <name>`                   |Generate LLVM bitcode (.bc)|
+|`--output-asm <name>`                  |Generate an assembly file (.s)|
+|`--output-incremental={yes\|no*}`      |Generate an incremental output file (rather than complete)|
+|`--trace-compile={stderr,name}`        |Print precompile statements for methods compiled during execution or save to a path|
+|`--image-codegen`                      |Force generate code in imaging mode|
+
 
 !!! compat "Julia 1.1"
     In Julia 1.0, the default `--project=@.` option did not search up from the root