| '\" t |
| .\" Title: cargo |
| .\" Author: [see the "AUTHOR(S)" section] |
| .\" Generator: Asciidoctor 2.0.10 |
| .\" Date: 2019-12-04 |
| .\" Manual: \ \& |
| .\" Source: \ \& |
| .\" Language: English |
| .\" |
| .TH "CARGO" "1" "2019-12-04" "\ \&" "\ \&" |
| .ie \n(.g .ds Aq \(aq |
| .el .ds Aq ' |
| .ss \n[.ss] 0 |
| .nh |
| .ad l |
| .de URL |
| \fI\\$2\fP <\\$1>\\$3 |
| .. |
| .als MTO URL |
| .if \n[.g] \{\ |
| . mso www.tmac |
| . am URL |
| . ad l |
| . . |
| . am MTO |
| . ad l |
| . . |
| . LINKSTYLE blue R < > |
| .\} |
| .SH "NAME" |
| cargo \- The Rust package manager |
| .SH "SYNOPSIS" |
| .sp |
| \fBcargo [\fIOPTIONS\fP] \fICOMMAND\fP [\fIARGS\fP]\fP |
| .br |
| \fBcargo [\fIOPTIONS\fP] \-\-version\fP |
| .br |
| \fBcargo [\fIOPTIONS\fP] \-\-list\fP |
| .br |
| \fBcargo [\fIOPTIONS\fP] \-\-help\fP |
| .br |
| \fBcargo [\fIOPTIONS\fP] \-\-explain \fICODE\fP\fP |
| .SH "DESCRIPTION" |
| .sp |
| This program is a package manager and build tool for the Rust language, |
| available at \c |
| .URL "https://rust\-lang.org" "" "." |
| .SH "COMMANDS" |
| .SS "Build Commands" |
| .sp |
| \fBcargo\-bench\fP(1) |
| .RS 4 |
| Execute benchmarks of a package. |
| .RE |
| .sp |
| \fBcargo\-build\fP(1) |
| .RS 4 |
| Compile a package. |
| .RE |
| .sp |
| \fBcargo\-check\fP(1) |
| .RS 4 |
| Check a local package and all of its dependencies for errors. |
| .RE |
| .sp |
| \fBcargo\-clean\fP(1) |
| .RS 4 |
| Remove artifacts that Cargo has generated in the past. |
| .RE |
| .sp |
| \fBcargo\-doc\fP(1) |
| .RS 4 |
| Build a package\(cqs documentation. |
| .RE |
| .sp |
| \fBcargo\-fetch\fP(1) |
| .RS 4 |
| Fetch dependencies of a package from the network. |
| .RE |
| .sp |
| \fBcargo\-fix\fP(1) |
| .RS 4 |
| Automatically fix lint warnings reported by rustc. |
| .RE |
| .sp |
| \fBcargo\-run\fP(1) |
| .RS 4 |
| Run a binary or example of the local package. |
| .RE |
| .sp |
| \fBcargo\-rustc\fP(1) |
| .RS 4 |
| Compile a package, and pass extra options to the compiler. |
| .RE |
| .sp |
| \fBcargo\-rustdoc\fP(1) |
| .RS 4 |
| Build a package\(cqs documentation, using specified custom flags. |
| .RE |
| .sp |
| \fBcargo\-test\fP(1) |
| .RS 4 |
| Execute unit and integration tests of a package. |
| .RE |
| .SS "Manifest Commands" |
| .sp |
| \fBcargo\-generate\-lockfile\fP(1) |
| .RS 4 |
| Generate \fBCargo.lock\fP for a project. |
| .RE |
| .sp |
| \fBcargo\-locate\-project\fP(1) |
| .RS 4 |
| Print a JSON representation of a \fBCargo.toml\fP file\(cqs location. |
| .RE |
| .sp |
| \fBcargo\-metadata\fP(1) |
| .RS 4 |
| Output the resolved dependencies of a package, the concrete used versions |
| including overrides, in machine\-readable format. |
| .RE |
| .sp |
| \fBcargo\-pkgid\fP(1) |
| .RS 4 |
| Print a fully qualified package specification. |
| .RE |
| .sp |
| \fBcargo\-update\fP(1) |
| .RS 4 |
| Update dependencies as recorded in the local lock file. |
| .RE |
| .sp |
| \fBcargo\-vendor\fP(1) |
| .RS 4 |
| Vendor all dependencies locally. |
| .RE |
| .sp |
| \fBcargo\-verify\-project\fP(1) |
| .RS 4 |
| Check correctness of crate manifest. |
| .RE |
| .SS "Package Commands" |
| .sp |
| \fBcargo\-init\fP(1) |
| .RS 4 |
| Create a new Cargo package in an existing directory. |
| .RE |
| .sp |
| \fBcargo\-install\fP(1) |
| .RS 4 |
| Build and install a Rust binary. |
| .RE |
| .sp |
| \fBcargo\-new\fP(1) |
| .RS 4 |
| Create a new Cargo package. |
| .RE |
| .sp |
| \fBcargo\-search\fP(1) |
| .RS 4 |
| Search packages in crates.io. |
| .RE |
| .sp |
| \fBcargo\-uninstall\fP(1) |
| .RS 4 |
| Remove a Rust binary. |
| .RE |
| .SS "Publishing Commands" |
| .sp |
| \fBcargo\-login\fP(1) |
| .RS 4 |
| Save an API token from the registry locally. |
| .RE |
| .sp |
| \fBcargo\-owner\fP(1) |
| .RS 4 |
| Manage the owners of a crate on the registry. |
| .RE |
| .sp |
| \fBcargo\-package\fP(1) |
| .RS 4 |
| Assemble the local package into a distributable tarball. |
| .RE |
| .sp |
| \fBcargo\-publish\fP(1) |
| .RS 4 |
| Upload a package to the registry. |
| .RE |
| .sp |
| \fBcargo\-yank\fP(1) |
| .RS 4 |
| Remove a pushed crate from the index. |
| .RE |
| .SS "General Commands" |
| .sp |
| \fBcargo\-help\fP(1) |
| .RS 4 |
| Display help information about Cargo. |
| .RE |
| .sp |
| \fBcargo\-version\fP(1) |
| .RS 4 |
| Show version information. |
| .RE |
| .SH "OPTIONS" |
| .SS "Special Options" |
| .sp |
| \fB\-V\fP, \fB\-\-version\fP |
| .RS 4 |
| Print version info and exit. If used with \fB\-\-verbose\fP, prints extra |
| information. |
| .RE |
| .sp |
| \fB\-\-list\fP |
| .RS 4 |
| List all installed Cargo subcommands. If used with \fB\-\-verbose\fP, prints |
| extra information. |
| .RE |
| .sp |
| \fB\-\-explain \fICODE\fP\fP |
| .RS 4 |
| Run \fBrustc \-\-explain CODE\fP which will print out a detailed explanation of |
| an error message (for example, \fBE0004\fP). |
| .RE |
| .SS "Display Options" |
| .sp |
| \fB\-v\fP, \fB\-\-verbose\fP |
| .RS 4 |
| Use verbose output. May be specified twice for "very verbose" output which |
| includes extra output such as dependency warnings and build script output. |
| May also be specified with the \fBterm.verbose\fP |
| .URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." |
| .RE |
| .sp |
| \fB\-q\fP, \fB\-\-quiet\fP |
| .RS 4 |
| No output printed to stdout. |
| .RE |
| .sp |
| \fB\-\-color\fP \fIWHEN\fP |
| .RS 4 |
| Control when colored output is used. Valid values: |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| . sp -1 |
| . IP \(bu 2.3 |
| .\} |
| \fBauto\fP (default): Automatically detect if color support is available on the |
| terminal. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| . sp -1 |
| . IP \(bu 2.3 |
| .\} |
| \fBalways\fP: Always display colors. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| . sp -1 |
| . IP \(bu 2.3 |
| .\} |
| \fBnever\fP: Never display colors. |
| .RE |
| .sp |
| May also be specified with the \fBterm.color\fP |
| .URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." |
| .RE |
| .SS "Manifest Options" |
| .sp |
| \fB\-\-frozen\fP, \fB\-\-locked\fP |
| .RS 4 |
| Either of these flags requires that the \fBCargo.lock\fP file is |
| up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will |
| exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from |
| attempting to access the network to determine if it is out\-of\-date. |
| .sp |
| These may be used in environments where you want to assert that the |
| \fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network |
| access. |
| .RE |
| .sp |
| \fB\-\-offline\fP |
| .RS 4 |
| Prevents Cargo from accessing the network for any reason. Without this |
| flag, Cargo will stop with an error if it needs to access the network and |
| the network is not available. With this flag, Cargo will attempt to |
| proceed without the network if possible. |
| .sp |
| Beware that this may result in different dependency resolution than online |
| mode. Cargo will restrict itself to crates that are downloaded locally, even |
| if there might be a newer version as indicated in the local copy of the index. |
| See the \fBcargo\-fetch\fP(1) command to download dependencies before going |
| offline. |
| .sp |
| May also be specified with the \fBnet.offline\fP \c |
| .URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." |
| .RE |
| .SS "Common Options" |
| .sp |
| \fB\-h\fP, \fB\-\-help\fP |
| .RS 4 |
| Prints help information. |
| .RE |
| .sp |
| \fB\-Z\fP \fIFLAG\fP... |
| .RS 4 |
| Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for |
| details. |
| .RE |
| .SH "ENVIRONMENT" |
| .sp |
| See \c |
| .URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " |
| for |
| details on environment variables that Cargo reads. |
| .SH "EXIT STATUS" |
| .sp |
| 0 |
| .RS 4 |
| Cargo succeeded. |
| .RE |
| .sp |
| 101 |
| .RS 4 |
| Cargo failed to complete. |
| .RE |
| .SH "FILES" |
| .sp |
| \fB~/.cargo/\fP |
| .RS 4 |
| Default location for Cargo\(cqs "home" directory where it stores various |
| files. The location can be changed with the \fBCARGO_HOME\fP environment |
| variable. |
| .RE |
| .sp |
| \fB$CARGO_HOME/bin/\fP |
| .RS 4 |
| Binaries installed by \fBcargo\-install\fP(1) will be located here. If using |
| rustup, executables distributed with Rust are also located here. |
| .RE |
| .sp |
| \fB$CARGO_HOME/config\fP |
| .RS 4 |
| The global configuration file. See \c |
| .URL "https://doc.rust\-lang.org/cargo/reference/config.html" "the reference" |
| for more information about configuration files. |
| .RE |
| .sp |
| \fB.cargo/config\fP |
| .RS 4 |
| Cargo automatically searches for a file named \fB.cargo/config\fP in the |
| current directory, and all parent directories. These configuration files |
| will be merged with the global configuration file. |
| .RE |
| .sp |
| \fB$CARGO_HOME/credentials\fP |
| .RS 4 |
| Private authentication information for logging in to a registry. |
| .RE |
| .sp |
| \fB$CARGO_HOME/registry/\fP |
| .RS 4 |
| This directory contains cached downloads of the registry index and any |
| downloaded dependencies. |
| .RE |
| .sp |
| \fB$CARGO_HOME/git/\fP |
| .RS 4 |
| This directory contains cached downloads of git dependencies. |
| .RE |
| .sp |
| Please note that the internal structure of the \fB$CARGO_HOME\fP directory is not |
| stable yet and may be subject to change. |
| .SH "EXAMPLES" |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 1.\h'+01'\c |
| .\} |
| .el \{\ |
| . sp -1 |
| . IP " 1." 4.2 |
| .\} |
| Build a local package and all of its dependencies: |
| .sp |
| .if n .RS 4 |
| .nf |
| cargo build |
| .fi |
| .if n .RE |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 2.\h'+01'\c |
| .\} |
| .el \{\ |
| . sp -1 |
| . IP " 2." 4.2 |
| .\} |
| Build a package with optimizations: |
| .sp |
| .if n .RS 4 |
| .nf |
| cargo build \-\-release |
| .fi |
| .if n .RE |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 3.\h'+01'\c |
| .\} |
| .el \{\ |
| . sp -1 |
| . IP " 3." 4.2 |
| .\} |
| Run tests for a cross\-compiled target: |
| .sp |
| .if n .RS 4 |
| .nf |
| cargo test \-\-target i686\-unknown\-linux\-gnu |
| .fi |
| .if n .RE |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 4.\h'+01'\c |
| .\} |
| .el \{\ |
| . sp -1 |
| . IP " 4." 4.2 |
| .\} |
| Create a new package that builds an executable: |
| .sp |
| .if n .RS 4 |
| .nf |
| cargo new foobar |
| .fi |
| .if n .RE |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 5.\h'+01'\c |
| .\} |
| .el \{\ |
| . sp -1 |
| . IP " 5." 4.2 |
| .\} |
| Create a package in the current directory: |
| .sp |
| .if n .RS 4 |
| .nf |
| mkdir foo && cd foo |
| cargo init . |
| .fi |
| .if n .RE |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 6.\h'+01'\c |
| .\} |
| .el \{\ |
| . sp -1 |
| . IP " 6." 4.2 |
| .\} |
| Learn about a command\(cqs options and usage: |
| .sp |
| .if n .RS 4 |
| .nf |
| cargo help clean |
| .fi |
| .if n .RE |
| .RE |
| .SH "BUGS" |
| .sp |
| See \c |
| .URL "https://github.com/rust\-lang/cargo/issues" "" " " |
| for issues. |
| .SH "SEE ALSO" |
| .sp |
| \fBrustc\fP(1), \fBrustdoc\fP(1) |