fork/cargo

git clone https://git.julia.blue/fork/cargo

borsAuto merge of #14620 - epage:guideless, r=weihanglo0473ee8b8

0.90.0
17.5 KiB415 linesraw
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