Updated rustpkg man page to match 0.7

Author: gavinb

man/rustpkg.1

@@ -15,146 +15,168 @@ install and test Rust programs.
 
 .TP
 \fBbuild\fR
-Build all targets described in the package script in the current
-directory.
+Searches for a package with the specified name and builds it in the workspace in
+which it is found.
 .TP
 \fBclean\fR
-Remove all build files in the work cache for the package in the current
-directory.
-.TP
-\fBdo\fR
-Runs a command in the package script.
-.TP
-\fBinfo\fR
-Probe the package script in the current directory for information.
+Remove all generated files from the \fIbuild\fR directory in the target's workspace.
 .TP
 \fBinstall\fR
-Install a package given a local archive or a remote URI or VCS.
-.TP
-\fBprefer\fR
-Specify which version of a binary to use.
+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
-Build all targets described in the package script in the current directory
-with the test flag.
-.TP
-\fBuninstall\fR
-Remove a package by id or name and optionally version.
-.TP
-\fBunprefer\fR
-Remove links to the versioned binary.
-.TP
-\fBhelp\fR
-show detailed usage of a command
+Builds the module called \fItest.rs\fR in the specified workspace, and then runs
+the resulting executable in test mode.
 
-.SH "BUILD COMMAND"
+.SS "BUILD COMMAND"
 
-The \fBbuild\fR command builds all targets described in the package script in
-the current directory.
+    rustpkg build \fI[pkgname]\fR
 
-.TP
--c, --cfg
-Pass a cfg flag to the package script
+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.
 
-.SH "DO COMMAND"
+.SS "CLEAN COMMAND"
 
-The \fBdo\fR command runs a command in the package script. You can listen to a
-command by tagging a function with the attribute `#[pkg_do(cmd)]`.
+    rustpkg clean \fI[pkgname]\fR
 
-.SH "TEST COMMAND"
+deletes the contents of package's build directory.
 
-The test command is an shortcut for the command line:
+.SS "INSTALL COMMAND"
 
-    $ rustc --test <filename> -o <filestem>test~ && ./<filestem>test~
+    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
 
-Note the trailing tilde on the output filename, which should ensure the
-file does not clash with a user-generated files.
+.SS "TEST COMMAND"
 
-.SH "INFO COMMAND"
+    rustpkg test \fI[pkgname]\fR
 
-Probe the package script in the current directory for information.
+The test command is a shortcut for the command line:
 
-Options:
+    $ 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
--j, --json
-Output the result as JSON
+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 "INSTALL COMMAND"
+.SH "PATHS"
 
-    rustpkg [options..] install [url] [target]
+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.
 
-Install a package from a URL by Git or cURL (FTP, HTTP, etc.).  If target is
-provided, Git will checkout the branch or tag before continuing. If the URL
-is a TAR file (with or without compression), extract it before
-installing. If a URL isn't provided, the package will be built and installed
-from the current directory (which is functionally the same as `rustpkg
-build` and installing the result).
+In addition to the RUST_PATH settings, the following implicit paths are
+\fIalways\fR searched, in the following order:
 
-Examples:
+1. Any folders named ".rust" in the current directory, \fIand every parent\fR
+of the curent directory, up to the filesystem root;
 
-    rustpkg install
-    rustpkg install git://github.com/mozilla/servo.git
-    rustpkg install git://github.com/mozilla/servo.git v0.1.2
-    rustpkg install http://rust-lang.org/servo-0.1.2.tar.gz
+2. The system path "/usr/local" on Unix-style systems, or the equivalent on
+Windows; and
 
-Options:
+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
--c, --cfg
-Pass a cfg flag to the package script
+\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.
 
-.SH "PREFER COMMAND"
+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.
 
-By default all binaries are given a unique name so that multiple versions
-can coexist. The prefer command will symlink the uniquely named binary to
-the binary directory under its bare name. If version is not supplied, the
-latest version of the package will be preferred.
+.SH "PACKAGE IDENTIFIERS"
 
-Example:
+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.
 
-    export PATH=$PATH:/home/user/.rustpkg/bin
-    rustpkg prefer [email protected]
-    machine -v
-    ==> v1.2.4
-    rustpkg prefer [email protected]
-    machine -v
-    ==> v0.4.6
+For example, \fIgit.cakeli.workers.dev/mozilla/rust\fR is a package ID
+that would refer to the git repository browsable at \fIhttp://github.com/mozilla/rust\fR.
 
-.SH "TEST COMMAND"
+A package ID can also specify a version, like:
+\fIgit.cakeli.workers.dev/mozilla/rust#0.3\fR. In this case, \fBrustpkg\fR will check that
+the repository \fIgit.cakeli.workers.dev/mozilla/rust\fR has a tag named \fI0.3\fR, and
+report an error otherwise.
 
-Build all targets described in the package script in the current directory
-with the test flag. The test bootstraps will be run afterwards and the output
-and exit code will be redirected.
+.SH "SPECIAL MODULES"
 
-Options:
+\fBrustpkg\fR searches for four different known filenames in the src directory
+in order to determine which crates to build:
 
 .TP
--c, --cfg
-Pass a cfg flag to the package script
-
-.SH "UNINSTALL COMMAND"
+\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.
 
-Remove a package by id or name and optionally version. If the package(s)
-is/are depended on by another package then they cannot be removed.
+.SH "CRATE VERSIONS"
 
-.SH "UNPREFER COMMAND"
+\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.
 
-    $ rustpkg [options..] unprefer <id|name>[@version]
+.SH "DEPENDENCIES"
 
-Remove all symlinks from the store to the binary directory for a package
-name and optionally version. If version is not supplied, the latest version
-of the package will be unpreferred. See `rustpkg prefer -h` for more
-information.
+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 "EXAMPLES"
+.SH "CUSTOM BUILD SCRIPTS"
 
-To clone, build and install a specific version of the Servo engine from
-its git repository on Github:
-    $ rustpkg install git://github.com/mozilla/servo.git v0.1.2
+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.
 
-To download the archive and install Servo from a tarball:
-    $ rustpkg install http://rust-lang.org/servo-0.1.2.tar.gz
+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"