fork/cargo
git clone https://git.julia.blue/fork/cargo
f2932725b
master
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 specified target architecture. The default is the 190 host architecture. The general format of the triple is 191 <arch><sub>-<vendor>-<sys>-<abi>. 192 193 Possible values: 194 195 o Any supported target in rustc --print target-list. 196 197 o "host-tuple", which will internally be substituted by the 198 host’s target. This can be particularly useful if you’re 199 cross-compiling some crates, and don’t want to specify your 200 host’s machine as a target (for instance, an xtask in a shared 201 project that may be worked on by many hosts). 202 203 o A path to a custom target specification. See Custom Target Lookup 204 Path 205 <https://doc.rust-lang.org/rustc/targets/custom.html#custom-target-lookup-path> 206 for more information. 207 208 This may also be specified with the build.target config value 209 <https://doc.rust-lang.org/cargo/reference/config.html>. 210 211 Note that specifying this flag makes Cargo run in a different mode 212 where the target artifacts are placed in a separate directory. See 213 the build cache 214 <https://doc.rust-lang.org/cargo/reference/build-cache.html> 215 documentation for more details. 216 217 --target-dir directory 218 Directory for all generated artifacts and intermediate files. May 219 also be specified with the CARGO_TARGET_DIR environment variable, or 220 the build.target-dir config value 221 <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to 222 a new temporary folder located in the temporary directory of the 223 platform. 224 225 When using --path, by default it will use target directory in the 226 workspace of the local crate unless --target-dir is specified. 227 228 --debug 229 Build with the dev profile instead of the release profile. See also 230 the --profile option for choosing a specific profile by name. 231 232 --profile name 233 Install with the given profile. See the reference 234 <https://doc.rust-lang.org/cargo/reference/profiles.html> for more 235 details on profiles. 236 237 --timings=fmts 238 Output information how long each compilation takes, and track 239 concurrency information over time. Accepts an optional 240 comma-separated list of output formats; --timings without an 241 argument will default to --timings=html. Specifying an output format 242 (rather than the default) is unstable and requires 243 -Zunstable-options. Valid output formats: 244 245 o html (unstable, requires -Zunstable-options): Write a 246 human-readable file cargo-timing.html to the target/cargo-timings 247 directory with a report of the compilation. Also write a report 248 to the same directory with a timestamp in the filename if you 249 want to look at older runs. HTML output is suitable for human 250 consumption only, and does not provide machine-readable timing 251 data. 252 253 o json (unstable, requires -Zunstable-options): Emit 254 machine-readable JSON information about timing information. 255 256 Manifest Options 257 --ignore-rust-version 258 Ignore rust-version specification in packages. 259 260 --locked 261 Asserts that the exact same dependencies and versions are used as 262 when the existing Cargo.lock file was originally generated. Cargo 263 will exit with an error when either of the following scenarios 264 arises: 265 266 o The lock file is missing. 267 268 o Cargo attempted to change the lock file due to a different 269 dependency resolution. 270 271 It may be used in environments where deterministic builds are 272 desired, such as in CI pipelines. 273 274 --offline 275 Prevents Cargo from accessing the network for any reason. Without 276 this flag, Cargo will stop with an error if it needs to access the 277 network and the network is not available. With this flag, Cargo will 278 attempt to proceed without the network if possible. 279 280 Beware that this may result in different dependency resolution than 281 online mode. Cargo will restrict itself to crates that are 282 downloaded locally, even if there might be a newer version as 283 indicated in the local copy of the index. See the cargo-fetch(1) 284 command to download dependencies before going offline. 285 286 May also be specified with the net.offline config value 287 <https://doc.rust-lang.org/cargo/reference/config.html>. 288 289 --frozen 290 Equivalent to specifying both --locked and --offline. 291 292 Miscellaneous Options 293 -j N, --jobs N 294 Number of parallel jobs to run. May also be specified with the 295 build.jobs config value 296 <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to 297 the number of logical CPUs. If negative, it sets the maximum number 298 of parallel jobs to the number of logical CPUs plus provided value. 299 If a string default is provided, it sets the value back to defaults. 300 Should not be 0. 301 302 --keep-going 303 Build as many crates in the dependency graph as possible, rather 304 than aborting the build on the first one that fails to build. 305 306 For example if the current package depends on dependencies fails and 307 works, one of which fails to build, cargo install -j1 may or may not 308 build the one that succeeds (depending on which one of the two 309 builds Cargo picked to run first), whereas cargo install -j1 310 --keep-going would definitely run both builds, even if the one run 311 first fails. 312 313 Display Options 314 -v, --verbose 315 Use verbose output. May be specified twice for “very verbose” 316 output which includes extra output such as dependency warnings and 317 build script output. May also be specified with the term.verbose 318 config value 319 <https://doc.rust-lang.org/cargo/reference/config.html>. 320 321 -q, --quiet 322 Do not print cargo log messages. May also be specified with the 323 term.quiet config value 324 <https://doc.rust-lang.org/cargo/reference/config.html>. 325 326 --color when 327 Control when colored output is used. Valid values: 328 329 o auto (default): Automatically detect if color support is 330 available on the terminal. 331 332 o always: Always display colors. 333 334 o never: Never display colors. 335 336 May also be specified with the term.color config value 337 <https://doc.rust-lang.org/cargo/reference/config.html>. 338 339 --message-format fmt 340 The output format for diagnostic messages. Can be specified multiple 341 times and consists of comma-separated values. Valid values: 342 343 o human (default): Display in a human-readable text format. 344 Conflicts with short and json. 345 346 o short: Emit shorter, human-readable text messages. Conflicts with 347 human and json. 348 349 o json: Emit JSON messages to stdout. See the reference 350 <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages> 351 for more details. Conflicts with human and short. 352 353 o json-diagnostic-short: Ensure the rendered field of JSON messages 354 contains the “short” rendering from rustc. Cannot be used 355 with human or short. 356 357 o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON 358 messages contains embedded ANSI color codes for respecting 359 rustc’s default color scheme. Cannot be used with human or 360 short. 361 362 o json-render-diagnostics: Instruct Cargo to not include rustc 363 diagnostics in JSON messages printed, but instead Cargo itself 364 should render the JSON diagnostics coming from rustc. Cargo’s 365 own JSON diagnostics and others coming from rustc are still 366 emitted. Cannot be used with human or short. 367 368 Common Options 369 +toolchain 370 If Cargo has been installed with rustup, and the first argument to 371 cargo begins with +, it will be interpreted as a rustup toolchain 372 name (such as +stable or +nightly). See the rustup documentation 373 <https://rust-lang.github.io/rustup/overrides.html> for more 374 information about how toolchain overrides work. 375 376 --config KEY=VALUE or PATH 377 Overrides a Cargo configuration value. The argument should be in 378 TOML syntax of KEY=VALUE, or provided as a path to an extra 379 configuration file. This flag may be specified multiple times. See 380 the command-line overrides section 381 <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> 382 for more information. 383 384 -C PATH 385 Changes the current working directory before executing any specified 386 operations. This affects things like where cargo looks by default 387 for the project manifest (Cargo.toml), as well as the directories 388 searched for discovering .cargo/config.toml, for example. This 389 option must appear before the command name, for example cargo -C 390 path/to/my-project build. 391 392 This option is only available on the nightly channel 393 <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and 394 requires the -Z unstable-options flag to enable (see #10098 395 <https://github.com/rust-lang/cargo/issues/10098>). 396 397 -h, --help 398 Prints help information. 399 400 -Z flag 401 Unstable (nightly-only) flags to Cargo. Run cargo -Z help for 402 details. 403 404ENVIRONMENT 405 See the reference 406 <https://doc.rust-lang.org/cargo/reference/environment-variables.html> 407 for details on environment variables that Cargo reads. 408 409EXIT STATUS 410 o 0: Cargo succeeded. 411 412 o 101: Cargo failed to complete. 413 414EXAMPLES 415 1. Install or upgrade a package from crates.io: 416 417 cargo install ripgrep 418 419 2. Install or reinstall the package in the current directory: 420 421 cargo install --path . 422 423 3. View the list of installed packages: 424 425 cargo install --list 426 427SEE ALSO 428 cargo(1), cargo-uninstall(1), cargo-search(1), cargo-publish(1) 429