e1507f3120
Closes #9221. "rustpkg test" isn't implemented yet, so it shouldn't be in the manpage. Referring interested parties to the manual is probably the right thing for now; eventually, these documents should merge.
182 lines
6.1 KiB
Groff
182 lines
6.1 KiB
Groff
.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.
|
|
|
|
\fBrustpkg\fR is still a work in progress. See \fBdoc/rustpkg.md\fR in the Rust source distribution for future plans.
|
|
|
|
.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.
|
|
|
|
.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 github.com/mozilla/servo.git#1.2
|
|
$ rustpkg install rust-glfw
|
|
|
|
.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.
|