Skip to content

Commit

Permalink
Indicate defaults in comandline help (JuliaLang#44223)
Browse files Browse the repository at this point in the history
Co-authored-by: Gerhard Aigner <aigner@trium.de>
Co-authored-by: Jameson Nash <vtjnash@gmail.com>
  • Loading branch information
3 people authored and LilithHafner committed Mar 8, 2022
1 parent 3d41401 commit 0eb8555
Show file tree
Hide file tree
Showing 4 changed files with 196 additions and 146 deletions.
151 changes: 93 additions & 58 deletions doc/man/julia.1
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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>
Expand All @@ -112,77 +119,96 @@ process affinity is not configured, it uses the number of CPU
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>
Expand All @@ -192,36 +218,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
51 changes: 31 additions & 20 deletions doc/src/manual/command-line-options.md
Original file line number Diff line number Diff line change
Expand Up @@ -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|
Expand All @@ -94,23 +94,34 @@ 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"
Expand Down
Loading

0 comments on commit 0eb8555

Please sign in to comment.