fork/cargo

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

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

master
20.4 KiB474 linesraw
1CARGO-FIX(1)
2
3NAME
4       cargo-fix — Automatically fix lint warnings reported by rustc
5
6SYNOPSIS
7       cargo fix [options]
8
9DESCRIPTION
10       This Cargo subcommand will automatically take rustc’s suggestions from
11       diagnostics like warnings and apply them to your source code. This is
12       intended to help automate tasks that rustc itself already knows how to
13       tell you to fix!
14
15       Executing cargo fix will under the hood execute cargo-check(1). Any
16       warnings applicable to your crate will be automatically fixed (if
17       possible) and all remaining warnings will be displayed when the check
18       process is finished. For example if you’d like to apply all fixes to
19       the current package, you can run:
20
21           cargo fix
22
23       which behaves the same as cargo check --all-targets.
24
25       cargo fix is only capable of fixing code that is normally compiled with
26       cargo check. If code is conditionally enabled with optional features,
27       you will need to enable those features for that code to be analyzed:
28
29           cargo fix --features foo
30
31       Similarly, other cfg expressions like platform-specific code will need
32       to pass --target to fix code for the given target.
33
34           cargo fix --target x86_64-pc-windows-gnu
35
36       If you encounter any problems with cargo fix or otherwise have any
37       questions or feature requests please don’t hesitate to file an issue
38       at <https://github.com/rust-lang/cargo>.
39
40   Edition migration
41       The cargo fix subcommand can also be used to migrate a package from one
42       edition
43       <https://doc.rust-lang.org/edition-guide/editions/transitioning-an-existing-project-to-a-new-edition.html>
44       to the next. The general procedure is:
45
46       1. Run cargo fix --edition. Consider also using the --all-features flag
47          if your project has multiple features. You may also want to run cargo
48          fix --edition multiple times with different --target flags if your
49          project has platform-specific code gated by cfg attributes.
50
51       2. Modify Cargo.toml to set the edition field
52          <https://doc.rust-lang.org/cargo/reference/manifest.html#the-edition-field>
53          to the new edition.
54
55       3. Run your project tests to verify that everything still works. If new
56          warnings are issued, you may want to consider running cargo fix again
57          (without the --edition flag) to apply any suggestions given by the
58          compiler.
59
60       And hopefully that’s it! Just keep in mind of the caveats mentioned
61       above that cargo fix cannot update code for inactive features or cfg
62       expressions. Also, in some rare cases the compiler is unable to
63       automatically migrate all code to the new edition, and this may require
64       manual changes after building with the new edition.
65
66OPTIONS
67   Fix options
68       --broken-code
69           Fix code even if it already has compiler errors. This is useful if
70           cargo fix fails to apply the changes. It will apply the changes and
71           leave the broken code in the working directory for you to inspect
72           and manually fix.
73
74       --edition
75           Apply changes that will update the code to the next edition. This
76           will not update the edition in the Cargo.toml manifest, which must
77           be updated manually after cargo fix --edition has finished.
78
79       --edition-idioms
80           Apply suggestions that will update code to the preferred style for
81           the current edition.
82
83       --allow-no-vcs
84           Fix code even if a VCS was not detected.
85
86       --allow-dirty
87           Fix code even if the working directory has changes (including staged
88           changes).
89
90       --allow-staged
91           Fix code even if the working directory has staged changes.
92
93   Package Selection
94       By default, when no package selection options are given, the packages
95       selected depend on the selected manifest file (based on the current
96       working directory if --manifest-path is not given). If the manifest is
97       the root of a workspace then the workspaces default members are
98       selected, otherwise only the package defined by the manifest will be
99       selected.
100
101       The default members of a workspace can be set explicitly with the
102       workspace.default-members key in the root manifest. If this is not set,
103       a virtual workspace will include all workspace members (equivalent to
104       passing --workspace), and a non-virtual workspace will include only the
105       root crate itself.
106
107       -p spec…, --package spec…
108           Fix only the specified packages. See cargo-pkgid(1) for the SPEC
109           format. This flag may be specified multiple times and supports
110           common Unix glob patterns like *, ? and []. However, to avoid your
111           shell accidentally expanding glob patterns before Cargo handles
112           them, you must use single quotes or double quotes around each
113           pattern.
114
115       --workspace
116           Fix all members in the workspace.
117
118       --all
119           Deprecated alias for --workspace.
120
121       --exclude SPEC…
122           Exclude the specified packages. Must be used in conjunction with the
123           --workspace flag. This flag may be specified multiple times and
124           supports common Unix glob patterns like *, ? and []. However, to
125           avoid your shell accidentally expanding glob patterns before Cargo
126           handles them, you must use single quotes or double quotes around
127           each pattern.
128
129   Target Selection
130       When no target selection options are given, cargo fix will fix all
131       targets (--all-targets implied). Binaries are skipped if they have
132       required-features that are missing.
133
134       Passing target selection flags will fix only the specified targets.
135
136       Note that --bin, --example, --test and --bench flags also support common
137       Unix glob patterns like *, ? and []. However, to avoid your shell
138       accidentally expanding glob patterns before Cargo handles them, you must
139       use single quotes or double quotes around each glob pattern.
140
141       --lib
142           Fix the package’s library.
143
144       --bin name…
145           Fix the specified binary. This flag may be specified multiple times
146           and supports common Unix glob patterns.
147
148       --bins
149           Fix all binary targets.
150
151       --example name…
152           Fix the specified example. This flag may be specified multiple times
153           and supports common Unix glob patterns.
154
155       --examples
156           Fix all example targets.
157
158       --test name…
159           Fix the specified integration test. This flag may be specified
160           multiple times and supports common Unix glob patterns.
161
162       --tests
163           Fix all targets that have the test = true manifest flag set. By
164           default this includes the library and binaries built as unittests,
165           and integration tests. Be aware that this will also build any
166           required dependencies, so the lib target may be built twice (once as
167           a unittest, and once as a dependency for binaries, integration
168           tests, etc.). Targets may be enabled or disabled by setting the test
169           flag in the manifest settings for the target.
170
171       --bench name…
172           Fix the specified benchmark. This flag may be specified multiple
173           times and supports common Unix glob patterns.
174
175       --benches
176           Fix all targets that have the bench = true manifest flag set. By
177           default this includes the library and binaries built as benchmarks,
178           and bench targets. Be aware that this will also build any required
179           dependencies, so the lib target may be built twice (once as a
180           benchmark, and once as a dependency for binaries, benchmarks, etc.).
181           Targets may be enabled or disabled by setting the bench flag in the
182           manifest settings for the target.
183
184       --all-targets
185           Fix all targets. This is equivalent to specifying --lib --bins
186           --tests --benches --examples.
187
188   Feature Selection
189       The feature flags allow you to control which features are enabled. When
190       no feature options are given, the default feature is activated for every
191       selected package.
192
193       See the features documentation
194       <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options>
195       for more details.
196
197       -F features, --features features
198           Space or comma separated list of features to activate. Features of
199           workspace members may be enabled with package-name/feature-name
200           syntax. This flag may be specified multiple times, which enables all
201           specified features.
202
203       --all-features
204           Activate all available features of all selected packages.
205
206       --no-default-features
207           Do not activate the default feature of the selected packages.
208
209   Compilation Options
210       --target triple
211           Fix for the specified target architecture. Flag may be specified
212           multiple times. The default is the host architecture. The general
213           format of the triple is <arch><sub>-<vendor>-<sys>-<abi>.
214
215           Possible values:
216
217           o  Any supported target in rustc --print target-list.
218
219           o  "host-tuple", which will internally be substituted by the
220              host’s target. This can be particularly useful if you’re
221              cross-compiling some crates, and don’t want to specify your
222              host’s machine as a target (for instance, an xtask in a shared
223              project that may be worked on by many hosts).
224
225           o  A path to a custom target specification. See Custom Target Lookup
226              Path
227              <https://doc.rust-lang.org/rustc/targets/custom.html#custom-target-lookup-path>
228              for more information.
229
230           This may also be specified with the build.target config value
231           <https://doc.rust-lang.org/cargo/reference/config.html>.
232
233           Note that specifying this flag makes Cargo run in a different mode
234           where the target artifacts are placed in a separate directory. See
235           the build cache
236           <https://doc.rust-lang.org/cargo/reference/build-cache.html>
237           documentation for more details.
238
239       -r, --release
240           Fix optimized artifacts with the release profile. See also the
241           --profile option for choosing a specific profile by name.
242
243       --profile name
244           Fix with the given profile.
245
246           As a special case, specifying the test profile will also enable
247           checking in test mode which will enable checking tests and enable
248           the test cfg option. See rustc tests
249           <https://doc.rust-lang.org/rustc/tests/index.html> for more detail.
250
251           See the reference
252           <https://doc.rust-lang.org/cargo/reference/profiles.html> for more
253           details on profiles.
254
255       --timings=fmts
256           Output information how long each compilation takes, and track
257           concurrency information over time. Accepts an optional
258           comma-separated list of output formats; --timings without an
259           argument will default to --timings=html. Specifying an output format
260           (rather than the default) is unstable and requires
261           -Zunstable-options. Valid output formats:
262
263           o  html (unstable, requires -Zunstable-options): Write a
264              human-readable file cargo-timing.html to the target/cargo-timings
265              directory with a report of the compilation. Also write a report
266              to the same directory with a timestamp in the filename if you
267              want to look at older runs. HTML output is suitable for human
268              consumption only, and does not provide machine-readable timing
269              data.
270
271           o  json (unstable, requires -Zunstable-options): Emit
272              machine-readable JSON information about timing information.
273
274   Output Options
275       --target-dir directory
276           Directory for all generated artifacts and intermediate files. May
277           also be specified with the CARGO_TARGET_DIR environment variable, or
278           the build.target-dir config value
279           <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
280           target in the root of the workspace.
281
282   Display Options
283       -v, --verbose
284           Use verbose output. May be specified twice for “very verbose”
285           output which includes extra output such as dependency warnings and
286           build script output. May also be specified with the term.verbose
287           config value
288           <https://doc.rust-lang.org/cargo/reference/config.html>.
289
290       -q, --quiet
291           Do not print cargo log messages. May also be specified with the
292           term.quiet config value
293           <https://doc.rust-lang.org/cargo/reference/config.html>.
294
295       --color when
296           Control when colored output is used. Valid values:
297
298           o  auto (default): Automatically detect if color support is
299              available on the terminal.
300
301           o  always: Always display colors.
302
303           o  never: Never display colors.
304
305           May also be specified with the term.color config value
306           <https://doc.rust-lang.org/cargo/reference/config.html>.
307
308       --message-format fmt
309           The output format for diagnostic messages. Can be specified multiple
310           times and consists of comma-separated values. Valid values:
311
312           o  human (default): Display in a human-readable text format.
313              Conflicts with short and json.
314
315           o  short: Emit shorter, human-readable text messages. Conflicts with
316              human and json.
317
318           o  json: Emit JSON messages to stdout. See the reference
319              <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages>
320              for more details. Conflicts with human and short.
321
322           o  json-diagnostic-short: Ensure the rendered field of JSON messages
323              contains the “short” rendering from rustc. Cannot be used
324              with human or short.
325
326           o  json-diagnostic-rendered-ansi: Ensure the rendered field of JSON
327              messages contains embedded ANSI color codes for respecting
328              rustc’s default color scheme. Cannot be used with human or
329              short.
330
331           o  json-render-diagnostics: Instruct Cargo to not include rustc
332              diagnostics in JSON messages printed, but instead Cargo itself
333              should render the JSON diagnostics coming from rustc. Cargo’s
334              own JSON diagnostics and others coming from rustc are still
335              emitted. Cannot be used with human or short.
336
337   Manifest Options
338       --manifest-path path
339           Path to the Cargo.toml file. By default, Cargo searches for the
340           Cargo.toml file in the current directory or any parent directory.
341
342       --ignore-rust-version
343           Ignore rust-version specification in packages.
344
345       --locked
346           Asserts that the exact same dependencies and versions are used as
347           when the existing Cargo.lock file was originally generated. Cargo
348           will exit with an error when either of the following scenarios
349           arises:
350
351           o  The lock file is missing.
352
353           o  Cargo attempted to change the lock file due to a different
354              dependency resolution.
355
356           It may be used in environments where deterministic builds are
357           desired, such as in CI pipelines.
358
359       --offline
360           Prevents Cargo from accessing the network for any reason. Without
361           this flag, Cargo will stop with an error if it needs to access the
362           network and the network is not available. With this flag, Cargo will
363           attempt to proceed without the network if possible.
364
365           Beware that this may result in different dependency resolution than
366           online mode. Cargo will restrict itself to crates that are
367           downloaded locally, even if there might be a newer version as
368           indicated in the local copy of the index. See the cargo-fetch(1)
369           command to download dependencies before going offline.
370
371           May also be specified with the net.offline config value
372           <https://doc.rust-lang.org/cargo/reference/config.html>.
373
374       --frozen
375           Equivalent to specifying both --locked and --offline.
376
377       --lockfile-path PATH
378           Changes the path of the lockfile from the default
379           (<workspace_root>/Cargo.lock) to PATH. PATH must end with Cargo.lock
380           (e.g. --lockfile-path /tmp/temporary-lockfile/Cargo.lock). Note that
381           providing --lockfile-path will ignore existing lockfile at the
382           default path, and instead will either use the lockfile from PATH, or
383           write a new lockfile into the provided PATH if it doesn’t exist.
384           This flag can be used to run most commands in read-only directories,
385           writing lockfile into the provided PATH.
386
387           This option is only available on the nightly channel
388           <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and
389           requires the -Z unstable-options flag to enable (see #14421
390           <https://github.com/rust-lang/cargo/issues/14421>).
391
392   Common Options
393       +toolchain
394           If Cargo has been installed with rustup, and the first argument to
395           cargo begins with +, it will be interpreted as a rustup toolchain
396           name (such as +stable or +nightly). See the rustup documentation
397           <https://rust-lang.github.io/rustup/overrides.html> for more
398           information about how toolchain overrides work.
399
400       --config KEY=VALUE or PATH
401           Overrides a Cargo configuration value. The argument should be in
402           TOML syntax of KEY=VALUE, or provided as a path to an extra
403           configuration file. This flag may be specified multiple times. See
404           the command-line overrides section
405           <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides>
406           for more information.
407
408       -C PATH
409           Changes the current working directory before executing any specified
410           operations. This affects things like where cargo looks by default
411           for the project manifest (Cargo.toml), as well as the directories
412           searched for discovering .cargo/config.toml, for example. This
413           option must appear before the command name, for example cargo -C
414           path/to/my-project build.
415
416           This option is only available on the nightly channel
417           <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and
418           requires the -Z unstable-options flag to enable (see #10098
419           <https://github.com/rust-lang/cargo/issues/10098>).
420
421       -h, --help
422           Prints help information.
423
424       -Z flag
425           Unstable (nightly-only) flags to Cargo. Run cargo -Z help for
426           details.
427
428   Miscellaneous Options
429       -j N, --jobs N
430           Number of parallel jobs to run. May also be specified with the
431           build.jobs config value
432           <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
433           the number of logical CPUs. If negative, it sets the maximum number
434           of parallel jobs to the number of logical CPUs plus provided value.
435           If a string default is provided, it sets the value back to defaults.
436           Should not be 0.
437
438       --keep-going
439           Build as many crates in the dependency graph as possible, rather
440           than aborting the build on the first one that fails to build.
441
442           For example if the current package depends on dependencies fails and
443           works, one of which fails to build, cargo fix -j1 may or may not
444           build the one that succeeds (depending on which one of the two
445           builds Cargo picked to run first), whereas cargo fix -j1
446           --keep-going would definitely run both builds, even if the one run
447           first fails.
448
449ENVIRONMENT
450       See the reference
451       <https://doc.rust-lang.org/cargo/reference/environment-variables.html>
452       for details on environment variables that Cargo reads.
453
454EXIT STATUS
455       o  0: Cargo succeeded.
456
457       o  101: Cargo failed to complete.
458
459EXAMPLES
460       1. Apply compiler suggestions to the local package:
461
462              cargo fix
463
464       2. Update a package to prepare it for the next edition:
465
466              cargo fix --edition
467
468       3. Apply suggested idioms for the current edition:
469
470              cargo fix --edition-idioms
471
472SEE ALSO
473       cargo(1), cargo-check(1)
474