| '\" t |
| .\" Title: cargo-install |
| .\" Author: [see the "AUTHOR(S)" section] |
| .\" Generator: Asciidoctor 1.5.8 |
| .\" Date: 2019-06-10 |
| .\" Manual: \ \& |
| .\" Source: \ \& |
| .\" Language: English |
| .\" |
| .TH "CARGO\-INSTALL" "1" "2019-06-10" "\ \&" "\ \&" |
| .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\-install \- Build and install a Rust binary |
| .SH "SYNOPSIS" |
| .sp |
| \fBcargo install [\fIOPTIONS\fP] \fICRATE\fP...\fP |
| .br |
| \fBcargo install [\fIOPTIONS\fP] \-\-path \fIPATH\fP\fP |
| .br |
| \fBcargo install [\fIOPTIONS\fP] \-\-git \fIURL\fP [\fICRATE\fP...]\fP |
| .br |
| \fBcargo install [\fIOPTIONS\fP] \-\-list\fP |
| .SH "DESCRIPTION" |
| .sp |
| This command manages Cargo\(cqs local set of installed binary crates. Only |
| packages which have executable \fB[[bin]]\fP or \fB[[example]]\fP targets can be |
| installed, and all executables are installed into the installation root\(cqs |
| \fBbin\fP folder. |
| .sp |
| The installation root is determined, in order of precedence: |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| . sp -1 |
| . IP \(bu 2.3 |
| .\} |
| \fB\-\-root\fP option |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| . sp -1 |
| . IP \(bu 2.3 |
| .\} |
| \fBCARGO_INSTALL_ROOT\fP environment variable |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| . sp -1 |
| . IP \(bu 2.3 |
| .\} |
| \fBinstall.root\fP Cargo \c |
| .URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "" |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| . sp -1 |
| . IP \(bu 2.3 |
| .\} |
| \fBCARGO_HOME\fP environment variable |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| . sp -1 |
| . IP \(bu 2.3 |
| .\} |
| \fB$HOME/.cargo\fP |
| .RE |
| .sp |
| There are multiple sources from which a crate can be installed. The default |
| location is crates.io but the \fB\-\-git\fP, \fB\-\-path\fP, and \fB\-\-registry\fP flags can |
| change this source. If the source contains more than one package (such as |
| crates.io or a git repository with multiple crates) the \fICRATE\fP argument is |
| required to indicate which crate should be installed. |
| .sp |
| Crates from crates.io can optionally specify the version they wish to install |
| via the \fB\-\-version\fP flags, and similarly packages from git repositories can |
| optionally specify the branch, tag, or revision that should be installed. If a |
| crate has multiple binaries, the \fB\-\-bin\fP argument can selectively install only |
| one of them, and if you\(cqd rather install examples the \fB\-\-example\fP argument can |
| be used as well. |
| .sp |
| If the source is crates.io or \fB\-\-git\fP then by default the crate will be built |
| in a temporary target directory. To avoid this, the target directory can be |
| specified by setting the \fBCARGO_TARGET_DIR\fP environment variable to a relative |
| path. In particular, this can be useful for caching build artifacts on |
| continuous integration systems. |
| .sp |
| By default, the \fBCargo.lock\fP file that is included with the package will be |
| ignored. This means that Cargo will recompute which versions of dependencies |
| to use, possibly using newer versions that have been released since the |
| package was published. The \fB\-\-locked\fP flag can be used to force Cargo to use |
| the packaged \fBCargo.lock\fP file if it is available. This may be useful for |
| ensuring reproducible builds, to use the exact same set of dependencies that |
| were available when the package was published. It may also be useful if a |
| newer version of a dependency is published that no longer builds on your |
| system, or has other problems. The downside to using \fB\-\-locked\fP is that you |
| will not receive any fixes or updates to any dependency. Note that Cargo did |
| not start publishing \fBCargo.lock\fP files until version 1.37, which means |
| packages published with prior versions will not have a \fBCargo.lock\fP file |
| available. |
| .SH "OPTIONS" |
| .SS "Install Options" |
| .sp |
| \fB\-\-vers\fP \fIVERSION\fP, \fB\-\-version\fP \fIVERSION\fP |
| .RS 4 |
| Specify a version to install. |
| .RE |
| .sp |
| \fB\-\-git\fP \fIURL\fP |
| .RS 4 |
| Git URL to install the specified crate from. |
| .RE |
| .sp |
| \fB\-\-branch\fP \fIBRANCH\fP |
| .RS 4 |
| Branch to use when installing from git. |
| .RE |
| .sp |
| \fB\-\-tag\fP \fITAG\fP |
| .RS 4 |
| Tag to use when installing from git. |
| .RE |
| .sp |
| \fB\-\-rev\fP \fISHA\fP |
| .RS 4 |
| Specific commit to use when installing from git. |
| .RE |
| .sp |
| \fB\-\-path\fP \fIPATH\fP |
| .RS 4 |
| Filesystem path to local crate to install. |
| .RE |
| .sp |
| \fB\-\-list\fP |
| .RS 4 |
| List all installed packages and their versions. |
| .RE |
| .sp |
| \fB\-f\fP, \fB\-\-force\fP |
| .RS 4 |
| Force overwriting existing crates or binaries. This can be used to |
| reinstall or upgrade a crate. |
| .RE |
| .sp |
| \fB\-\-bin\fP \fINAME\fP... |
| .RS 4 |
| Install only the specified binary. |
| .RE |
| .sp |
| \fB\-\-bins\fP |
| .RS 4 |
| Install all binaries. |
| .RE |
| .sp |
| \fB\-\-example\fP \fINAME\fP... |
| .RS 4 |
| Install only the specified example. |
| .RE |
| .sp |
| \fB\-\-examples\fP |
| .RS 4 |
| Install all examples. |
| .RE |
| .sp |
| \fB\-\-root\fP \fIDIR\fP |
| .RS 4 |
| Directory to install packages into. |
| .RE |
| .sp |
| \fB\-\-registry\fP \fIREGISTRY\fP |
| .RS 4 |
| Name of the registry to use. Registry names are defined in \c |
| .URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "." |
| If not specified, the default registry is used, which is defined by the |
| \fBregistry.default\fP config key which defaults to \fBcrates\-io\fP. |
| .RE |
| .SS "Feature Selection" |
| .sp |
| When no feature options are given, the \fBdefault\fP feature is activated for |
| every selected package. |
| .sp |
| \fB\-\-features\fP \fIFEATURES\fP |
| .RS 4 |
| Space or comma separated list of features to activate. These features only |
| apply to the current directory\(cqs package. Features of direct dependencies |
| may be enabled with \fB<dep\-name>/<feature\-name>\fP syntax. |
| .RE |
| .sp |
| \fB\-\-all\-features\fP |
| .RS 4 |
| Activate all available features of all selected packages. |
| .RE |
| .sp |
| \fB\-\-no\-default\-features\fP |
| .RS 4 |
| Do not activate the \fBdefault\fP feature of the current directory\(cqs |
| package. |
| .RE |
| .SS "Compilation Options" |
| .sp |
| \fB\-\-target\fP \fITRIPLE\fP |
| .RS 4 |
| Install for the given architecture. The default is the host |
| architecture. The general format of the triple is |
| \fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fP. Run \fBrustc \-\-print target\-list\fP for a |
| list of supported targets. |
| .sp |
| This may also be specified with the \fBbuild.target\fP |
| .URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." |
| .RE |
| .sp |
| \fB\-\-debug\fP |
| .RS 4 |
| Build with the \fBdev\fP profile instead the \fBrelease\fP profile. |
| .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 "Miscellaneous Options" |
| .sp |
| \fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP |
| .RS 4 |
| Number of parallel jobs to run. May also be specified with the |
| \fBbuild.jobs\fP \c |
| .URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." |
| Defaults to |
| the number of CPUs. |
| .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 "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 "EXAMPLES" |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 1.\h'+01'\c |
| .\} |
| .el \{\ |
| . sp -1 |
| . IP " 1." 4.2 |
| .\} |
| Install a package from crates.io: |
| .sp |
| .if n .RS 4 |
| .nf |
| cargo install ripgrep |
| .fi |
| .if n .RE |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 2.\h'+01'\c |
| .\} |
| .el \{\ |
| . sp -1 |
| . IP " 2." 4.2 |
| .\} |
| Reinstall or upgrade a package: |
| .sp |
| .if n .RS 4 |
| .nf |
| cargo install ripgrep \-\-force |
| .fi |
| .if n .RE |
| .RE |
| .SH "SEE ALSO" |
| .sp |
| \fBcargo\fP(1), \fBcargo\-uninstall\fP(1), \fBcargo\-search\fP(1), \fBcargo\-publish\fP(1) |