Make all command-line options documented in all related files (#53826)

I checked and updated the three related files to make sure command-line documentations are the same in all of them. Previously mentioned in #52645 (comment) --------- Co-authored-by: Matt Bauman <[email protected]>
JuliaLang · Apr 4, 2024 · a931fbe · a931fbe
1 parent 66a4fa7
commit a931fbe
Show file tree

Hide file tree

Showing 3 changed files with 72 additions and 52 deletions.
diff --git a/doc/man/julia.1 b/doc/man/julia.1
@@ -59,7 +59,7 @@ Display version information
 
 .TP
 -h, --help
-Print help message
+Print command-line options (this message)
 
 .TP
 --help-hidden
@@ -77,7 +77,7 @@ Start up with the given system image file
 
 .TP
 -H, --home <dir>
-Set location of julia executable
+Set location of `julia` executable
 
 .TP
 --startup-file={yes*|no}
@@ -95,39 +95,42 @@ Use native code from system image if available
 .TP
 --compiled-modules={yes*|no|existing|strict}
 Enable or disable incremental precompilation of modules.
-The "existing" option allows use of existing compiled modules that were previously precompiled, but disallows creation of new precompile files.
-The "strict" option is similar, but will error if no precompile file is found.
+The `existing` option allows use of existing compiled modules that were
+previously precompiled, but disallows creation of new precompile files.
+The `strict` option is similar, but will error if no precompile file is found.
 
 .TP
 --pkgimages={yes*|no|existing}
 Enable or disable usage of native code caching in the form of pkgimages
+The `existing` option allows use of existing pkgimages but disallows creation of new ones
 
 .TP
 -e, --eval <expr>
 Evaluate <expr>
 
-.TP
--m, --module <Package> [args]
-Run entry point of `Package` (`@main` function) with `args'.
-
-
 .TP
 -E, --print <expr>
 Evaluate <expr> and display the result
 
+.TP
+-m, --module <Package> [args]
+Run entry point of `Package` (`@main` function) with `args'
+
 .TP
 -L, --load <file>
 Load <file> immediately on all processors
 
 .TP
--t, --threads <n>
-Enable n threads; "auto" tries to infer a useful default number
-of threads to use but the exact behavior might change in the future.
-Currently, "auto" uses the number of CPUs assigned to this julia
-process based on the OS-specific affinity assignment interface, if
-supported (Linux and Windows). If this is not supported (macOS) or
-process affinity is not configured, it uses the number of CPU
-threads.
+-t, --threads {auto|N[,auto|M]}
+Enable N[+M] threads; N threads are assigned to the `default`
+threadpool, and if M is specified, M threads are assigned to the
+`interactive` threadpool; `auto` tries to infer a useful
+default number of threads to use but the exact behavior might change
+in the future. Currently sets N to the number of CPUs assigned to
+this Julia process based on the OS-specific affinity assignment
+interface if supported (Linux and Windows) or to the number of CPU
+threads if not supported (MacOS) or if process affinity is not
+configured, and sets M to 1.
 
 .TP
 --gcthreads=N[,M]
@@ -144,15 +147,15 @@ as the number of local CPU threads (logical cores)
 Run processes on hosts listed in <file>
 
 .TP
--i
+-i, --interactive
 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|short|auto*}
 Enable or disable startup banner
 
 .TP
@@ -180,15 +183,15 @@ Enable or disable warning for ambiguous top-level scope
 Limit usage of CPU features up to <target>; set to `help` to see the available options
 
 .TP
--O, --optimize={0,1,2*,3}
+-O, --optimize={0|1|2*|3}
 Set the optimization level (level 3 if `-O` is used without a level)
 
 .TP
---min-optlevel={0*,1,2,3}
+--min-optlevel={0*|1|2|3}
 Set a lower bound on the optimization level
 
 .TP
--g {0,1*,2}
+-g, --debug-info={0|1*|2}
 Set the level of debug info generation (level 2 if `-g` is used without a level)
 
 .TP
@@ -203,6 +206,10 @@ Emit bounds checks always, never, or respect @inbounds declarations
 --math-mode={ieee|user*}
 Always follow `ieee` floating point semantics or respect `@fastmath` declarations
 
+.TP
+--polly={yes*|no}
+Enable or disable the polyhedral optimizer Polly (overrides @polly declaration)
+
 .TP
 --code-coverage[={none*|user|all}]
 Count executions of source lines (omitting setting is equivalent to `user`)
@@ -213,17 +220,17 @@ Count executions of source lines in a file or files under a given directory. A `
 be placed before the path to indicate this option. A `@` with no path will track the current directory.
 
 .TP
- --code-coverage=tracefile.info
- Append coverage information to the LCOV tracefile (filename supports format tokens)
+--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
 --track-allocation=@<path>
-Count bytes allocated by each source line in a file or files under a given directory. A `@`
-must be placed before the path to indicate this option. A `@` with no path will track the current directory.
+Count bytes but only in files that fall under the given file path/directory.
+The `@` prefix is required to select this option. A `@` with no path will track the current directory.
 
 .TP
 --bug-report=KIND
@@ -233,7 +240,7 @@ fallbacks to the latest compatible BugReporting.jl if not. For more information,
 --bug-report=help.
 
 .TP
---heap-size-hint=<value>
+--heap-size-hint=<size>
 Forces garbage collection if memory usage is higher than the given value.
 The value may be specified as a number of bytes, optionally in units of
 KB, MB, GB, or TB, or as a percentage of physical memory with %.
@@ -275,13 +282,17 @@ Generate an assembly file (.s)
 Generate an incremental output file (rather than complete)
 
 .TP
---trace-compile={stderr,name}
+--trace-compile={stderr|name}
 Print precompile statements for methods compiled during execution or save to a path
 
 .TP
 -image-codegen
 Force generate code in imaging mode
 
+.TP
+--permalloc-pkgimg={yes|no*}
+Copy the data section of package images into memory
+
 .SH FILES AND ENVIRONMENT
 See https://docs.julialang.org/en/v1/manual/environment-variables/
 

diff --git a/doc/src/manual/command-line-interface.md b/doc/src/manual/command-line-interface.md
@@ -164,44 +164,47 @@ The following is a complete list of command-line switches available when launchi
 |Switch                                 |Description|
 |:---                                   |:---|
 |`-v`, `--version`                      |Display version information|
-|`-h`, `--help`                         |Print command-line options (this message).|
-|`--help-hidden`                        |Uncommon options not shown by `-h`|
+|`-h`, `--help`                         |Print command-line options (this message)|
+|`--help-hidden`                        |Print uncommon options not shown by `-h`|
 |`--project[={<dir>\|@.}]`              |Set `<dir>` as the active 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_DEPOT_PATH/config/startup.jl`; if [`JULIA_DEPOT_PATH`](@ref 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\|existing|strict}` |Enable or disable incremental precompilation of modules. The `existing` option allows use of existing compiled modules that were previously precompiled, but disallows creation of new precompile files. The `strict` option is similar, but will error if no precompile file is found. |
-|`--pkgimages={yes*\|no|existing}`               |Enable or disable usage of native code caching in the form of pkgimages. The `existing` option allows use of existing pkgimages but disallows creation of new ones|
+|`--compiled-modules={yes*\|no\|existing\|strict}` |Enable or disable incremental precompilation of modules. The `existing` option allows use of existing compiled modules that were previously precompiled, but disallows creation of new precompile files. The `strict` option is similar, but will error if no precompile file is found. |
+|`--pkgimages={yes*\|no\|existing}`     |Enable or disable usage of native code caching in the form of pkgimages. The `existing` option allows use of existing pkgimages but disallows creation of new ones|
 |`-e`, `--eval <expr>`                  |Evaluate `<expr>`|
 |`-E`, `--print <expr>`                 |Evaluate `<expr>` and display the result|
+|`-m`, `--module <Package> [args]`      |Run entry point of `Package` (`@main` function) with `args'|
 |`-L`, `--load <file>`                  |Load `<file>` immediately on all processors|
-|`-t`, `--threads {N\|auto}`            |Enable N threads; `auto` tries to infer a useful default number of threads to use but the exact behavior might change in the future.  Currently, `auto` uses the number of CPUs assigned to this julia process based on the OS-specific affinity assignment interface, if supported (Linux and Windows). If this is not supported (macOS) or process affinity is not configured, it uses the number of CPU threads.|
+|`-t`, `--threads {auto\|N[,auto\|M]}`  |Enable N[+M] threads; N threads are assigned to the `default` threadpool, and if M is specified, M threads are assigned to the `interactive` threadpool; `auto` tries to infer a useful default number of threads to use but the exact behavior might change in the future. Currently sets N to the number of CPUs assigned to this Julia process based on the OS-specific affinity assignment interface if supported (Linux and Windows) or to the number of CPU threads if not supported (MacOS) or if process affinity is not configured, and sets M to 1.|
 | `--gcthreads=N[,M]`                   |Use N threads for the mark phase of GC and M (0 or 1) threads for the concurrent sweeping phase of GC. N is set to half of the number of compute threads and M is set to 0 if unspecified.|
 |`-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)|
 |`--machine-file <file>`                |Run processes on hosts listed in `<file>`|
-|`-i`                                   |Interactive mode; REPL runs and `isinteractive()` is true|
+|`-i`, `--interactive`                  |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|
+|`--banner={yes\|no\|short\|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 (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`, `--debug-info={0,1*,2}`          |Set the level of debug info generation (level is 2 if `-g` is 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`, `--debug-info={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 ($)|
 |`--math-mode={ieee\|user*}`            |Always follow `ieee` floating point semantics or respect `@fastmath` declarations|
+|`--polly={yes*\|no}`                   |Enable or disable the polyhedral optimizer Polly (overrides @polly declaration)|
 |`--code-coverage[={none*\|user\|all}]` |Count executions of source lines (omitting setting is equivalent to `user`)|
 |`--code-coverage=@<path>`              |Count executions but only in files that fall under the given file path/directory. The `@` prefix is required to select this option. A `@` with no path will track the current directory.|
 |`--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")|
 |`--track-allocation=@<path>`           |Count bytes but only in files that fall under the given file path/directory. The `@` prefix is required to select this option. A `@` with no path will track the current directory.|
 |`--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 falls back to the latest compatible BugReporting.jl if not. For more information, see `--bug-report=help`.|
+|`--heap-size-hint=<size>`              |Forces garbage collection if memory usage is higher than the given value. The value may be specified as a number of bytes, optionally in units of KB, MB, GB, or TB, or as a percentage of physical memory with %.|
 |`--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)|
@@ -211,9 +214,9 @@ The following is a complete list of command-line switches available when launchi
 |`--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|
+|`--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|
-|`--heap-size-hint=<size>`              |Forces garbage collection if memory usage is higher than the given value. The value may be specified as a number of bytes, optionally in units of KB, MB, GB, or TB, or as a percentage of physical memory with %.|
+|`--permalloc-pkgimg={yes\|no*}`        |Copy the data section of package images into memory|
 
 
 !!! compat "Julia 1.1"