RUSTPKG(1)

NAME
rustpkg - package manager for Rust applications

SYNOPSIS
rustpkg [COMMAND] [OPTIONS] INPUT

DESCRIPTION
This tool is a package manager for applications written in the Rust language, available at <https://www.rust-lang.org>. It provides commands to build, install and test Rust programs.

COMMANDS

build
    Searches for a package with the specified name and builds it in the workspace in which it is found.

clean
    Remove all generated files from the build directory in the target's workspace.

install
    Builds the specified target, and all its dependencies, and then installs the build products into the lib and bin directories of their respective workspaces.

test
    Builds the module called test.rs in the specified workspace, and then runs the resulting executable in test mode.

  BUILD COMMAND
    rustpkg build [pkgname] The build 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 build subdirectories of each package. The executables and libraries are not copied to the 'bin' or 'lib' directories; that is the purpose of the install command.

  CLEAN COMMAND
    rustpkg clean [pkgname] deletes the contents of package's build directory.

  INSTALL COMMAND
    rustpkg install [url] builds the libraries and/or executables that are targets for the specified package name or URL, and then installs them either into package's lib and bin directories, or into the lib and bin subdirectories of the first entry in RUST_PATH. Examples:
    $ rustpkg install git://github.com/mozilla/servo.git#1.2
    $ rustpkg install rust-glfw

  TEST COMMAND
    rustpkg test [pkgname] 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.

ENVIRONMENT

RUST_PATH
    A colon-separated (semicolon-separated) list of paths denoting workspaces to search for Rust source files. See the section PATHS for full details.

PATHS
The rustpkg tool searches for packages in the folders specified by the RUST_PATH environment variable. Each folder constitutes a workspace, which contains one or more modules available to import. In addition to the RUST_PATH settings, the following implicit paths are always searched, in the following order: 1. Any folders named ".rust" in the current directory, and every parent 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).

PACKAGE STRUCTURE
A valid workspace must contain each of the following subdirectories:

src/
    Contains the Rust source code, with one subdirectory per package. Each subdirectory contains source files for a given package.

lib/
    "rustpkg install" installs libraries into a target-specific subdirectory of this directory.

bin/
    "rustpkg install" installs executable binaries into a target-specific subdirectory of this directory.

build/
    "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.

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, github.com/mozilla/rust is a package ID that would refer to the git repository browsable at http://github.com/mozilla/rust. A package ID can also specify a version, like: github.com/mozilla/rust#0.3. In this case, rustpkg will check that the repository github.com/mozilla/rust has a tag named 0.3, and report an error otherwise.

SPECIAL MODULES
rustpkg searches for four different known filenames in the src directory in order to determine which crates to build:

main.rs
    Assumed to be a main entry point for building an executable (install destination is 'bin' directory).

lib.rs
    Assumed to be a library crate (install destination is 'lib' directory).

test.rs
    Assumed to contain tests declared with the #[test] attribute.

bench.rs
    Assumed to contain benchmarks declared with the #[bench] attribute.

CRATE VERSIONS
rustpkg 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.

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

CUSTOM BUILD SCRIPTS
A file called pkg.rs at the root level in a workspace is called a package script. If a package script exists, rustpkg executes it to build the package rather than inferring crates as described previously. Inside pkg.rs, it's possible to call back into rustpkg to finish up the build. The rustpkg::api module contains functions to build, install, or clean libraries and executables in the way rustpkg normally would without custom build logic.

SEE ALSO
rust, rustc, rustdoc, rusti

BUGS
See <https://github.com/mozilla/rust/issues> for issues.

AUTHOR
See AUTHORS.txt in the rust source distribution. Graydon Hoare <graydon@mozilla.com> is the project leader.

COPYRIGHT
This work is dual-licensed under Apache 2.0 and MIT terms. See COPYRIGHT file in the rust source distribution.