Merge pull request #1713 from killerswan/manpg

Updating the manpage and usage message

man/rustc.1

@@ -1,6 +1,8 @@
-.TH RUSTC "1" "October 2011" "Rust" "User Commands"
+.TH RUSTC "1" "January 2012" "Rust" "User Commands"
+
 .SH NAME
 rustc \- rust compiler
+
 .SH SYNOPSIS
 rustc [\fB-h\fR] [\fB-v\fR] [\fB-o\fR \fIoutfile\fR]
       [\fB--lib\fR] [\fB--static\fR] [\fB-L\fR \fIpath\fR]
@@ -8,130 +10,125 @@ rustc [\fB-h\fR] [\fB-v\fR] [\fB-o\fR \fIoutfile\fR]
 .PP
 Only the most commonly-used options are listed here. All options are listed and
 described below.
+
 .SH DESCRIPTION
 This program is a compiler for the Rust language, available at
 <\fBhttps://www.rust-lang.org\fR>.
+
 .SH OPTIONS
 .TP
-\fB-h, --help\fR:
-Display help.
+\fB--bin\fR
+Compile an executable crate (default)
 .TP
-\fB-v, --version\fR:
-Display version information.
+\fB-c\fR
+Compile and assemble, but do not link
 .TP
-\fB-o\fR \fIfilename\fR:
-Write output to \fIfilename\fR. The default
-output filename for \fBfoo.rs\fR is otherwise \fBfoo\fR plus any
-platform-specific extension (when compiling a binary), a
-platform-specific name, e.g. \fBlibfoo.so\fR (when compiling a
-library), \fBfoo.o\fR (when using \fB-c\fR), \fBfoo.s\fR (when using
-\fB-S\fR) or \fBfoo.bc\fR (when using \fB--emit-llvm\fR), and \fBfoo.ll\fR
-(when using both \fB-S\fR and \fB--emit-llvm\fR).
+\fB--cfg <cfgspec>\fR
+Configure the compilation environment
 .TP
-\fB--lib\fR:
-Compile and link a library crate into a shared object.
+\fB--emit-llvm\fR
+Produce an LLVM bitcode file
 .TP
-\fB--static\fR:
-Produce a statically-linked binary, or generate a static
-library.
+\fB-g\fR
+Produce debug info
 .TP
-\fB--pretty\fR \fI[type]\fR:
-Pretty-print the input. Valid \fItype\fRs are:
-.RS
+\fB--gc\fR
+Garbage collect shared data (experimental/temporary)
 .TP
-\fBnormal\fR: Un-annotated source (default).
+\fB-h --help\fR
+Display this message
 .TP
-\fBexpanded\fR: Crates expanded.
+\fB-L <path>\fR
+Add a directory to the library search path
 .TP
-\fBtyped\fR: Crates expanded, all expressions annotated with types.
+\fB--lib\fR
+Compile a library crate
 .TP
-\fBidentified\fR: Fully parenthesized, ast nodes and blocks annotated with IDs.
-.RE
+\fB--ls\fR
+List the symbols defined by a compiled librar crate
 .TP
-\fB--ls\fR:
-Lists symbols defined by the specified \fBcompiled\fR library.
+\fB--no-asm-comments\fR
+Do not add comments into the assembly source
 .TP
-\fB-L\fR \fIpath\fR:
-Adds \fIpath\fR to the library search path.
+\fB--no-lint-ctypes\fR
+Suppress warnings for possibly incorrect ctype usage
 .TP
-\fB--noverify\fR:
-Disables LLVM verification pass, which does sanity checking of
-bitcode generated by rustc. Using this option gives a slight speedup, at the
-cost of vastly reduced ability to catch rustc bugs. See
-<\fBhttp://llvm.org/docs/Passes.html\fR> for a list of properties checked.
+\fB--no-trans\fR
+Run all passes except translation; no output
 .TP
-\fB--parse-only\fR:
-Run the parse phase only. If parsing succeeds, produces no
-output.
+\fB--no-verify\fR
+Suppress LLVM verification step (slight speedup)
+(see http://llvm.org/docs/Passes.html for detail)
 .TP
-\fB--no-trans\fR:
-Run all passes except translation. Produces no output.
+\fB-O\fR
+Equivalent to --opt-level=2
 .TP
-\fB-g\fR:
-Produce debug info.
+\fB-o <filename>\fR
+Write output to <filename>
 .TP
-\fB--opt-level\fR \fIlevel\fR:
-Set optimization level to \fIlevel\fR.
+\fB--opt-level <lvl>\fR
+Optimize with possible levels 0-3
 .TP
-\fB-O\fR:
-Equal to --opt-level=2
+\fB--out-dir <dir>\fR
+Write output to compiler-chosen filename in <dir>
 .TP
-\fB-S\fR:
-Compile to assembly, but do not assemble or link.
+\fB--parse-only\fR
+Parse only; do not compile, assemble, or link
 .TP
-\fB-c\fR:
-Compile and assemble, but do not link.
+\fB--pretty [type]\fR
+Pretty-print the input instead of compiling; valid types are: \fBnormal\fR (un-annotated source), \fBexpanded\fR (crates expanded), \fBtyped\fR (crates expanded, with type annotations), or \fBidentified\fR (fully parenthesized, AST nodes and blocks with IDs)
 .TP
-\fB--emit-llvm\fR:
-Generate output files in LLVM format. When used with \fB-S\fR this generate LLVM
-intermediate language assembly files, otherwise this generates LLVM bitcode
-format object files. 
+\fB-S\fR
+Compile only; do not assemble or link
 .TP
-\fB--save-temps\fR:
-For foo.rs, save generated bitcode before optimization to
-\fBfoo.bc\fR, bitcode after optimization to \fBfoo.opt.bc\fR, and the generated
-object file to \fBfoo.o\fR.
+\fB--save-temps\fR
+Write intermediate files (.bc, .opt.bc, .o) in addition to normal output
 .TP
-\fB--stats\fR:
-Print statistics about compilation.
+\fB--static\fR
+Use or produce static libraries or binaries
 .TP
-\fB--cfg\fR \fIcfgspec\fR:
-Provide a crate config spec.
+\fB--stats\fR
+Print compilation statistics
 .TP
-\fB--time-passes\fR:
-Print runtimes of compilation phases.
+\fB--sysroot <path>\fR
+Override the system root
 .TP
-\fB--time-llvm-passes\fR:
-Print runtimes of llvm phases.
+\fB--test\fR
+Build test harness
 .TP
-\fB--sysroot\fR \fIpath\fR:
-Set the system root. Default is the directory above
-rustc's.
+\fB--target <triple>\fR
+Target cpu-manufacturer-kernel[-os] to compile for (default: host triple)
+(see http://sources.redhat.com/autobook/autobook/autobook_17.html for detail)
 .TP
-\fB--target\fR \fIgnu-config-name\fR:
-Set the compilation target, which is a
-string of the form \fBcpu\fR-\fBmanufacturer\fR-\fBkernel\fR[-\fBos\fR]. Example
-values include "i686-unknown-linux-gnu" and "mips-idt-ecoff"; see
-<\fBhttp://sources.redhat.com/autobook/autobook/autobook_17.html\fR>. If not
-supplied, the host triple is used (see \fB--version\fR output).
+\fB--time-passes\fR
+Time the individual phases of the compiler
 .TP
-\fB--test\fR:
-Build a test harness.
+\fB--time-llvm-passes\fR
+Time the individual phases of the LLVM backend
 .TP
-\fB--gc\fR:
-\fBEXPERIMENTAL\fR. Garbage-collect shared data.
+\fB-v --version\fR
+Print version info and exit
 .TP
-\fB--warn-unused-imports\fR:
-Warn about unnecessary imports.
-.TP
-\fB--no-lint-ctypes\fR:
-Disables checking of possibly incorrect usage of Rust int or uint types in
-native function declarations, where types defined in libcore::ctypes should be
-used instead. Ctypes check emits warnings by default.
+\fB--warn-unused-imports\fR
+Warn about unnecessary imports
+
+.SH "EXAMPLES"
+To build an executable from a source file with a main function:
+    $ rustc -o hello hello.rs
+
+To build a library from a source file:
+    $ rustc --lib hello-lib.rs
+
+To build either with a crate (.rc) file:
+    $ rustc hello.rc
+
 .SH "BUGS"
 See \fBhttps://github.com/mozilla/rust/issues\fR for a list of known bugs.
+
 .SH "AUTHOR"
 See \fBAUTHORS.txt\fR in the rust source distribution. Graydon Hoare
 <\fIgraydon@mozilla.com\fR> is the project leader.
+
 .SH "COPYRIGHT"
 See \fBLICENSE.txt\fR in the rust source distribution.
+

src/comp/driver/rustc.rs

@@ -21,43 +21,52 @@ fn version(argv0: str) {
 }
 
 fn usage(argv0: str) {
-    io::stdout().write_str(#fmt["usage: %s [options] <input>\n", argv0] +
+    io::stdout().write_str(#fmt["Usage: %s [options] <input>\n", argv0] +
                                "
-options:
+Options:
 
-    -h --help          display this message
-    -v --version       print version info and exit
+    --bin              Compile an executable crate (default)
+    -c                 Compile and assemble, but do not link
+    --cfg <cfgspec>    Configure the compilation environment
+    --emit-llvm        Produce an LLVM bitcode file
+    -g                 Produce debug info
+    --gc               Garbage collect shared data (experimental/temporary)
+    -h --help          Display this message
+    -L <path>          Add a directory to the library search path
+    --lib              Compile a library crate
+    --ls               List the symbols defined by a compiled library crate
+    --no-asm-comments  Do not add comments into the assembly source
+    --no-lint-ctypes   Suppress warnings for possibly incorrect ctype usage
+    --no-trans         Run all passes except translation; no output
+    --no-verify        Suppress LLVM verification step (slight speedup)
+                       (see http://llvm.org/docs/Passes.html for detail)
+    -O                 Equivalent to --opt-level=2
+    -o <filename>      Write output to <filename>
+    --opt-level <lvl>  Optimize with possible levels 0-3
+    --out-dir <dir>    Write output to compiler-chosen filename in <dir>
+    --parse-only       Parse only; do not compile, assemble, or link
+    --pretty [type]    Pretty-print the input instead of compiling;
+                       valid types are: normal (un-annotated source), 
+                       expanded (crates expanded), typed (crates expanded,
+                       with type annotations), or identified (fully
+                       parenthesized, AST nodes and blocks with IDs)
+    -S                 Compile only; do not assemble or link
+    --save-temps       Write intermediate files (.bc, .opt.bc, .o)
+                       in addition to normal output
+    --static           Use or produce static libraries or binaries
+    --stats            Print compilation statistics
+    --sysroot <path>   Override the system root
+    --test             Build a test harness
+    --target <triple>  Target cpu-manufacturer-kernel[-os] to compile for
+                       (default: host triple)
+                       (see http://sources.redhat.com/autobook/autobook/
+                       autobook_17.html for detail)
 
-    -o <filename>      write output to <filename>
-    --out-dir <dir>    write output to compiler-chosen filename in <dir>
-    --lib              compile a library crate
-    --bin              compile an executable crate (default)
-    --static           use or produce static libraries
-    --pretty [type]    pretty-print the input instead of compiling
-    --ls               list the symbols defined by a crate file
-    -L <path>          add a directory to the library search path
-    --no-verify        suppress LLVM verification step (slight speedup)
-    --parse-only       parse only; do not compile, assemble, or link
-    --no-trans         run all passes except translation; no output
-    -g                 produce debug info
-    --opt-level <lvl>  optimize with possible levels 0-3
-    -O                 equivalent to --opt-level=2
-    -S                 compile only; do not assemble or link
-    --no-asm-comments  do not add comments into the assembly source
-    -c                 compile and assemble, but do not link
-    --emit-llvm        produce an LLVM bitcode file
-    --save-temps       write intermediate files in addition to normal output
-    --stats            gather and report various compilation statistics
-    --cfg <cfgspec>    configure the compilation environment
-    --time-passes      time the individual phases of the compiler
-    --time-llvm-passes time the individual phases of the LLVM backend
-    --sysroot <path>   override the system root
-    --target <triple>  target to compile for (default: host triple)
-    --test             build test harness
-    --gc               garbage collect shared data (experimental/temporary)
+    --time-passes      Time the individual phases of the compiler
+    --time-llvm-passes Time the individual phases of the LLVM backend
+    -v --version       Print version info and exit
     --warn-unused-imports
-                       warn about unnecessary imports
-    --no-lint-ctypes   suppress lint-style ctypes usage check
+                       Warn about unnecessary imports
 
 ");
 }