rollup merge of rust-lang#20129: nagisa/man-fixes

This pull request updates the rustc manual page to represent current state of rustc option handling better. Moved the apparently deprecated options (rust-lang#19900) to their own section and added all the new codegen options.

A bit unrelatedly, I also updated description of `-O` and `-g` flags to point to the new codegen options rather than old, deprecated ones.

Fixes rust-lang#20111.

man/rustc.1

@@ -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
@@ -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
 
@@ -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.
@@ -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:

src/librustc/session/config.rs

@@ -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"),