man/rustpkg.1

   1 .TH RUSTPKG "1" "July 2013" "rustpkg 0.7" "User Commands"
   2 .SH NAME
   3 rustpkg \- package manager for Rust applications
   4 .SH SYNOPSIS
   5 .B rustpkg
   6 [\fICOMMAND\fR] [\fIOPTIONS\fR] \fIINPUT\fR
   7
   8 .SH DESCRIPTION
   9
  10 This tool is a package manager for applications written in the Rust language,
  11 available at <\fBhttps://www.rust-lang.org\fR>. It provides commands to build,
  12 install and test Rust programs.
  13
  14 \fBrustpkg\fR is still a work in progress. See \fBdoc/rustpkg.md\fR in the Rust source distribution for future plans.
  15
  16 .SH COMMANDS
  17
  18 .TP
  19 \fBbuild\fR
  20 Searches for a package with the specified name and builds it in the workspace in
  21 which it is found.
  22 .TP
  23 \fBclean\fR
  24 Remove all generated files from the \fIbuild\fR directory in the target's workspace.
  25 .TP
  26 \fBinstall\fR
  27 Builds the specified target, and all its dependencies, and then installs the
  28 build products into the \fIlib\fR and \fIbin\fR directories of their respective
  29 workspaces.
  30 .TP
  31 \fBinit\fR
  32 Initializes the current working directory into a workspace.
  33
  34 .SS "BUILD COMMAND"
  35
  36     rustpkg build \fI[pkgname]\fR
  37
  38 The \fBbuild\fR command searches for a package with specified package name and
  39 builds it in any workspace(s) where it finds one. Any dependent packages are
  40 also built. The output files produced by the build phase are stored in the
  41 \fIbuild\fR subdirectories of each package. The executables and libraries are
  42 not copied to the 'bin' or 'lib' directories; that is the purpose of the
  43 \fBinstall\fR command.
  44
  45 .SS "CLEAN COMMAND"
  46
  47     rustpkg clean \fI[pkgname]\fR
  48
  49 deletes the contents of package's build directory.
  50
  51 .SS "INSTALL COMMAND"
  52
  53     rustpkg install \fI[url]\fR
  54
  55 builds the libraries and/or executables that are targets for the specified
  56 package name or URL, and then installs them either into package's \fIlib\fR
  57 and \fIbin\fR directories, or into the \fIlib\fR and \fIbin\fR subdirectories
  58 of the first entry in RUST_PATH.
  59
  60 Examples:
  61
  62     $ rustpkg install github.com/mozilla/servo.git#1.2
  63     $ rustpkg install rust-glfw
  64
  65 .SS "INIT COMMAND"
  66
  67     rustpkg init
  68
  69 This will turn the current working directory into a workspace. The first
  70 command you run when starting off a new project.
  71
  72 Example:
  73
  74     $ rustpkg init
  75
  76 .SH "ENVIRONMENT"
  77
  78 .TP
  79 RUST_PATH
  80 A colon-separated (semicolon-separated) list of paths denoting workspaces
  81 to search for Rust source files. See the section \fBPATHS\fR for full details.
  82
  83 .SH "PATHS"
  84
  85 The \fBrustpkg\fR tool searches for packages in the folders specified by the
  86 \fBRUST_PATH\fR environment variable. Each folder constitutes a
  87 \fIworkspace\fR, which contains one or more modules available to import.
  88
  89 In addition to the RUST_PATH settings, the following implicit paths are
  90 \fIalways\fR searched, in the following order:
  91
  92 1. Any folders named ".rust" in the current directory, \fIand every parent\fR
  93 of the curent directory, up to the filesystem root;
  94
  95 2. The system path "/usr/local" on Unix-style systems, or the equivalent on
  96 Windows; and
  97
  98 3. A folder named ".rust" in the user's home directory (ie. "~/.rust" on Unix-
  99 style systems or the equivalent on Windows).
 100
 101 .SH "PACKAGE STRUCTURE"
 102
 103 A valid workspace must contain each of the following subdirectories:
 104
 105 .TP
 106 \fBsrc/\fR
 107 Contains the Rust source code, with one subdirectory per package. Each
 108 subdirectory contains source files for a given package.
 109 .TP
 110 \fBlib/\fR
 111 "rustpkg install" installs libraries into a target-specific subdirectory of this directory.
 112 .TP
 113 \fBbin/\fR
 114 "rustpkg install" installs executable binaries into a target-specific subdirectory of this directory.
 115 .TP
 116 \fBbuild/\fR
 117 "rustpkg build" stores temporary build artifacts in a target-specific subdirectory of this directory.
 118
 119 For example, if "foo" is a workspace containing the package "bar", then
 120 "foo/src/bar/main.rs" would be the "main" entry point for building a "bar"
 121 executable.
 122
 123 .SH "PACKAGE IDENTIFIERS"
 124
 125 A package identifier uniquely identifies a package. A package can be stored in
 126 a workspace on the local file system, or on a remote Web server, in which case
 127 the package ID resembles a URL.
 128
 129 For example, \fIgithub.com/mozilla/rust\fR is a package ID
 130 that would refer to the git repository browsable at \fIhttp://github.com/mozilla/rust\fR.
 131
 132 A package ID can also specify a version, like:
 133 \fIgithub.com/mozilla/rust#0.3\fR. In this case, \fBrustpkg\fR will check that
 134 the repository \fIgithub.com/mozilla/rust\fR has a tag named \fI0.3\fR, and
 135 report an error otherwise.
 136
 137 .SH "SPECIAL MODULES"
 138
 139 \fBrustpkg\fR searches for four different known filenames in the src directory
 140 in order to determine which crates to build:
 141
 142 .TP
 143 \fBmain.rs\fR
 144 Assumed to be a main entry point for building an executable (install destination is 'bin' directory).
 145 .TP
 146 \fBlib.rs\fR
 147 Assumed to be a library crate (install destination is 'lib' directory).
 148 .TP
 149 \fBtest.rs\fR
 150 Assumed to contain tests declared with the \fI#[test]\fR attribute.
 151 .TP
 152 \fBbench.rs\fR
 153 Assumed to contain benchmarks declared with the \fI#[bench]\fR attribute.
 154
 155 .SH "CRATE VERSIONS"
 156
 157 \fBrustpkg\fR packages do not need to declare their versions with an attribute
 158 inside one of the source files, because rustpkg infers it from the version
 159 control system. When building a package that is in a git repository,
 160 rustpkg assumes that the most recent tag specifies the current version. When
 161 building a package that is not under version control, or that has no tags,
 162 rustpkg defaults the version to 0.1.
 163
 164 .SH "DEPENDENCIES"
 165
 166 rustpkg infers dependencies from "extern mod" directives. Thus, there should
 167 be no need to pass a "-L" flag to rustpkg to tell it where to find a library.
 168 (In the future, it will also be possible to write an "extern mod" directive
 169 referring to a remote package.)
 170
 171 .SH "CUSTOM BUILD SCRIPTS"
 172
 173 A file called \fIpkg.rs\fR at the root level in a workspace is called a \fIpackage
 174 script\fR. If a package script exists, rustpkg executes it to build the
 175 package rather than inferring crates as described previously.
 176
 177 Inside \fIpkg.rs\fR, it's possible to call back into rustpkg to finish up the
 178 build. The \fIrustpkg::api\fR module contains functions to build, install, or
 179 clean libraries and executables in the way rustpkg normally would without
 180 custom build logic.
 181
 182 .SH "SEE ALSO"
 183
 184 rustc, rustdoc
 185
 186 .SH "BUGS"
 187 See <\fBhttps://github.com/mozilla/rust/issues\fR> for issues.
 188
 189 .SH "AUTHOR"
 190 See \fBAUTHORS.txt\fR in the Rust source distribution. Graydon Hoare
 191 <\fIgraydon@mozilla.com\fR> is the project leader.
 192
 193 .SH "COPYRIGHT"
 194 This work is dual-licensed under Apache 2.0 and MIT terms.  See \fBCOPYRIGHT\fR
 195 file in the rust source distribution.