man/rustpkg.1 - third_party/rust - Git at Google

 .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.
 .TP
 \fBinit\fR
 Initializes the current working directory into a workspace.

 .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

 .SS "INIT COMMAND"

     rustpkg init

 This will turn the current working directory into a workspace. The first
 command you run when starting off a new project.

 Example:

     $ rustpkg init

 .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.
	.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.
	.TP
	\fBinit\fR
	Initializes the current working directory into a workspace.

	.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

	.SS "INIT COMMAND"

	rustpkg init

	This will turn the current working directory into a workspace. The first
	command you run when starting off a new project.

	Example:

	$ rustpkg init

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