fork/cargo

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

borsAuto merge of #14675 - RalfJung:help, r=weihanglode128bea7

0.88.0
16.8 KiB389 linesraw
1CARGO-CHECK(1)
2
3NAME
4       cargo-check — Check the current package
5
6SYNOPSIS
7       cargo check [options]
8
9DESCRIPTION
10       Check a local package and all of its dependencies for errors. This will
11       essentially compile the packages without performing the final step of
12       code generation, which is faster than running cargo build. The compiler
13       will save metadata files to disk so that future runs will reuse them if
14       the source has not been modified. Some diagnostics and errors are only
15       emitted during code generation, so they inherently won’t be reported
16       with cargo check.
17
18OPTIONS
19   Package Selection
20       By default, when no package selection options are given, the packages
21       selected depend on the selected manifest file (based on the current
22       working directory if --manifest-path is not given). If the manifest is
23       the root of a workspace then the workspaces default members are
24       selected, otherwise only the package defined by the manifest will be
25       selected.
26
27       The default members of a workspace can be set explicitly with the
28       workspace.default-members key in the root manifest. If this is not set,
29       a virtual workspace will include all workspace members (equivalent to
30       passing --workspace), and a non-virtual workspace will include only the
31       root crate itself.
32
33       -p spec…, --package spec…
34           Check only the specified packages. See cargo-pkgid(1) for the SPEC
35           format. This flag may be specified multiple times and supports
36           common Unix glob patterns like *, ? and []. However, to avoid your
37           shell accidentally expanding glob patterns before Cargo handles
38           them, you must use single quotes or double quotes around each
39           pattern.
40
41       --workspace
42           Check all members in the workspace.
43
44       --all
45           Deprecated alias for --workspace.
46
47       --exclude SPEC…
48           Exclude the specified packages. Must be used in conjunction with the
49           --workspace flag. This flag may be specified multiple times and
50           supports common Unix glob patterns like *, ? and []. However, to
51           avoid your shell accidentally expanding glob patterns before Cargo
52           handles them, you must use single quotes or double quotes around
53           each pattern.
54
55   Target Selection
56       When no target selection options are given, cargo check will check all
57       binary and library targets of the selected packages. Binaries are
58       skipped if they have required-features that are missing.
59
60       Passing target selection flags will check only the specified targets.
61
62       Note that --bin, --example, --test and --bench flags also support common
63       Unix glob patterns like *, ? and []. However, to avoid your shell
64       accidentally expanding glob patterns before Cargo handles them, you must
65       use single quotes or double quotes around each glob pattern.
66
67       --lib
68           Check the package’s library.
69
70       --bin name…
71           Check the specified binary. This flag may be specified multiple
72           times and supports common Unix glob patterns.
73
74       --bins
75           Check all binary targets.
76
77       --example name…
78           Check the specified example. This flag may be specified multiple
79           times and supports common Unix glob patterns.
80
81       --examples
82           Check all example targets.
83
84       --test name…
85           Check the specified integration test. This flag may be specified
86           multiple times and supports common Unix glob patterns.
87
88       --tests
89           Check all targets that have the test = true manifest flag set. By
90           default this includes the library and binaries built as unittests,
91           and integration tests. Be aware that this will also build any
92           required dependencies, so the lib target may be built twice (once as
93           a unittest, and once as a dependency for binaries, integration
94           tests, etc.). Targets may be enabled or disabled by setting the test
95           flag in the manifest settings for the target.
96
97       --bench name…
98           Check the specified benchmark. This flag may be specified multiple
99           times and supports common Unix glob patterns.
100
101       --benches
102           Check all targets that have the bench = true manifest flag set. By
103           default this includes the library and binaries built as benchmarks,
104           and bench targets. Be aware that this will also build any required
105           dependencies, so the lib target may be built twice (once as a
106           benchmark, and once as a dependency for binaries, benchmarks, etc.).
107           Targets may be enabled or disabled by setting the bench flag in the
108           manifest settings for the target.
109
110       --all-targets
111           Check all targets. This is equivalent to specifying --lib --bins
112           --tests --benches --examples.
113
114   Feature Selection
115       The feature flags allow you to control which features are enabled. When
116       no feature options are given, the default feature is activated for every
117       selected package.
118
119       See the features documentation
120       <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options>
121       for more details.
122
123       -F features, --features features
124           Space or comma separated list of features to activate. Features of
125           workspace members may be enabled with package-name/feature-name
126           syntax. This flag may be specified multiple times, which enables all
127           specified features.
128
129       --all-features
130           Activate all available features of all selected packages.
131
132       --no-default-features
133           Do not activate the default feature of the selected packages.
134
135   Compilation Options
136       --target triple
137           Check for the given architecture. The default is the host
138           architecture. The general format of the triple is
139           <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for
140           a list of supported targets. This flag may be specified multiple
141           times.
142
143           This may also be specified with the build.target config value
144           <https://doc.rust-lang.org/cargo/reference/config.html>.
145
146           Note that specifying this flag makes Cargo run in a different mode
147           where the target artifacts are placed in a separate directory. See
148           the build cache
149           <https://doc.rust-lang.org/cargo/reference/build-cache.html>
150           documentation for more details.
151
152       -r, --release
153           Check optimized artifacts with the release profile. See also the
154           --profile option for choosing a specific profile by name.
155
156       --profile name
157           Check with the given profile.
158
159           As a special case, specifying the test profile will also enable
160           checking in test mode which will enable checking tests and enable
161           the test cfg option. See rustc tests
162           <https://doc.rust-lang.org/rustc/tests/index.html> for more detail.
163
164           See the reference
165           <https://doc.rust-lang.org/cargo/reference/profiles.html> for more
166           details on profiles.
167
168       --timings=fmts
169           Output information how long each compilation takes, and track
170           concurrency information over time. Accepts an optional
171           comma-separated list of output formats; --timings without an
172           argument will default to --timings=html. Specifying an output format
173           (rather than the default) is unstable and requires
174           -Zunstable-options. Valid output formats:
175
176           o  html (unstable, requires -Zunstable-options): Write a
177              human-readable file cargo-timing.html to the target/cargo-timings
178              directory with a report of the compilation. Also write a report
179              to the same directory with a timestamp in the filename if you
180              want to look at older runs. HTML output is suitable for human
181              consumption only, and does not provide machine-readable timing
182              data.
183
184           o  json (unstable, requires -Zunstable-options): Emit
185              machine-readable JSON information about timing information.
186
187   Output Options
188       --target-dir directory
189           Directory for all generated artifacts and intermediate files. May
190           also be specified with the CARGO_TARGET_DIR environment variable, or
191           the build.target-dir config value
192           <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
193           target in the root of the workspace.
194
195   Display Options
196       -v, --verbose
197           Use verbose output. May be specified twice for “very verbose”
198           output which includes extra output such as dependency warnings and
199           build script output. May also be specified with the term.verbose
200           config value
201           <https://doc.rust-lang.org/cargo/reference/config.html>.
202
203       -q, --quiet
204           Do not print cargo log messages. May also be specified with the
205           term.quiet config value
206           <https://doc.rust-lang.org/cargo/reference/config.html>.
207
208       --color when
209           Control when colored output is used. Valid values:
210
211           o  auto (default): Automatically detect if color support is
212              available on the terminal.
213
214           o  always: Always display colors.
215
216           o  never: Never display colors.
217
218           May also be specified with the term.color config value
219           <https://doc.rust-lang.org/cargo/reference/config.html>.
220
221       --message-format fmt
222           The output format for diagnostic messages. Can be specified multiple
223           times and consists of comma-separated values. Valid values:
224
225           o  human (default): Display in a human-readable text format.
226              Conflicts with short and json.
227
228           o  short: Emit shorter, human-readable text messages. Conflicts with
229              human and json.
230
231           o  json: Emit JSON messages to stdout. See the reference
232              <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages>
233              for more details. Conflicts with human and short.
234
235           o  json-diagnostic-short: Ensure the rendered field of JSON messages
236              contains the “short” rendering from rustc. Cannot be used
237              with human or short.
238
239           o  json-diagnostic-rendered-ansi: Ensure the rendered field of JSON
240              messages contains embedded ANSI color codes for respecting
241              rustc’s default color scheme. Cannot be used with human or
242              short.
243
244           o  json-render-diagnostics: Instruct Cargo to not include rustc
245              diagnostics in JSON messages printed, but instead Cargo itself
246              should render the JSON diagnostics coming from rustc. Cargo’s
247              own JSON diagnostics and others coming from rustc are still
248              emitted. Cannot be used with human or short.
249
250   Manifest Options
251       --manifest-path path
252           Path to the Cargo.toml file. By default, Cargo searches for the
253           Cargo.toml file in the current directory or any parent directory.
254
255       --ignore-rust-version
256           Ignore rust-version specification in packages.
257
258       --locked
259           Asserts that the exact same dependencies and versions are used as
260           when the existing Cargo.lock file was originally generated. Cargo
261           will exit with an error when either of the following scenarios
262           arises:
263
264           o  The lock file is missing.
265
266           o  Cargo attempted to change the lock file due to a different
267              dependency resolution.
268
269           It may be used in environments where deterministic builds are
270           desired, such as in CI pipelines.
271
272       --offline
273           Prevents Cargo from accessing the network for any reason. Without
274           this flag, Cargo will stop with an error if it needs to access the
275           network and the network is not available. With this flag, Cargo will
276           attempt to proceed without the network if possible.
277
278           Beware that this may result in different dependency resolution than
279           online mode. Cargo will restrict itself to crates that are
280           downloaded locally, even if there might be a newer version as
281           indicated in the local copy of the index. See the cargo-fetch(1)
282           command to download dependencies before going offline.
283
284           May also be specified with the net.offline config value
285           <https://doc.rust-lang.org/cargo/reference/config.html>.
286
287       --frozen
288           Equivalent to specifying both --locked and --offline.
289
290       --lockfile-path PATH
291           Changes the path of the lockfile from the default
292           (<workspace_root>/Cargo.lock) to PATH. PATH must end with Cargo.lock
293           (e.g. --lockfile-path /tmp/temporary-lockfile/Cargo.lock). Note that
294           providing --lockfile-path will ignore existing lockfile at the
295           default path, and instead will either use the lockfile from PATH, or
296           write a new lockfile into the provided PATH if it doesn’t exist.
297           This flag can be used to run most commands in read-only directories,
298           writing lockfile into the provided PATH.
299
300           This option is only available on the nightly channel
301           <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and
302           requires the -Z unstable-options flag to enable (see #14421
303           <https://github.com/rust-lang/cargo/issues/14421>).
304
305   Common Options
306       +toolchain
307           If Cargo has been installed with rustup, and the first argument to
308           cargo begins with +, it will be interpreted as a rustup toolchain
309           name (such as +stable or +nightly). See the rustup documentation
310           <https://rust-lang.github.io/rustup/overrides.html> for more
311           information about how toolchain overrides work.
312
313       --config KEY=VALUE or PATH
314           Overrides a Cargo configuration value. The argument should be in
315           TOML syntax of KEY=VALUE, or provided as a path to an extra
316           configuration file. This flag may be specified multiple times. See
317           the command-line overrides section
318           <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides>
319           for more information.
320
321       -C PATH
322           Changes the current working directory before executing any specified
323           operations. This affects things like where cargo looks by default
324           for the project manifest (Cargo.toml), as well as the directories
325           searched for discovering .cargo/config.toml, for example. This
326           option must appear before the command name, for example cargo -C
327           path/to/my-project build.
328
329           This option is only available on the nightly channel
330           <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and
331           requires the -Z unstable-options flag to enable (see #10098
332           <https://github.com/rust-lang/cargo/issues/10098>).
333
334       -h, --help
335           Prints help information.
336
337       -Z flag
338           Unstable (nightly-only) flags to Cargo. Run cargo -Z help for
339           details.
340
341   Miscellaneous Options
342       -j N, --jobs N
343           Number of parallel jobs to run. May also be specified with the
344           build.jobs config value
345           <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
346           the number of logical CPUs. If negative, it sets the maximum number
347           of parallel jobs to the number of logical CPUs plus provided value.
348           If a string default is provided, it sets the value back to defaults.
349           Should not be 0.
350
351       --keep-going
352           Build as many crates in the dependency graph as possible, rather
353           than aborting the build on the first one that fails to build.
354
355           For example if the current package depends on dependencies fails and
356           works, one of which fails to build, cargo check -j1 may or may not
357           build the one that succeeds (depending on which one of the two
358           builds Cargo picked to run first), whereas cargo check -j1
359           --keep-going would definitely run both builds, even if the one run
360           first fails.
361
362       --future-incompat-report
363           Displays a future-incompat report for any future-incompatible
364           warnings produced during execution of this command
365
366           See cargo-report(1)
367
368ENVIRONMENT
369       See the reference
370       <https://doc.rust-lang.org/cargo/reference/environment-variables.html>
371       for details on environment variables that Cargo reads.
372
373EXIT STATUS
374       o  0: Cargo succeeded.
375
376       o  101: Cargo failed to complete.
377
378EXAMPLES
379       1. Check the local package for errors:
380
381              cargo check
382
383       2. Check all targets, including unit tests:
384
385              cargo check --all-targets --profile=test
386
387SEE ALSO
388       cargo(1), cargo-build(1)
389