fork/cargo
git clone https://git.julia.blue/fork/cargo
de128bea7
0.88.0
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