fork/cargo
git clone https://git.julia.blue/fork/cargo
f2932725b
home-0.5.12
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