Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Indicate defaults in comandline help #44223

Merged
merged 11 commits into from
Feb 25, 2022
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}]
laborg marked this conversation as resolved.
Show resolved Hide resolved
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")|
laborg marked this conversation as resolved.
Show resolved Hide resolved
|`--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