fork/cargo
git clone https://git.julia.blue/fork/cargo
0473ee8b8
0.91.0
1CARGO-INSTALL(1) 2 3NAME 4 cargo-install — Build and install a Rust binary 5 6SYNOPSIS 7 cargo install [options] crate[@version]… 8 cargo install [options] --path path 9 cargo install [options] --git url [crate…] 10 cargo install [options] --list 11 12DESCRIPTION 13 This command manages Cargo’s local set of installed binary crates. 14 Only packages which have executable [[bin]] or [[example]] targets can 15 be installed, and all executables are installed into the installation 16 root’s bin folder. By default only binaries, not examples, are 17 installed. 18 19 The installation root is determined, in order of precedence: 20 21 o --root option 22 23 o CARGO_INSTALL_ROOT environment variable 24 25 o install.root Cargo config value 26 <https://doc.rust-lang.org/cargo/reference/config.html> 27 28 o CARGO_HOME environment variable 29 30 o $HOME/.cargo 31 32 There are multiple sources from which a crate can be installed. The 33 default source location is crates.io but the --git, --path, and 34 --registry flags can change this source. If the source contains more 35 than one package (such as crates.io or a git repository with multiple 36 crates) the crate argument is required to indicate which crate should be 37 installed. 38 39 Crates from crates.io can optionally specify the version they wish to 40 install via the --version flags, and similarly packages from git 41 repositories can optionally specify the branch, tag, or revision that 42 should be installed. If a crate has multiple binaries, the --bin 43 argument can selectively install only one of them, and if you’d rather 44 install examples the --example argument can be used as well. 45 46 If the package is already installed, Cargo will reinstall it if the 47 installed version does not appear to be up-to-date. If any of the 48 following values change, then Cargo will reinstall the package: 49 50 o The package version and source. 51 52 o The set of binary names installed. 53 54 o The chosen features. 55 56 o The profile (--profile). 57 58 o The target (--target). 59 60 Installing with --path will always build and install, unless there are 61 conflicting binaries from another package. The --force flag may be used 62 to force Cargo to always reinstall the package. 63 64 If the source is crates.io or --git then by default the crate will be 65 built in a temporary target directory. To avoid this, the target 66 directory can be specified by setting the CARGO_TARGET_DIR environment 67 variable to a relative path. In particular, this can be useful for 68 caching build artifacts on continuous integration systems. 69 70 Dealing with the Lockfile 71 By default, the Cargo.lock file that is included with the package will 72 be ignored. This means that Cargo will recompute which versions of 73 dependencies to use, possibly using newer versions that have been 74 released since the package was published. The --locked flag can be used 75 to force Cargo to use the packaged Cargo.lock file if it is available. 76 This may be useful for ensuring reproducible builds, to use the exact 77 same set of dependencies that were available when the package was 78 published. It may also be useful if a newer version of a dependency is 79 published that no longer builds on your system, or has other problems. 80 The downside to using --locked is that you will not receive any fixes or 81 updates to any dependency. Note that Cargo did not start publishing 82 Cargo.lock files until version 1.37, which means packages published with 83 prior versions will not have a Cargo.lock file available. 84 85 Configuration Discovery 86 This command operates on system or user level, not project level. This 87 means that the local configuration discovery 88 <https://doc.rust-lang.org/cargo/reference/config.html#hierarchical-structure> 89 is ignored. Instead, the configuration discovery begins at 90 $CARGO_HOME/config.toml. If the package is installed with --path $PATH, 91 the local configuration will be used, beginning discovery at 92 $PATH/.cargo/config.toml. 93 94OPTIONS 95 Install Options 96 --vers version, --version version 97 Specify a version to install. This may be a version requirement 98 <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html>, 99 like ~1.2, to have Cargo select the newest version from the given 100 requirement. If the version does not have a requirement operator 101 (such as ^ or ~), then it must be in the form MAJOR.MINOR.PATCH, and 102 will install exactly that version; it is not treated as a caret 103 requirement like Cargo dependencies are. 104 105 --git url 106 Git URL to install the specified crate from. 107 108 --branch branch 109 Branch to use when installing from git. 110 111 --tag tag 112 Tag to use when installing from git. 113 114 --rev sha 115 Specific commit to use when installing from git. 116 117 --path path 118 Filesystem path to local crate to install from. 119 120 --list 121 List all installed packages and their versions. 122 123 -n, --dry-run 124 (unstable) Perform all checks without installing. 125 126 -f, --force 127 Force overwriting existing crates or binaries. This can be used if a 128 package has installed a binary with the same name as another 129 package. This is also useful if something has changed on the system 130 that you want to rebuild with, such as a newer version of rustc. 131 132 --no-track 133 By default, Cargo keeps track of the installed packages with a 134 metadata file stored in the installation root directory. This flag 135 tells Cargo not to use or create that file. With this flag, Cargo 136 will refuse to overwrite any existing files unless the --force flag 137 is used. This also disables Cargo’s ability to protect against 138 multiple concurrent invocations of Cargo installing at the same 139 time. 140 141 --bin name… 142 Install only the specified binary. 143 144 --bins 145 Install all binaries. This is the default behavior. 146 147 --example name… 148 Install only the specified example. 149 150 --examples 151 Install all examples. 152 153 --root dir 154 Directory to install packages into. 155 156 --registry registry 157 Name of the registry to use. Registry names are defined in Cargo 158 config files 159 <https://doc.rust-lang.org/cargo/reference/config.html>. If not 160 specified, the default registry is used, which is defined by the 161 registry.default config key which defaults to crates-io. 162 163 --index index 164 The URL of the registry index to use. 165 166 Feature Selection 167 The feature flags allow you to control which features are enabled. When 168 no feature options are given, the default feature is activated for every 169 selected package. 170 171 See the features documentation 172 <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> 173 for more details. 174 175 -F features, --features features 176 Space or comma separated list of features to activate. Features of 177 workspace members may be enabled with package-name/feature-name 178 syntax. This flag may be specified multiple times, which enables all 179 specified features. 180 181 --all-features 182 Activate all available features of all selected packages. 183 184 --no-default-features 185 Do not activate the default feature of the selected packages. 186 187 Compilation Options 188 --target triple 189 Install for the given architecture. The default is the host 190 architecture. The general format of the triple is 191 <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for 192 a list of supported targets. 193 194 This may also be specified with the build.target config value 195 <https://doc.rust-lang.org/cargo/reference/config.html>. 196 197 Note that specifying this flag makes Cargo run in a different mode 198 where the target artifacts are placed in a separate directory. See 199 the build cache 200 <https://doc.rust-lang.org/cargo/reference/build-cache.html> 201 documentation for more details. 202 203 --target-dir directory 204 Directory for all generated artifacts and intermediate files. May 205 also be specified with the CARGO_TARGET_DIR environment variable, or 206 the build.target-dir config value 207 <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to 208 a new temporary folder located in the temporary directory of the 209 platform. 210 211 When using --path, by default it will use target directory in the 212 workspace of the local crate unless --target-dir is specified. 213 214 --debug 215 Build with the dev profile instead of the release profile. See also 216 the --profile option for choosing a specific profile by name. 217 218 --profile name 219 Install with the given profile. See the reference 220 <https://doc.rust-lang.org/cargo/reference/profiles.html> for more 221 details on profiles. 222 223 --timings=fmts 224 Output information how long each compilation takes, and track 225 concurrency information over time. Accepts an optional 226 comma-separated list of output formats; --timings without an 227 argument will default to --timings=html. Specifying an output format 228 (rather than the default) is unstable and requires 229 -Zunstable-options. Valid output formats: 230 231 o html (unstable, requires -Zunstable-options): Write a 232 human-readable file cargo-timing.html to the target/cargo-timings 233 directory with a report of the compilation. Also write a report 234 to the same directory with a timestamp in the filename if you 235 want to look at older runs. HTML output is suitable for human 236 consumption only, and does not provide machine-readable timing 237 data. 238 239 o json (unstable, requires -Zunstable-options): Emit 240 machine-readable JSON information about timing information. 241 242 Manifest Options 243 --ignore-rust-version 244 Ignore rust-version specification in packages. 245 246 --locked 247 Asserts that the exact same dependencies and versions are used as 248 when the existing Cargo.lock file was originally generated. Cargo 249 will exit with an error when either of the following scenarios 250 arises: 251 252 o The lock file is missing. 253 254 o Cargo attempted to change the lock file due to a different 255 dependency resolution. 256 257 It may be used in environments where deterministic builds are 258 desired, such as in CI pipelines. 259 260 --offline 261 Prevents Cargo from accessing the network for any reason. Without 262 this flag, Cargo will stop with an error if it needs to access the 263 network and the network is not available. With this flag, Cargo will 264 attempt to proceed without the network if possible. 265 266 Beware that this may result in different dependency resolution than 267 online mode. Cargo will restrict itself to crates that are 268 downloaded locally, even if there might be a newer version as 269 indicated in the local copy of the index. See the cargo-fetch(1) 270 command to download dependencies before going offline. 271 272 May also be specified with the net.offline config value 273 <https://doc.rust-lang.org/cargo/reference/config.html>. 274 275 --frozen 276 Equivalent to specifying both --locked and --offline. 277 278 Miscellaneous Options 279 -j N, --jobs N 280 Number of parallel jobs to run. May also be specified with the 281 build.jobs config value 282 <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to 283 the number of logical CPUs. If negative, it sets the maximum number 284 of parallel jobs to the number of logical CPUs plus provided value. 285 If a string default is provided, it sets the value back to defaults. 286 Should not be 0. 287 288 --keep-going 289 Build as many crates in the dependency graph as possible, rather 290 than aborting the build on the first one that fails to build. 291 292 For example if the current package depends on dependencies fails and 293 works, one of which fails to build, cargo install -j1 may or may not 294 build the one that succeeds (depending on which one of the two 295 builds Cargo picked to run first), whereas cargo install -j1 296 --keep-going would definitely run both builds, even if the one run 297 first fails. 298 299 Display Options 300 -v, --verbose 301 Use verbose output. May be specified twice for “very verbose” 302 output which includes extra output such as dependency warnings and 303 build script output. May also be specified with the term.verbose 304 config value 305 <https://doc.rust-lang.org/cargo/reference/config.html>. 306 307 -q, --quiet 308 Do not print cargo log messages. May also be specified with the 309 term.quiet config value 310 <https://doc.rust-lang.org/cargo/reference/config.html>. 311 312 --color when 313 Control when colored output is used. Valid values: 314 315 o auto (default): Automatically detect if color support is 316 available on the terminal. 317 318 o always: Always display colors. 319 320 o never: Never display colors. 321 322 May also be specified with the term.color config value 323 <https://doc.rust-lang.org/cargo/reference/config.html>. 324 325 --message-format fmt 326 The output format for diagnostic messages. Can be specified multiple 327 times and consists of comma-separated values. Valid values: 328 329 o human (default): Display in a human-readable text format. 330 Conflicts with short and json. 331 332 o short: Emit shorter, human-readable text messages. Conflicts with 333 human and json. 334 335 o json: Emit JSON messages to stdout. See the reference 336 <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages> 337 for more details. Conflicts with human and short. 338 339 o json-diagnostic-short: Ensure the rendered field of JSON messages 340 contains the “short” rendering from rustc. Cannot be used 341 with human or short. 342 343 o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON 344 messages contains embedded ANSI color codes for respecting 345 rustc’s default color scheme. Cannot be used with human or 346 short. 347 348 o json-render-diagnostics: Instruct Cargo to not include rustc 349 diagnostics in JSON messages printed, but instead Cargo itself 350 should render the JSON diagnostics coming from rustc. Cargo’s 351 own JSON diagnostics and others coming from rustc are still 352 emitted. Cannot be used with human or short. 353 354 Common Options 355 +toolchain 356 If Cargo has been installed with rustup, and the first argument to 357 cargo begins with +, it will be interpreted as a rustup toolchain 358 name (such as +stable or +nightly). See the rustup documentation 359 <https://rust-lang.github.io/rustup/overrides.html> for more 360 information about how toolchain overrides work. 361 362 --config KEY=VALUE or PATH 363 Overrides a Cargo configuration value. The argument should be in 364 TOML syntax of KEY=VALUE, or provided as a path to an extra 365 configuration file. This flag may be specified multiple times. See 366 the command-line overrides section 367 <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> 368 for more information. 369 370 -C PATH 371 Changes the current working directory before executing any specified 372 operations. This affects things like where cargo looks by default 373 for the project manifest (Cargo.toml), as well as the directories 374 searched for discovering .cargo/config.toml, for example. This 375 option must appear before the command name, for example cargo -C 376 path/to/my-project build. 377 378 This option is only available on the nightly channel 379 <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and 380 requires the -Z unstable-options flag to enable (see #10098 381 <https://github.com/rust-lang/cargo/issues/10098>). 382 383 -h, --help 384 Prints help information. 385 386 -Z flag 387 Unstable (nightly-only) flags to Cargo. Run cargo -Z help for 388 details. 389 390ENVIRONMENT 391 See the reference 392 <https://doc.rust-lang.org/cargo/reference/environment-variables.html> 393 for details on environment variables that Cargo reads. 394 395EXIT STATUS 396 o 0: Cargo succeeded. 397 398 o 101: Cargo failed to complete. 399 400EXAMPLES 401 1. Install or upgrade a package from crates.io: 402 403 cargo install ripgrep 404 405 2. Install or reinstall the package in the current directory: 406 407 cargo install --path . 408 409 3. View the list of installed packages: 410 411 cargo install --list 412 413SEE ALSO 414 cargo(1), cargo-uninstall(1), cargo-search(1), cargo-publish(1) 415