Skip to content

Commit

Permalink
Update man page with the new options
Browse files Browse the repository at this point in the history 
This pull request updates the rustc manual page to represent post-rust-lang#19900
state of rustc options better.

A bit unrelatedly, --help output is changed to fix some issues too:
  * -g and -O descriptions were changed from deprected flags to the new
    codegen flags.
  * dep-info value was moved from crate-type to emit flag.

Fixes rust-lang#20111
Fixes rust-lang#20131
  • Loading branch information
@nagisa
nagisa committed Dec 22, 2014
1 parent 34d6800 commit faa0094
Show file tree
Hide file tree
Showing 2 changed files with 83 additions and 56 deletions.
131 changes: 79 additions & 52 deletions man/rustc.1
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,75 +12,54 @@ This program is a compiler for the Rust language, available at
.SH OPTIONS

.TP
\fB\-\-crate-name NAME\fR
Specify the name of the crate being built
.TP
\fB\-\-crate-type=[bin|lib|dylib|rlib|staticlib]\fR
Configure the flavor of rust crate that is generated (default `bin`)
\fB\-h\fR, \fB\-\-help\fR
Display the help message
.TP
\fB\-\-cfg\fR SPEC
Configure the compilation environment
.TP
\fB\-\-emit=[asm,ir,bc,obj,link]\fR
Configure the output that rustc will produce
.TP
\fB\-h\fR, \fB\-\-help\fR
Display this message
.TP
\fB\-L\fR PATH
Add a directory to the library search path
.TP
\fB\-\-no\-trans\fR
Run all passes except translation; no output
\fB\-l\fR NAME[:KIND]
Link the generated crate(s) to the specified native library NAME. The optional
KIND can be one of, static, dylib, or framework. If omitted, dylib is assumed.
.TP
\fB\-\-no\-analysis\fR
Parse and expand the source, but run no analysis and produce no output
\fB\-\-crate-type\fR [bin|lib|rlib|dylib|staticlib]
Comma separated list of types of crates for the compiler to emit
.TP
\fB\-g\fR
Emit DWARF debug information into object files generated.
\fB\-\-crate-name NAME\fR
Specify the name of the crate being built
.TP
\fB\-\-debuginfo\fR LEVEL
Emit DWARF debug info to the objects created: 0 = no debug info, 1 =
line-tables only (for stacktraces and breakpoints), 2 = full debug
info with variable and type information (same as -g).
\fB\-\-emit\fR [asm|llvm-bc|llvm-ir|obj|link|dep-info]
Configure the output that rustc will produce
.TP
\fB\-\-print\fR [crate-name|output-file-names|sysroot]
Comma separated list of compiler information to print on stdout
.TP
\fB\-g\fR
Equivalent to \fI\-C\fR debuginfo=2
.TP
\fB\-O\fR
Equivalent to \fI\-\-opt\-level=2\fR
Equivalent to \fI\-C\fR opt-level=2
.TP
\fB\-o\fR FILENAME
Write output to <filename>. Ignored if more than one --emit is specified.
.TP
\fB\-\-opt\-level\fR LEVEL
Optimize with possible levels 0-3
Write output to <filename>. Ignored if multiple \fI\-\-emit\fR outputs are
specified.
.TP
\fB\-\-out\-dir\fR DIR
Write output to compiler-chosen filename in <dir>. Ignored if -o is specified.
(default the current directory)
.TP
\fB\-\-parse\-only\fR
Parse only; do not compile, assemble, or link
Write output to compiler-chosen filename in <dir>. Ignored if \fI\-o\fR is
specified. Defaults to the current directory.
.TP
\fB\-\-pretty\fR [TYPE]
Pretty-print the input instead of compiling; valid types are: normal
(un-annotated source), expanded (crates expanded), typed (crates
expanded, with type annotations), identified (fully parenthesized,
AST nodes and blocks with IDs), or flowgraph=<nodeid> (graphviz
formatted flowgraph for node)
.TP
\fB\-\-dep-info\fR [FILENAME]
Output dependency info to <filename> after compiling, in a format suitable
for use by Makefiles.
.TP
\fB\-\-sysroot\fR PATH
Override the system root
\fB\-\-explain\fR OPT
Provide a detailed explanation of an error message
.TP
\fB\-\-test\fR
Build a test harness
.TP
\fB\-\-target\fR TRIPLE
Target triple cpu-manufacturer-kernel[-os] to compile for (see
http://sources.redhat.com/autobook/autobook/autobook_17.html
for details)
Target triple cpu-manufacturer-kernel[-os] to compile for (see chapter 3.4 of
http://www.sourceware.org/autobook/ for details)
.TP
\fB\-W\fR help
Print 'lint' options and default settings
Expand All @@ -97,15 +76,30 @@ Set lint denied
\fB\-F\fR OPT, \fB\-\-forbid\fR OPT
Set lint forbidden
.TP
\fB\-Z\fR FLAG
Set internal debugging options. Use "-Z help" to print available options.
.TP
\fB\-C\fR FLAG[=VAL], \fB\-\-codegen\fR FLAG[=VAL]
Set a codegen-related flag to the value specified. Use "-C help" to print
available flags. See CODEGEN OPTIONS below
.TP
\fB\-v\fR, \fB\-\-version\fR
\fB\-V\fR, \fB\-\-version\fR
Print version info and exit
.TP
\fB\-v\fR, \fB\-\-verbose\fR
Use verbose output
.TP
\fB\-\-extern\fR NAME=PATH
Specify where an external rust library is located
.TP
\fB\-\-sysroot\fR PATH
Override the system root
.TP
\fB\-Z\fR FLAG
Set internal debugging options. Use "-Z help" to print available options.
.TP
\fB\-\-color\fR auto|always|never
Configure coloring of output:
auto = colorize, if output goes to a tty (default);
always = always colorize output;
never = never colorize output

.SH CODEGEN OPTIONS

Expand All @@ -121,6 +115,9 @@ objects.
A space-separated list of extra arguments to pass to the linker when the linker
is invoked.
.TP
\fBlto\fR
Perform LLVM link-time optimizations.
.TP
\fBtarget-cpu\fR=help
Selects a target processor. If the value is 'help', then a list of available
CPUs is printed.
Expand Down Expand Up @@ -167,8 +164,38 @@ Prefers dynamic linking to static linking.
\fBno-integrated-as\fR
Force usage of an external assembler rather than LLVM's integrated one.
.TP
\fBno-redzone\fR
Disable the use of the redzone.
.TP
\fBrelocation-model\fR=[pic,static,dynamic-no-pic]
The relocation model to use. (default: pic)
The relocation model to use. (Default: pic)
.TP
\fBcode-model\fR=[small,kernel,medium,large]
Choose the code model to use.
.TP
\fBmetadata\fR=val
Metadata to mangle symbol names with.
.TP
\fBextra-filename\fR=val
Extra data to put in each output filename.
.TP
\fBcodegen-units\fR=val
Divide crate into N units to optimize in parallel.
.TP
\fBremark\fR=val
Print remarks for these optimization passes (space separated, or "all").
.TP
\fBno-stack-check\fR
Disable checks for stack exhaustion (a memory-safety hazard!).
.TP
\fBdebuginfo\fR=val
Debug info emission level:
0 = no debug info;
1 = line-tables only (for stacktraces and breakpoints);
2 = full debug info with variable and type information.
.TP
\fBopt-level\fR=val
Optimize with possible levels 0-3

.SH "EXAMPLES"
To build an executable from a source file with a main function:
Expand Down
8 changes: 4 additions & 4 deletions src/librustc/session/config.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -664,17 +664,17 @@ pub fn short_optgroups() -> Vec<getopts::OptGroup> {
assumed.", "NAME[:KIND]"),
optmulti("", "crate-type", "Comma separated list of types of crates
for the compiler to emit",
"[bin|lib|rlib|dylib|staticlib|dep-info]"),
"[bin|lib|rlib|dylib|staticlib]"),
optopt("", "crate-name", "Specify the name of the crate being built",
"NAME"),
optmulti("", "emit", "Comma separated list of types of output for \
the compiler to emit",
"[asm|llvm-bc|llvm-ir|obj|link]"),
"[asm|llvm-bc|llvm-ir|obj|link|dep-info]"),
optmulti("", "print", "Comma separated list of compiler information to \
print on stdout",
"[crate-name|output-file-names|sysroot]"),
optflag("g", "", "Equivalent to --debuginfo=2"),
optflag("O", "", "Equivalent to --opt-level=2"),
optflag("g", "", "Equivalent to -C debuginfo=2"),
optflag("O", "", "Equivalent to -C opt-level=2"),
optopt("o", "", "Write output to <filename>", "FILENAME"),
optopt("", "out-dir", "Write output to compiler-chosen filename \
in <dir>", "DIR"),
Expand Down

1 comment on commit faa0094

@alexcrichton
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

r+ rollup

Thanks!

Please sign in to comment.