auto merge of #7632 : gavinb/rust/7484_manpages, r=cmr
This patch updates the existing manpage and creates new pages for all of the rust command line tools. Closes #7484.
This commit is contained in:
commit
e95fcfafc7
|
@ -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.
|
|
@ -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.
|
||||
|
|
|
@ -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.
|
|
@ -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,0 +1,194 @@
|
|||
.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
|
||||
Searches for a package with the specified name and builds it in the workspace in
|
||||
which it is found.
|
||||
.TP
|
||||
\fBclean\fR
|
||||
Remove all generated files from the \fIbuild\fR directory in the target's workspace.
|
||||
.TP
|
||||
\fBinstall\fR
|
||||
Builds the specified target, and all its dependencies, and then installs the
|
||||
build products into the \fIlib\fR and \fIbin\fR directories of their respective
|
||||
workspaces.
|
||||
.TP
|
||||
\fBtest\fR
|
||||
Builds the module called \fItest.rs\fR in the specified workspace, and then runs
|
||||
the resulting executable in test mode.
|
||||
|
||||
.SS "BUILD COMMAND"
|
||||
|
||||
rustpkg build \fI[pkgname]\fR
|
||||
|
||||
The \fBbuild\fR command searches for a package with specified package name and
|
||||
builds it in any workspace(s) where it finds one. Any dependent packages are
|
||||
also built. The output files produced by the build phase are stored in the
|
||||
\fIbuild\fR subdirectories of each package. The executables and libraries are
|
||||
not copied to the 'bin' or 'lib' directories; that is the purpose of the
|
||||
\fBinstall\fR command.
|
||||
|
||||
.SS "CLEAN COMMAND"
|
||||
|
||||
rustpkg clean \fI[pkgname]\fR
|
||||
|
||||
deletes the contents of package's build directory.
|
||||
|
||||
.SS "INSTALL COMMAND"
|
||||
|
||||
rustpkg install \fI[url]\fR
|
||||
|
||||
builds the libraries and/or executables that are targets for the specified
|
||||
package name or URL, and then installs them either into package's \fIlib\fR
|
||||
and \fIbin\fR directories, or into the \fIlib\fR and \fIbin\fR subdirectories
|
||||
of the first entry in RUST_PATH.
|
||||
|
||||
Examples:
|
||||
|
||||
$ rustpkg install git://github.com/mozilla/servo.git#1.2
|
||||
$ rustpkg install rust-glfw
|
||||
|
||||
.SS "TEST COMMAND"
|
||||
|
||||
rustpkg test \fI[pkgname]\fR
|
||||
|
||||
The test command is a shortcut for the command line:
|
||||
|
||||
$ rustc --test <filename> -o <filestem>test~ && ./<filestem>test~
|
||||
|
||||
Note the suffix on the output filename (the word "test" followed by a tilde),
|
||||
which should ensure the file does not clash with a user-generated files.
|
||||
|
||||
.SH "ENVIRONMENT"
|
||||
|
||||
.TP
|
||||
RUST_PATH
|
||||
A colon-separated (semicolon-separated) list of paths denoting workspaces
|
||||
to search for Rust source files. See the section \fBPATHS\fR for full details.
|
||||
|
||||
.SH "PATHS"
|
||||
|
||||
The \fBrustpkg\fR tool searches for packages in the folders specified by the
|
||||
\fBRUST_PATH\fR environment variable. Each folder constitutes a
|
||||
\fIworkspace\fR, which contains one or more modules available to import.
|
||||
|
||||
In addition to the RUST_PATH settings, the following implicit paths are
|
||||
\fIalways\fR searched, in the following order:
|
||||
|
||||
1. Any folders named ".rust" in the current directory, \fIand every parent\fR
|
||||
of the curent directory, up to the filesystem root;
|
||||
|
||||
2. The system path "/usr/local" on Unix-style systems, or the equivalent on
|
||||
Windows; and
|
||||
|
||||
3. A folder named ".rust" in the user's home directory (ie. "~/.rust" on Unix-
|
||||
style systems or the equivalent on Windows).
|
||||
|
||||
.SH "PACKAGE STRUCTURE"
|
||||
|
||||
A valid workspace must contain each of the following subdirectories:
|
||||
|
||||
.TP
|
||||
\fBsrc/\fR
|
||||
Contains the Rust source code, with one subdirectory per package. Each
|
||||
subdirectory contains source files for a given package.
|
||||
.TP
|
||||
\fBlib/\fR
|
||||
"rustpkg install" installs libraries into a target-specific subdirectory of this directory.
|
||||
.TP
|
||||
\fBbin/\fR
|
||||
"rustpkg install" installs executable binaries into a target-specific subdirectory of this directory.
|
||||
.TP
|
||||
\fBbuild/\fR
|
||||
"rustpkg build" stores temporary build artifacts in a target-specific subdirectory of this directory.
|
||||
|
||||
For example, if "foo" is a workspace containing the package "bar", then
|
||||
"foo/src/bar/main.rs" would be the "main" entry point for building a "bar"
|
||||
executable.
|
||||
|
||||
.SH "PACKAGE IDENTIFIERS"
|
||||
|
||||
A package identifier uniquely identifies a package. A package can be stored in
|
||||
a workspace on the local file system, or on a remote Web server, in which case
|
||||
the package ID resembles a URL.
|
||||
|
||||
For example, \fIgithub.com/mozilla/rust\fR is a package ID
|
||||
that would refer to the git repository browsable at \fIhttp://github.com/mozilla/rust\fR.
|
||||
|
||||
A package ID can also specify a version, like:
|
||||
\fIgithub.com/mozilla/rust#0.3\fR. In this case, \fBrustpkg\fR will check that
|
||||
the repository \fIgithub.com/mozilla/rust\fR has a tag named \fI0.3\fR, and
|
||||
report an error otherwise.
|
||||
|
||||
.SH "SPECIAL MODULES"
|
||||
|
||||
\fBrustpkg\fR searches for four different known filenames in the src directory
|
||||
in order to determine which crates to build:
|
||||
|
||||
.TP
|
||||
\fBmain.rs\fR
|
||||
Assumed to be a main entry point for building an executable (install destination is 'bin' directory).
|
||||
.TP
|
||||
\fBlib.rs\fR
|
||||
Assumed to be a library crate (install destination is 'lib' directory).
|
||||
.TP
|
||||
\fBtest.rs\fR
|
||||
Assumed to contain tests declared with the \fI#[test]\fR attribute.
|
||||
.TP
|
||||
\fBbench.rs\fR
|
||||
Assumed to contain benchmarks declared with the \fI#[bench]\fR attribute.
|
||||
|
||||
.SH "CRATE VERSIONS"
|
||||
|
||||
\fBrustpkg\fR packages do not need to declare their versions with an attribute
|
||||
inside one of the source files, because rustpkg infers it from the version
|
||||
control system. When building a package that is in a git repository,
|
||||
rustpkg assumes that the most recent tag specifies the current version. When
|
||||
building a package that is not under version control, or that has no tags,
|
||||
rustpkg defaults the version to 0.1.
|
||||
|
||||
.SH "DEPENDENCIES"
|
||||
|
||||
rustpkg infers dependencies from "extern mod" directives. Thus, there should
|
||||
be no need to pass a "-L" flag to rustpkg to tell it where to find a library.
|
||||
(In the future, it will also be possible to write an "extern mod" directive
|
||||
referring to a remote package.)
|
||||
|
||||
.SH "CUSTOM BUILD SCRIPTS"
|
||||
|
||||
A file called \fIpkg.rs\fR at the root level in a workspace is called a \fIpackage
|
||||
script\fR. If a package script exists, rustpkg executes it to build the
|
||||
package rather than inferring crates as described previously.
|
||||
|
||||
Inside \fIpkg.rs\fR, it's possible to call back into rustpkg to finish up the
|
||||
build. The \fIrustpkg::api\fR module contains functions to build, install, or
|
||||
clean libraries and executables in the way rustpkg normally would without
|
||||
custom build logic.
|
||||
|
||||
.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.
|
|
@ -150,8 +150,11 @@ install-host: $(CSREQ$(ISTAGE)_T_$(CFG_BUILD_TRIPLE)_H_$(CFG_BUILD_TRIPLE))
|
|||
$(Q)$(call INSTALL_LIB,$(LIBRUSTDOC_GLOB_$(CFG_BUILD_TRIPLE)))
|
||||
$(Q)$(call INSTALL,$(HL),$(PHL),$(CFG_RUNTIME_$(CFG_BUILD_TRIPLE)))
|
||||
$(Q)$(call INSTALL,$(HL),$(PHL),$(CFG_RUSTLLVM_$(CFG_BUILD_TRIPLE)))
|
||||
$(Q)$(call INSTALL,$(S)/man, \
|
||||
$(PREFIX_ROOT)/share/man/man1,rustc.1)
|
||||
$(Q)$(call INSTALL,$(S)/man, $(PREFIX_ROOT)/share/man/man1,rust.1)
|
||||
$(Q)$(call INSTALL,$(S)/man, $(PREFIX_ROOT)/share/man/man1,rustc.1)
|
||||
$(Q)$(call INSTALL,$(S)/man, $(PREFIX_ROOT)/share/man/man1,rustdoc.1)
|
||||
$(Q)$(call INSTALL,$(S)/man, $(PREFIX_ROOT)/share/man/man1,rusti.1)
|
||||
$(Q)$(call INSTALL,$(S)/man, $(PREFIX_ROOT)/share/man/man1,rustpkg.1)
|
||||
|
||||
install-targets: $(INSTALL_TARGET_RULES)
|
||||
|
||||
|
|
Loading…
Reference in New Issue