diff --git a/man/rust.1 b/man/rust.1 new file mode 100644 index 0000000000000..66bebb7ebe384 --- /dev/null +++ b/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 + +.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 + +.SS "TEST COMMAND" + +The \fBtest\fR command is a shortcut for the command line: + + $ rustc --test -o test~ && ./test~ + +.SS "DOC COMMAND" + +The \fBdoc\fR command is an alias for the rustdoc program. It is equivalent to: + + $ rustdoc [options] + +.SS "PKG COMMAND" + +The \fBpkg\fR command is an alias for the rustpkg program. It is equivalent to: + + $ rustpkg [options] + +.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. diff --git a/man/rustc.1 b/man/rustc.1 index 4e76749f707ee..2298d5e54554e 100644 --- a/man/rustc.1 +++ b/man/rustc.1 @@ -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 @@ -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. diff --git a/man/rustdoc.1 b/man/rustdoc.1 new file mode 100644 index 0000000000000..93a8f49898cd1 --- /dev/null +++ b/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 +Put documents here (default: .) +.TP +--output-format +markdown or html (default: html) +.TP +--output-style +doc-per-crate or doc-per-mod (default: doc-per-mod) +.TP +--pandoc-cmd +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. diff --git a/man/rusti.1 b/man/rusti.1 new file mode 100644 index 0000000000000..9f7d1733c6514 --- /dev/null +++ b/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 ...\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. diff --git a/man/rustpkg.1 b/man/rustpkg.1 new file mode 100644 index 0000000000000..1ecc8c98183c1 --- /dev/null +++ b/man/rustpkg.1 @@ -0,0 +1,172 @@ +.TH RUSTPKG "1" "July 2013" "rustpkg 0.7" "User Commands" +.SH NAME +rustpkg \- package manager for Rust applications +.SH SYNOPSIS +.B rustpkg +[\fICOMMAND\fR] [\fIOPTIONS\fR] \fIINPUT\fR + +.SH DESCRIPTION + +This tool is a package manager for applications written in the Rust language, +available at <\fBhttps://www.rust-lang.org\fR>. It provides commands to build, +install and test Rust programs. + +.SH COMMANDS + +.TP +\fBbuild\fR +Build all targets described in the package script in the current +directory. +.TP +\fBclean\fR +Remove all build files in the work cache for the package in the current +directory. +.TP +\fBdo\fR +Runs a command in the package script. +.TP +\fBinfo\fR +Probe the package script in the current directory for information. +.TP +\fBinstall\fR +Install a package given a local archive or a remote URI or VCS. +.TP +\fBprefer\fR +Specify which version of a binary to use. +.TP +\fBtest\fR +Build all targets described in the package script in the current directory +with the test flag. +.TP +\fBuninstall\fR +Remove a package by id or name and optionally version. +.TP +\fBunprefer\fR +Remove links to the versioned binary. +.TP +\fBhelp\fR +show detailed usage of a command + +.SH "BUILD COMMAND" + +The \fBbuild\fR command builds all targets described in the package script in +the current directory. + +.TP +-c, --cfg +Pass a cfg flag to the package script + +.SH "DO COMMAND" + +The \fBdo\fR command runs a command in the package script. You can listen to a +command by tagging a function with the attribute `#[pkg_do(cmd)]`. + +.SH "TEST COMMAND" + +The test command is an shortcut for the command line: + + $ rustc --test -o test~ && ./test~ + +Note the trailing tilde on the output filename, which should ensure the +file does not clash with a user-generated files. + +.SH "INFO COMMAND" + +Probe the package script in the current directory for information. + +Options: + +.TP +-j, --json +Output the result as JSON + +.SH "INSTALL COMMAND" + + rustpkg [options..] install [url] [target] + +Install a package from a URL by Git or cURL (FTP, HTTP, etc.). If target is +provided, Git will checkout the branch or tag before continuing. If the URL +is a TAR file (with or without compression), extract it before +installing. If a URL isn't provided, the package will be built and installed +from the current directory (which is functionally the same as `rustpkg +build` and installing the result). + +Examples: + + rustpkg install + rustpkg install git://github.com/mozilla/servo.git + rustpkg install git://github.com/mozilla/servo.git v0.1.2 + rustpkg install http://rust-lang.org/servo-0.1.2.tar.gz + +Options: + +.TP +-c, --cfg +Pass a cfg flag to the package script + +.SH "PREFER COMMAND" + +By default all binaries are given a unique name so that multiple versions +can coexist. The prefer command will symlink the uniquely named binary to +the binary directory under its bare name. If version is not supplied, the +latest version of the package will be preferred. + +Example: + + export PATH=$PATH:/home/user/.rustpkg/bin + rustpkg prefer machine@1.2.4 + machine -v + ==> v1.2.4 + rustpkg prefer machine@0.4.6 + machine -v + ==> v0.4.6 + +.SH "TEST COMMAND" + +Build all targets described in the package script in the current directory +with the test flag. The test bootstraps will be run afterwards and the output +and exit code will be redirected. + +Options: + +.TP +-c, --cfg +Pass a cfg flag to the package script + +.SH "UNINSTALL COMMAND" + +Remove a package by id or name and optionally version. If the package(s) +is/are depended on by another package then they cannot be removed. + +.SH "UNPREFER COMMAND" + + $ rustpkg [options..] unprefer [@version] + +Remove all symlinks from the store to the binary directory for a package +name and optionally version. If version is not supplied, the latest version +of the package will be unpreferred. See `rustpkg prefer -h` for more +information. + +.SH "EXAMPLES" + +To clone, build and install a specific version of the Servo engine from +its git repository on Github: + $ rustpkg install git://github.com/mozilla/servo.git v0.1.2 + +To download the archive and install Servo from a tarball: + $ rustpkg install http://rust-lang.org/servo-0.1.2.tar.gz + +.SH "SEE ALSO" + +rust, rustc, rustdoc, 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.