fork/cargo

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

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

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