diff --git a/man/rust.1 b/man/rust.1 new file mode 100644 index 00000000000..66bebb7ebe3 --- /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 4e76749f707..2298d5e5455 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 00000000000..93a8f49898c --- /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 00000000000..9f7d1733c65 --- /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 00000000000..a3178e616c6 --- /dev/null +++ b/man/rustpkg.1 @@ -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 -o test~ && ./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. diff --git a/mk/install.mk b/mk/install.mk index 6745535fbca..2eb2ad47db4 100644 --- a/mk/install.mk +++ b/mk/install.mk @@ -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)