fork/cargo

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

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

master
18.4 KiB424 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 specified target architecture. Flag may be specified
132           multiple times. The default is the host architecture. The general
133           format of the triple is <arch><sub>-<vendor>-<sys>-<abi>.
134
135           Possible values:
136
137           o  Any supported target in rustc --print target-list.
138
139           o  "host-tuple", which will internally be substituted by the
140              host’s target. This can be particularly useful if you’re
141              cross-compiling some crates, and don’t want to specify your
142              host’s machine as a target (for instance, an xtask in a shared
143              project that may be worked on by many hosts).
144
145           o  A path to a custom target specification. See Custom Target Lookup
146              Path
147              <https://doc.rust-lang.org/rustc/targets/custom.html#custom-target-lookup-path>
148              for more information.
149
150           This may also be specified with the build.target config value
151           <https://doc.rust-lang.org/cargo/reference/config.html>.
152
153           Note that specifying this flag makes Cargo run in a different mode
154           where the target artifacts are placed in a separate directory. See
155           the build cache
156           <https://doc.rust-lang.org/cargo/reference/build-cache.html>
157           documentation for more details.
158
159       -r, --release
160           Build optimized artifacts with the release profile. See also the
161           --profile option for choosing a specific profile by name.
162
163       --profile name
164           Build with the given profile.
165
166           The rustc subcommand will treat the following named profiles with
167           special behaviors:
168
169           o  check — Builds in the same way as the cargo-check(1) command
170              with the dev profile.
171
172           o  test — Builds in the same way as the cargo-test(1) command,
173              enabling building in test mode which will enable tests and enable
174              the test cfg option. See rustc tests
175              <https://doc.rust-lang.org/rustc/tests/index.html> for more
176              detail.
177
178           o  bench — Builds in the same was as the cargo-bench(1) command,
179              similar to the test profile.
180
181           See the reference
182           <https://doc.rust-lang.org/cargo/reference/profiles.html> for more
183           details on profiles.
184
185       --timings=fmts
186           Output information how long each compilation takes, and track
187           concurrency information over time. Accepts an optional
188           comma-separated list of output formats; --timings without an
189           argument will default to --timings=html. Specifying an output format
190           (rather than the default) is unstable and requires
191           -Zunstable-options. Valid output formats:
192
193           o  html (unstable, requires -Zunstable-options): Write a
194              human-readable file cargo-timing.html to the target/cargo-timings
195              directory with a report of the compilation. Also write a report
196              to the same directory with a timestamp in the filename if you
197              want to look at older runs. HTML output is suitable for human
198              consumption only, and does not provide machine-readable timing
199              data.
200
201           o  json (unstable, requires -Zunstable-options): Emit
202              machine-readable JSON information about timing information.
203
204       --crate-type crate-type
205           Build for the given crate type. This flag accepts a comma-separated
206           list of 1 or more crate types, of which the allowed values are the
207           same as crate-type field in the manifest for configuring a Cargo
208           target. See crate-type field
209           <https://doc.rust-lang.org/cargo/reference/cargo-targets.html#the-crate-type-field>
210           for possible values.
211
212           If the manifest contains a list, and --crate-type is provided, the
213           command-line argument value will override what is in the manifest.
214
215           This flag only works when building a lib or example library target.
216
217   Output Options
218       --target-dir directory
219           Directory for all generated artifacts and intermediate files. May
220           also be specified with the CARGO_TARGET_DIR environment variable, or
221           the build.target-dir config value
222           <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
223           target in the root of the workspace.
224
225   Display Options
226       -v, --verbose
227           Use verbose output. May be specified twice for “very verbose”
228           output which includes extra output such as dependency warnings and
229           build script output. May also be specified with the term.verbose
230           config value
231           <https://doc.rust-lang.org/cargo/reference/config.html>.
232
233       -q, --quiet
234           Do not print cargo log messages. May also be specified with the
235           term.quiet config value
236           <https://doc.rust-lang.org/cargo/reference/config.html>.
237
238       --color when
239           Control when colored output is used. Valid values:
240
241           o  auto (default): Automatically detect if color support is
242              available on the terminal.
243
244           o  always: Always display colors.
245
246           o  never: Never display colors.
247
248           May also be specified with the term.color config value
249           <https://doc.rust-lang.org/cargo/reference/config.html>.
250
251       --message-format fmt
252           The output format for diagnostic messages. Can be specified multiple
253           times and consists of comma-separated values. Valid values:
254
255           o  human (default): Display in a human-readable text format.
256              Conflicts with short and json.
257
258           o  short: Emit shorter, human-readable text messages. Conflicts with
259              human and json.
260
261           o  json: Emit JSON messages to stdout. See the reference
262              <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages>
263              for more details. Conflicts with human and short.
264
265           o  json-diagnostic-short: Ensure the rendered field of JSON messages
266              contains the “short” rendering from rustc. Cannot be used
267              with human or short.
268
269           o  json-diagnostic-rendered-ansi: Ensure the rendered field of JSON
270              messages contains embedded ANSI color codes for respecting
271              rustc’s default color scheme. Cannot be used with human or
272              short.
273
274           o  json-render-diagnostics: Instruct Cargo to not include rustc
275              diagnostics in JSON messages printed, but instead Cargo itself
276              should render the JSON diagnostics coming from rustc. Cargo’s
277              own JSON diagnostics and others coming from rustc are still
278              emitted. Cannot be used with human or short.
279
280   Manifest Options
281       --manifest-path path
282           Path to the Cargo.toml file. By default, Cargo searches for the
283           Cargo.toml file in the current directory or any parent directory.
284
285       --ignore-rust-version
286           Ignore rust-version specification in packages.
287
288       --locked
289           Asserts that the exact same dependencies and versions are used as
290           when the existing Cargo.lock file was originally generated. Cargo
291           will exit with an error when either of the following scenarios
292           arises:
293
294           o  The lock file is missing.
295
296           o  Cargo attempted to change the lock file due to a different
297              dependency resolution.
298
299           It may be used in environments where deterministic builds are
300           desired, such as in CI pipelines.
301
302       --offline
303           Prevents Cargo from accessing the network for any reason. Without
304           this flag, Cargo will stop with an error if it needs to access the
305           network and the network is not available. With this flag, Cargo will
306           attempt to proceed without the network if possible.
307
308           Beware that this may result in different dependency resolution than
309           online mode. Cargo will restrict itself to crates that are
310           downloaded locally, even if there might be a newer version as
311           indicated in the local copy of the index. See the cargo-fetch(1)
312           command to download dependencies before going offline.
313
314           May also be specified with the net.offline config value
315           <https://doc.rust-lang.org/cargo/reference/config.html>.
316
317       --frozen
318           Equivalent to specifying both --locked and --offline.
319
320       --lockfile-path PATH
321           Changes the path of the lockfile from the default
322           (<workspace_root>/Cargo.lock) to PATH. PATH must end with Cargo.lock
323           (e.g. --lockfile-path /tmp/temporary-lockfile/Cargo.lock). Note that
324           providing --lockfile-path will ignore existing lockfile at the
325           default path, and instead will either use the lockfile from PATH, or
326           write a new lockfile into the provided PATH if it doesn’t exist.
327           This flag can be used to run most commands in read-only directories,
328           writing lockfile into the provided PATH.
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 #14421
333           <https://github.com/rust-lang/cargo/issues/14421>).
334
335   Common Options
336       +toolchain
337           If Cargo has been installed with rustup, and the first argument to
338           cargo begins with +, it will be interpreted as a rustup toolchain
339           name (such as +stable or +nightly). See the rustup documentation
340           <https://rust-lang.github.io/rustup/overrides.html> for more
341           information about how toolchain overrides work.
342
343       --config KEY=VALUE or PATH
344           Overrides a Cargo configuration value. The argument should be in
345           TOML syntax of KEY=VALUE, or provided as a path to an extra
346           configuration file. This flag may be specified multiple times. See
347           the command-line overrides section
348           <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides>
349           for more information.
350
351       -C PATH
352           Changes the current working directory before executing any specified
353           operations. This affects things like where cargo looks by default
354           for the project manifest (Cargo.toml), as well as the directories
355           searched for discovering .cargo/config.toml, for example. This
356           option must appear before the command name, for example cargo -C
357           path/to/my-project build.
358
359           This option is only available on the nightly channel
360           <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and
361           requires the -Z unstable-options flag to enable (see #10098
362           <https://github.com/rust-lang/cargo/issues/10098>).
363
364       -h, --help
365           Prints help information.
366
367       -Z flag
368           Unstable (nightly-only) flags to Cargo. Run cargo -Z help for
369           details.
370
371   Miscellaneous Options
372       -j N, --jobs N
373           Number of parallel jobs to run. May also be specified with the
374           build.jobs config value
375           <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
376           the number of logical CPUs. If negative, it sets the maximum number
377           of parallel jobs to the number of logical CPUs plus provided value.
378           If a string default is provided, it sets the value back to defaults.
379           Should not be 0.
380
381       --keep-going
382           Build as many crates in the dependency graph as possible, rather
383           than aborting the build on the first one that fails to build.
384
385           For example if the current package depends on dependencies fails and
386           works, one of which fails to build, cargo rustc -j1 may or may not
387           build the one that succeeds (depending on which one of the two
388           builds Cargo picked to run first), whereas cargo rustc -j1
389           --keep-going would definitely run both builds, even if the one run
390           first fails.
391
392       --future-incompat-report
393           Displays a future-incompat report for any future-incompatible
394           warnings produced during execution of this command
395
396           See cargo-report(1)
397
398ENVIRONMENT
399       See the reference
400       <https://doc.rust-lang.org/cargo/reference/environment-variables.html>
401       for details on environment variables that Cargo reads.
402
403EXIT STATUS
404       o  0: Cargo succeeded.
405
406       o  101: Cargo failed to complete.
407
408EXAMPLES
409       1. Check if your package (not including dependencies) uses unsafe code:
410
411              cargo rustc --lib -- -D unsafe-code
412
413       2. Try an experimental flag on the nightly compiler, such as this which
414          prints the size of every type:
415
416              cargo rustc --lib -- -Z print-type-sizes
417
418       3. Override crate-type field in Cargo.toml with command-line option:
419
420              cargo rustc --lib --crate-type lib,cdylib
421
422SEE ALSO
423       cargo(1), cargo-build(1), rustc(1)
424