fork/cargo

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

Weihang Lofix: use `host-tuple` for host target subsitution (#16003)f2932725b

home-0.5.12
18.1 KiB429 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 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