Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Create man pages for rust tools
  • Loading branch information
gavinb committed Jul 7, 2013
1 parent a9f178c commit 4f2ee0e
Show file tree
Hide file tree
Showing 5 changed files with 433 additions and 2 deletions.
111 changes: 111 additions & 0 deletions man/rust.1
@@ -0,0 +1,111 @@
.TH RUST "1" "July 2013" "rust 0.7" "User Commands"
.SH NAME
rust \- a front-end to the Rust toolchain
.SH SYNOPSIS
.B rust
[\fICOMMAND\fR] [\fIOPTIONS\fR] \fIINPUT\fR

.SH DESCRIPTION
This tool is a front-end for the Rust language, available at
<\fBhttps://www.rust-lang.org\fR>. It provides commands to
run, test and package Rust programs.

.SH COMMANDS

.TP
\fBbuild\fR
compile rust source files
.TP
\fBrun\fR
build an executable, and run it
.TP
\fBtest\fR
build a test executable, and run it
.TP
\fBdoc\fR
generate documentation from doc comments
.TP
\fBpkg\fR
download, build, install rust packages
.TP
\fBsketch\fR
run a rust interpreter
.TP
\fBhelp\fR
show detailed usage of a command

The build, run and test commands take the same parameters
as the rustc command.

.SS "BUILD COMMAND"

The \fBbuild\fR command is a shortcut for the \fBrustc\fR command line.
All options will be passed to the compiler verbatim. For example, to build
an optimised version:

$ rust build -O <filename>

.SS "RUN COMMAND"

The \fBrun\fR command is a shortcut for the \fBrustc\fR command line.
All options will be passed to the compiler verbatim, and if the compilation
is successful, the resultant executable will be invoked. For example, to
build and run an optimised version:

$ rust run -O <filename>

.SS "TEST COMMAND"

The \fBtest\fR command is a shortcut for the command line:

$ rustc --test <filename> -o <filestem>test~ && ./<filestem>test~

.SS "DOC COMMAND"

The \fBdoc\fR command is an alias for the rustdoc program. It is equivalent to:

$ rustdoc [options] <cratefile>

.SS "PKG COMMAND"

The \fBpkg\fR command is an alias for the rustpkg program. It is equivalent to:

$ rustpkg [options] <cratefile>

.SS "SKETCH COMMAND"

The \fBsketch\fR command launches the \fBrusti\fR interactive shell.

.SS "HELP COMMAND"

The \fBhelp\fR command displays a summary of available commands (ie. this text).

.SH "EXAMPLES"

To build an executable (with a main function):
$ rust build hello.rs

To build a library from a source file:
$ rust build --lib hello-lib.rs

To build and run an executable:
$ rust run hello.rs

To build an executable with unit tests and execute the tests:
$ rust test hello.rs

To create a package

.SH "SEE ALSO"
rustc, rustdoc, rustpkg, rusti

.SH "BUGS"
See <\fBhttps://github.com/mozilla/rust/issues\fR> for issues.

.SH "AUTHOR"
See \fBAUTHORS.txt\fR in the rust source distribution. Graydon Hoare
<\fIgraydon@mozilla.com\fR> is the project leader.

.SH "COPYRIGHT"
This work is dual-licensed under Apache 2.0 and MIT terms. See \fBCOPYRIGHT\fR
file in the rust source distribution.
7 changes: 5 additions & 2 deletions man/rustc.1
Expand Up @@ -86,10 +86,10 @@ Build a test harness
\fB\-\-target\fR TRIPLE
Target triple cpu-manufacturer-kernel[-os] to compile for (see
http://sources.redhat.com/autobook/autobook/autobook_17.html
for detail)
for details)
.TP
\fB\-\-target-feature\fR TRIPLE
Target-specific attributes (see llc -mattr=help for detail)
Target-specific attributes (see llc -mattr=help for details)
.TP
\fB\-\-android-cross-path\fR PATH
The path to the Android NDK
Expand Down Expand Up @@ -128,6 +128,9 @@ To build either with a crate (.rc) file:
To build an executable with debug info (experimental):
$ rustc -Z debug-info -o hello hello.rs

.SH "SEE ALSO"

rust, rustdoc, rustpkg, rusti

.SH "BUGS"
See <\fBhttps://github.com/mozilla/rust/issues\fR> for issues.
Expand Down
63 changes: 63 additions & 0 deletions man/rustdoc.1
@@ -0,0 +1,63 @@
.TH RUSTDOC "1" "July 2013" "rustdoc 0.7" "User Commands"
.SH NAME
rustdoc \- generate documentation from Rust source code
.SH SYNOPSIS
.B rustdoc
[\fIOPTIONS\fR] \fICRATEFILE\fR

.SH DESCRIPTION
This tool generates API reference documentation by extracting comments from
source code written in the Rust language, available at <\fBhttps://www.rust-
lang.org\fR>. It provides several output formats for the generated
documentation.

.SH COMMANDS

.TP
--output-dir <val>
Put documents here (default: .)
.TP
--output-format <val>
markdown or html (default: html)
.TP
--output-style <val>
doc-per-crate or doc-per-mod (default: doc-per-mod)
.TP
--pandoc-cmd <val>
Command for running pandoc
.TP
-h, --help
Print help

.SH "OUTPUT FORMATS"

The rustdoc tool can generate documentation in either the Markdown
or HTML formats. It requires the pandoc tool
<\fBhttp://johnmacfarlane.net/pandoc/\fR> for conversion features.

.SH "EXAMPLES"

To generate documentation for the source in the current directory:
$ rustdoc hello.rs

To build documentation into a subdirectory named 'doc' in the Markdown
format:
$ rustdoc --output-dir doc --output-format markdown hello.rs

The generated HTML can be viewed with any standard web browser, while
the Markdown version is well-suited for conversion into other formats.

.SH "SEE ALSO"

rust, rustc, rustpkg, rusti

.SH "BUGS"
See <\fBhttps://github.com/mozilla/rust/issues\fR> for issues.

.SH "AUTHOR"
See \fBAUTHORS.txt\fR in the rust source distribution. Graydon Hoare
<\fIgraydon@mozilla.com\fR> is the project leader.

.SH "COPYRIGHT"
This work is dual-licensed under Apache 2.0 and MIT terms. See \fBCOPYRIGHT\fR
file in the rust source distribution.
82 changes: 82 additions & 0 deletions man/rusti.1
@@ -0,0 +1,82 @@
.TH RUSTI "1" "July 2013" "rusti 0.7" "User Commands"
\" Macros
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.SH NAME
rusti \- Rust interactive shell

.SH SYNOPSIS
.B rusti

.SH DESCRIPTION

This program is a REPL (Read-Eval-Print Loop) for the Rust language, available
at <\fBhttps://www.rust-lang.org\fR>. It provides an interactive shell to
evaluate Rust expressions, functions and code snippets, and to experiment with
Rust code.

.B WARNING:
The Rust REPL is experimental and may be unstable. If you encounter problems,
please use the compiler instead.

.SH OPTIONS

Currently none.

.SH SPECIAL COMMANDS

The interactive shell evaluates all input as a sequence of Rust expressions,
except for a set of special commands prefixed by a colon ':'. These special
commands are described below:

.TP
\fB:help\fR
Display a summary of available commands.
.TP
\fB:{\\n ..lines.. \\n:}\\n\fR
execute multiline command
.TP
\fB:load <crate> ...\fR
loads given crates as dynamic libraries
.TP
\fB:clear\fR
clear the bindings
.TP
\fB:exit\fR
exit from the repl

.SH "EXAMPLES"

A simple example session, declaring a variable, defining a function,
evaluating an expression and printing the result:

.PP
.Vb
\& \fBrusti>\fR let x = 42;
\& \fBrusti>\fR fn square(n: int) -> int { n*n }
\& \fBrusti>\fR println(fmt!("%d squared is %d", x, square(x)));
\& 42 squared is 1764
.Ve

.SH "SEE ALSO"

rust, rustc, rustdoc, rustpkg

.SH "BUGS"
See <\fBhttps://github.com/mozilla/rust/issues\fR> for issues.

.SH "AUTHOR"
See \fBAUTHORS.txt\fR in the rust source distribution. Graydon Hoare
<\fIgraydon@mozilla.com\fR> is the project leader.

.SH "COPYRIGHT"
This work is dual-licensed under Apache 2.0 and MIT terms. See \fBCOPYRIGHT\fR
file in the rust source distribution.

0 comments on commit 4f2ee0e

Please sign in to comment.