ThiƩbaud Weksteen | d4f2c3c | 2020-11-03 11:08:00 +0100 | [diff] [blame] | 1 | '\" t |
| 2 | .TH "CARGO" "1" |
| 3 | .nh |
| 4 | .ad l |
| 5 | .ss \n[.ss] 0 |
| 6 | .SH "NAME" |
| 7 | cargo \- The Rust package manager |
| 8 | .SH "SYNOPSIS" |
| 9 | \fBcargo\fR [\fIoptions\fR] \fIcommand\fR [\fIargs\fR] |
| 10 | .br |
| 11 | \fBcargo\fR [\fIoptions\fR] \fB\-\-version\fR |
| 12 | .br |
| 13 | \fBcargo\fR [\fIoptions\fR] \fB\-\-list\fR |
| 14 | .br |
| 15 | \fBcargo\fR [\fIoptions\fR] \fB\-\-help\fR |
| 16 | .br |
| 17 | \fBcargo\fR [\fIoptions\fR] \fB\-\-explain\fR \fIcode\fR |
| 18 | .SH "DESCRIPTION" |
| 19 | This program is a package manager and build tool for the Rust language, |
| 20 | available at <https://rust\-lang.org>\&. |
| 21 | .SH "COMMANDS" |
| 22 | .SS "Build Commands" |
| 23 | \fBcargo\-bench\fR(1) |
| 24 | .br |
| 25 | \ \ \ \ Execute benchmarks of a package. |
| 26 | .sp |
| 27 | \fBcargo\-build\fR(1) |
| 28 | .br |
| 29 | \ \ \ \ Compile a package. |
| 30 | .sp |
| 31 | \fBcargo\-check\fR(1) |
| 32 | .br |
| 33 | \ \ \ \ Check a local package and all of its dependencies for errors. |
| 34 | .sp |
| 35 | \fBcargo\-clean\fR(1) |
| 36 | .br |
| 37 | \ \ \ \ Remove artifacts that Cargo has generated in the past. |
| 38 | .sp |
| 39 | \fBcargo\-doc\fR(1) |
| 40 | .br |
| 41 | \ \ \ \ Build a package's documentation. |
| 42 | .sp |
| 43 | \fBcargo\-fetch\fR(1) |
| 44 | .br |
| 45 | \ \ \ \ Fetch dependencies of a package from the network. |
| 46 | .sp |
| 47 | \fBcargo\-fix\fR(1) |
| 48 | .br |
| 49 | \ \ \ \ Automatically fix lint warnings reported by rustc. |
| 50 | .sp |
| 51 | \fBcargo\-run\fR(1) |
| 52 | .br |
| 53 | \ \ \ \ Run a binary or example of the local package. |
| 54 | .sp |
| 55 | \fBcargo\-rustc\fR(1) |
| 56 | .br |
| 57 | \ \ \ \ Compile a package, and pass extra options to the compiler. |
| 58 | .sp |
| 59 | \fBcargo\-rustdoc\fR(1) |
| 60 | .br |
| 61 | \ \ \ \ Build a package's documentation, using specified custom flags. |
| 62 | .sp |
| 63 | \fBcargo\-test\fR(1) |
| 64 | .br |
| 65 | \ \ \ \ Execute unit and integration tests of a package. |
| 66 | .SS "Manifest Commands" |
| 67 | \fBcargo\-generate\-lockfile\fR(1) |
| 68 | .br |
| 69 | \ \ \ \ Generate \fBCargo.lock\fR for a project. |
| 70 | .sp |
| 71 | \fBcargo\-locate\-project\fR(1) |
| 72 | .br |
| 73 | \ \ \ \ Print a JSON representation of a \fBCargo.toml\fR file's location. |
| 74 | .sp |
| 75 | \fBcargo\-metadata\fR(1) |
| 76 | .br |
| 77 | \ \ \ \ Output the resolved dependencies of a package in machine\-readable format. |
| 78 | .sp |
| 79 | \fBcargo\-pkgid\fR(1) |
| 80 | .br |
| 81 | \ \ \ \ Print a fully qualified package specification. |
| 82 | .sp |
| 83 | \fBcargo\-tree\fR(1) |
| 84 | .br |
| 85 | \ \ \ \ Display a tree visualization of a dependency graph. |
| 86 | .sp |
| 87 | \fBcargo\-update\fR(1) |
| 88 | .br |
| 89 | \ \ \ \ Update dependencies as recorded in the local lock file. |
| 90 | .sp |
| 91 | \fBcargo\-vendor\fR(1) |
| 92 | .br |
| 93 | \ \ \ \ Vendor all dependencies locally. |
| 94 | .sp |
| 95 | \fBcargo\-verify\-project\fR(1) |
| 96 | .br |
| 97 | \ \ \ \ Check correctness of crate manifest. |
| 98 | .SS "Package Commands" |
| 99 | \fBcargo\-init\fR(1) |
| 100 | .br |
| 101 | \ \ \ \ Create a new Cargo package in an existing directory. |
| 102 | .sp |
| 103 | \fBcargo\-install\fR(1) |
| 104 | .br |
| 105 | \ \ \ \ Build and install a Rust binary. |
| 106 | .sp |
| 107 | \fBcargo\-new\fR(1) |
| 108 | .br |
| 109 | \ \ \ \ Create a new Cargo package. |
| 110 | .sp |
| 111 | \fBcargo\-search\fR(1) |
| 112 | .br |
| 113 | \ \ \ \ Search packages in crates.io. |
| 114 | .sp |
| 115 | \fBcargo\-uninstall\fR(1) |
| 116 | .br |
| 117 | \ \ \ \ Remove a Rust binary. |
| 118 | .SS "Publishing Commands" |
| 119 | \fBcargo\-login\fR(1) |
| 120 | .br |
| 121 | \ \ \ \ Save an API token from the registry locally. |
| 122 | .sp |
| 123 | \fBcargo\-owner\fR(1) |
| 124 | .br |
| 125 | \ \ \ \ Manage the owners of a crate on the registry. |
| 126 | .sp |
| 127 | \fBcargo\-package\fR(1) |
| 128 | .br |
| 129 | \ \ \ \ Assemble the local package into a distributable tarball. |
| 130 | .sp |
| 131 | \fBcargo\-publish\fR(1) |
| 132 | .br |
| 133 | \ \ \ \ Upload a package to the registry. |
| 134 | .sp |
| 135 | \fBcargo\-yank\fR(1) |
| 136 | .br |
| 137 | \ \ \ \ Remove a pushed crate from the index. |
| 138 | .SS "General Commands" |
| 139 | \fBcargo\-help\fR(1) |
| 140 | .br |
| 141 | \ \ \ \ Display help information about Cargo. |
| 142 | .sp |
| 143 | \fBcargo\-version\fR(1) |
| 144 | .br |
| 145 | \ \ \ \ Show version information. |
| 146 | .SH "OPTIONS" |
| 147 | .SS "Special Options" |
| 148 | .sp |
| 149 | \fB\-V\fR, |
| 150 | \fB\-\-version\fR |
| 151 | .RS 4 |
| 152 | Print version info and exit. If used with \fB\-\-verbose\fR, prints extra |
| 153 | information. |
| 154 | .RE |
| 155 | .sp |
| 156 | \fB\-\-list\fR |
| 157 | .RS 4 |
| 158 | List all installed Cargo subcommands. If used with \fB\-\-verbose\fR, prints extra |
| 159 | information. |
| 160 | .RE |
| 161 | .sp |
| 162 | \fB\-\-explain\fR \fIcode\fR |
| 163 | .RS 4 |
| 164 | Run \fBrustc \-\-explain CODE\fR which will print out a detailed explanation of an |
| 165 | error message (for example, \fBE0004\fR). |
| 166 | .RE |
| 167 | .SS "Display Options" |
| 168 | .sp |
| 169 | \fB\-v\fR, |
| 170 | \fB\-\-verbose\fR |
| 171 | .RS 4 |
| 172 | Use verbose output. May be specified twice for "very verbose" output which |
| 173 | includes extra output such as dependency warnings and build script output. |
| 174 | May also be specified with the \fBterm.verbose\fR |
| 175 | \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. |
| 176 | .RE |
| 177 | .sp |
| 178 | \fB\-q\fR, |
| 179 | \fB\-\-quiet\fR |
| 180 | .RS 4 |
| 181 | No output printed to stdout. |
| 182 | .RE |
| 183 | .sp |
| 184 | \fB\-\-color\fR \fIwhen\fR |
| 185 | .RS 4 |
| 186 | Control when colored output is used. Valid values: |
| 187 | .sp |
| 188 | .RS 4 |
| 189 | \h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the |
| 190 | terminal. |
| 191 | .RE |
| 192 | .sp |
| 193 | .RS 4 |
| 194 | \h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. |
| 195 | .RE |
| 196 | .sp |
| 197 | .RS 4 |
| 198 | \h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. |
| 199 | .RE |
| 200 | .sp |
| 201 | May also be specified with the \fBterm.color\fR |
| 202 | \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. |
| 203 | .RE |
| 204 | .SS "Manifest Options" |
| 205 | .sp |
| 206 | \fB\-\-frozen\fR, |
| 207 | \fB\-\-locked\fR |
| 208 | .RS 4 |
| 209 | Either of these flags requires that the \fBCargo.lock\fR file is |
| 210 | up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will |
| 211 | exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from |
| 212 | attempting to access the network to determine if it is out\-of\-date. |
| 213 | .sp |
| 214 | These may be used in environments where you want to assert that the |
| 215 | \fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network |
| 216 | access. |
| 217 | .RE |
| 218 | .sp |
| 219 | \fB\-\-offline\fR |
| 220 | .RS 4 |
| 221 | Prevents Cargo from accessing the network for any reason. Without this |
| 222 | flag, Cargo will stop with an error if it needs to access the network and |
| 223 | the network is not available. With this flag, Cargo will attempt to |
| 224 | proceed without the network if possible. |
| 225 | .sp |
| 226 | Beware that this may result in different dependency resolution than online |
| 227 | mode. Cargo will restrict itself to crates that are downloaded locally, even |
| 228 | if there might be a newer version as indicated in the local copy of the index. |
| 229 | See the \fBcargo\-fetch\fR(1) command to download dependencies before going |
| 230 | offline. |
| 231 | .sp |
| 232 | May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. |
| 233 | .RE |
| 234 | .SS "Common Options" |
| 235 | .sp |
| 236 | \fB+\fR\fItoolchain\fR |
| 237 | .RS 4 |
| 238 | If Cargo has been installed with rustup, and the first argument to \fBcargo\fR |
| 239 | begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such |
| 240 | as \fB+stable\fR or \fB+nightly\fR). |
| 241 | See the \fIrustup documentation\fR <https://github.com/rust\-lang/rustup/> |
| 242 | for more information about how toolchain overrides work. |
| 243 | .RE |
| 244 | .sp |
| 245 | \fB\-h\fR, |
| 246 | \fB\-\-help\fR |
| 247 | .RS 4 |
| 248 | Prints help information. |
| 249 | .RE |
| 250 | .sp |
| 251 | \fB\-Z\fR \fIflag\fR |
| 252 | .RS 4 |
| 253 | Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. |
| 254 | .RE |
| 255 | .SH "ENVIRONMENT" |
| 256 | See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for |
| 257 | details on environment variables that Cargo reads. |
| 258 | .SH "EXIT STATUS" |
| 259 | .sp |
| 260 | .RS 4 |
| 261 | \h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. |
| 262 | .RE |
| 263 | .sp |
| 264 | .RS 4 |
| 265 | \h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. |
| 266 | .RE |
| 267 | .SH "FILES" |
| 268 | \fB~/.cargo/\fR |
| 269 | .br |
| 270 | \ \ \ \ Default location for Cargo's "home" directory where it |
| 271 | stores various files. The location can be changed with the \fBCARGO_HOME\fR |
| 272 | environment variable. |
| 273 | .sp |
| 274 | \fB$CARGO_HOME/bin/\fR |
| 275 | .br |
| 276 | \ \ \ \ Binaries installed by \fBcargo\-install\fR(1) will be located here. If using |
| 277 | rustup, executables distributed with Rust are also located here. |
| 278 | .sp |
| 279 | \fB$CARGO_HOME/config.toml\fR |
| 280 | .br |
| 281 | \ \ \ \ The global configuration file. See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/config.html> |
| 282 | for more information about configuration files. |
| 283 | .sp |
| 284 | \fB\&.cargo/config.toml\fR |
| 285 | .br |
| 286 | \ \ \ \ Cargo automatically searches for a file named \fB\&.cargo/config.toml\fR in the |
| 287 | current directory, and all parent directories. These configuration files |
| 288 | will be merged with the global configuration file. |
| 289 | .sp |
| 290 | \fB$CARGO_HOME/credentials.toml\fR |
| 291 | .br |
| 292 | \ \ \ \ Private authentication information for logging in to a registry. |
| 293 | .sp |
| 294 | \fB$CARGO_HOME/registry/\fR |
| 295 | .br |
| 296 | \ \ \ \ This directory contains cached downloads of the registry index and any |
| 297 | downloaded dependencies. |
| 298 | .sp |
| 299 | \fB$CARGO_HOME/git/\fR |
| 300 | .br |
| 301 | \ \ \ \ This directory contains cached downloads of git dependencies. |
| 302 | .sp |
| 303 | Please note that the internal structure of the \fB$CARGO_HOME\fR directory is not |
| 304 | stable yet and may be subject to change. |
| 305 | .SH "EXAMPLES" |
| 306 | .sp |
| 307 | .RS 4 |
| 308 | \h'-04' 1.\h'+01'Build a local package and all of its dependencies: |
| 309 | .sp |
| 310 | .RS 4 |
| 311 | .nf |
| 312 | cargo build |
| 313 | .fi |
| 314 | .RE |
| 315 | .RE |
| 316 | .sp |
| 317 | .RS 4 |
| 318 | \h'-04' 2.\h'+01'Build a package with optimizations: |
| 319 | .sp |
| 320 | .RS 4 |
| 321 | .nf |
| 322 | cargo build \-\-release |
| 323 | .fi |
| 324 | .RE |
| 325 | .RE |
| 326 | .sp |
| 327 | .RS 4 |
| 328 | \h'-04' 3.\h'+01'Run tests for a cross\-compiled target: |
| 329 | .sp |
| 330 | .RS 4 |
| 331 | .nf |
| 332 | cargo test \-\-target i686\-unknown\-linux\-gnu |
| 333 | .fi |
| 334 | .RE |
| 335 | .RE |
| 336 | .sp |
| 337 | .RS 4 |
| 338 | \h'-04' 4.\h'+01'Create a new package that builds an executable: |
| 339 | .sp |
| 340 | .RS 4 |
| 341 | .nf |
| 342 | cargo new foobar |
| 343 | .fi |
| 344 | .RE |
| 345 | .RE |
| 346 | .sp |
| 347 | .RS 4 |
| 348 | \h'-04' 5.\h'+01'Create a package in the current directory: |
| 349 | .sp |
| 350 | .RS 4 |
| 351 | .nf |
| 352 | mkdir foo && cd foo |
| 353 | cargo init . |
| 354 | .fi |
| 355 | .RE |
| 356 | .RE |
| 357 | .sp |
| 358 | .RS 4 |
| 359 | \h'-04' 6.\h'+01'Learn about a command's options and usage: |
| 360 | .sp |
| 361 | .RS 4 |
| 362 | .nf |
| 363 | cargo help clean |
| 364 | .fi |
| 365 | .RE |
| 366 | .RE |
| 367 | .SH "BUGS" |
| 368 | See <https://github.com/rust\-lang/cargo/issues> for issues. |
| 369 | .SH "SEE ALSO" |
| 370 | \fBrustc\fR(1), \fBrustdoc\fR(1) |