rust/man/rustpkg.1

.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.