1CARGO-RUSTC(1)              General Commands Manual             CARGO-RUSTC(1)
2
3
4

NAME

6       cargo-rustc — Compile the current package, and pass extra options to
7       the compiler
8

SYNOPSIS

10       cargo rustc [options] [-- args]
11

DESCRIPTION

13       The specified target for the current package (or package specified by
14       -p if provided) will be compiled along with all of its dependencies.
15       The specified args will all be passed to the final compiler invocation,
16       not any of the dependencies. Note that the compiler will still
17       unconditionally receive arguments such as -L, --extern, and
18       --crate-type, and the specified args will simply be added to the
19       compiler invocation.
20
21       See <https://doc.rust-lang.org/rustc/index.html> for documentation on
22       rustc flags.
23
24       This command requires that only one target is being compiled when
25       additional arguments are provided. If more than one target is available
26       for the current package the filters of --lib, --bin, etc, must be used
27       to select which target is compiled.
28
29       To pass flags to all compiler processes spawned by Cargo, use the
30       RUSTFLAGS environment variable
31       <https://doc.rust-lang.org/cargo/reference/environment-variables.html>
32       or the build.rustflags config value
33       <https://doc.rust-lang.org/cargo/reference/config.html>.
34

OPTIONS

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

ENVIRONMENT

370       See the reference
371       <https://doc.rust-lang.org/cargo/reference/environment-variables.html>
372       for details on environment variables that Cargo reads.
373

EXIT STATUS

3750: Cargo succeeded.
376
377101: Cargo failed to complete.
378

EXAMPLES

380        1. Check if your package (not including dependencies) uses unsafe
381           code:
382
383               cargo rustc --lib -- -D unsafe-code
384
385        2. Try an experimental flag on the nightly compiler, such as this
386           which prints the size of every type:
387
388               cargo rustc --lib -- -Z print-type-sizes
389
390        3. Override crate-type field in Cargo.toml with command-line option:
391
392               cargo rustc --lib --crate-type lib,cdylib
393

SEE ALSO

395       cargo(1), cargo-build(1), rustc(1)
396
397
398
399                                                                CARGO-RUSTC(1)
Impressum