src/tools/cargo/src/etc/man/cargo-build.1

   1 '\" t
   2 .TH "CARGO\-BUILD" "1"
   3 .nh
   4 .ad l
   5 .ss \n[.ss] 0
   6 .SH "NAME"
   7 cargo\-build \[em] Compile the current package
   8 .SH "SYNOPSIS"
   9 \fBcargo build\fR [\fIoptions\fR]
  10 .SH "DESCRIPTION"
  11 Compile local packages and all of their dependencies.
  12 .SH "OPTIONS"
  13 .SS "Package Selection"
  14 By default, when no package selection options are given, the packages selected
  15 depend on the selected manifest file (based on the current working directory if
  16 \fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then
  17 the workspaces default members are selected, otherwise only the package defined
  18 by the manifest will be selected.
  19 .sp
  20 The default members of a workspace can be set explicitly with the
  21 \fBworkspace.default\-members\fR key in the root manifest. If this is not set, a
  22 virtual workspace will include all workspace members (equivalent to passing
  23 \fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself.
  24 .sp
  25 \fB\-p\fR \fIspec\fR\[u2026],
  26 \fB\-\-package\fR \fIspec\fR\[u2026]
  27 .RS 4
  28 Build only the specified packages. See \fBcargo\-pkgid\fR(1) for the
  29 SPEC format. This flag may be specified multiple times and supports common Unix
  30 glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell accidentally
  31 expanding glob patterns before Cargo handles them, you must use single quotes or
  32 double quotes around each pattern.
  33 .RE
  34 .sp
  35 \fB\-\-workspace\fR
  36 .RS 4
  37 Build all members in the workspace.
  38 .RE
  39 .sp
  40 \fB\-\-all\fR
  41 .RS 4
  42 Deprecated alias for \fB\-\-workspace\fR\&.
  43 .RE
  44 .sp
  45 \fB\-\-exclude\fR \fISPEC\fR\[u2026]
  46 .RS 4
  47 Exclude the specified packages. Must be used in conjunction with the
  48 \fB\-\-workspace\fR flag. This flag may be specified multiple times and supports
  49 common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell
  50 accidentally expanding glob patterns before Cargo handles them, you must use
  51 single quotes or double quotes around each pattern.
  52 .RE
  53 .SS "Target Selection"
  54 When no target selection options are given, \fBcargo build\fR will build all
  55 binary and library targets of the selected packages. Binaries are skipped if
  56 they have \fBrequired\-features\fR that are missing.
  57 .sp
  58 Binary targets are automatically built if there is an integration test or
  59 benchmark being selected to build. This allows an integration
  60 test to execute the binary to exercise and test its behavior.
  61 The \fBCARGO_BIN_EXE_<name>\fR
  62 \fIenvironment variable\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html#environment\-variables\-cargo\-sets\-for\-crates>
  63 is set when the integration test is built so that it can use the
  64 \fI\f(BIenv\fI macro\fR <https://doc.rust\-lang.org/std/macro.env.html> to locate the
  65 executable.
  66 .sp
  67 Passing target selection flags will build only the specified
  68 targets.
  69 .sp
  70 Note that \fB\-\-bin\fR, \fB\-\-example\fR, \fB\-\-test\fR and \fB\-\-bench\fR flags also
  71 support common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your
  72 shell accidentally expanding glob patterns before Cargo handles them, you must
  73 use single quotes or double quotes around each glob pattern.
  74 .sp
  75 \fB\-\-lib\fR
  76 .RS 4
  77 Build the package\[cq]s library.
  78 .RE
  79 .sp
  80 \fB\-\-bin\fR \fIname\fR\[u2026]
  81 .RS 4
  82 Build the specified binary. This flag may be specified multiple times
  83 and supports common Unix glob patterns.
  84 .RE
  85 .sp
  86 \fB\-\-bins\fR
  87 .RS 4
  88 Build all binary targets.
  89 .RE
  90 .sp
  91 \fB\-\-example\fR \fIname\fR\[u2026]
  92 .RS 4
  93 Build the specified example. This flag may be specified multiple times
  94 and supports common Unix glob patterns.
  95 .RE
  96 .sp
  97 \fB\-\-examples\fR
  98 .RS 4
  99 Build all example targets.
 100 .RE
 101 .sp
 102 \fB\-\-test\fR \fIname\fR\[u2026]
 103 .RS 4
 104 Build the specified integration test. This flag may be specified
 105 multiple times and supports common Unix glob patterns.
 106 .RE
 107 .sp
 108 \fB\-\-tests\fR
 109 .RS 4
 110 Build all targets in test mode that have the \fBtest = true\fR manifest
 111 flag set. By default this includes the library and binaries built as
 112 unittests, and integration tests. Be aware that this will also build any
 113 required dependencies, so the lib target may be built twice (once as a
 114 unittest, and once as a dependency for binaries, integration tests, etc.).
 115 Targets may be enabled or disabled by setting the \fBtest\fR flag in the
 116 manifest settings for the target.
 117 .RE
 118 .sp
 119 \fB\-\-bench\fR \fIname\fR\[u2026]
 120 .RS 4
 121 Build the specified benchmark. This flag may be specified multiple
 122 times and supports common Unix glob patterns.
 123 .RE
 124 .sp
 125 \fB\-\-benches\fR
 126 .RS 4
 127 Build all targets in benchmark mode that have the \fBbench = true\fR
 128 manifest flag set. By default this includes the library and binaries built
 129 as benchmarks, and bench targets. Be aware that this will also build any
 130 required dependencies, so the lib target may be built twice (once as a
 131 benchmark, and once as a dependency for binaries, benchmarks, etc.).
 132 Targets may be enabled or disabled by setting the \fBbench\fR flag in the
 133 manifest settings for the target.
 134 .RE
 135 .sp
 136 \fB\-\-all\-targets\fR
 137 .RS 4
 138 Build all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&.
 139 .RE
 140 .SS "Feature Selection"
 141 The feature flags allow you to control which features are enabled. When no
 142 feature options are given, the \fBdefault\fR feature is activated for every
 143 selected package.
 144 .sp
 145 See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options>
 146 for more details.
 147 .sp
 148 \fB\-F\fR \fIfeatures\fR,
 149 \fB\-\-features\fR \fIfeatures\fR
 150 .RS 4
 151 Space or comma separated list of features to activate. Features of workspace
 152 members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may
 153 be specified multiple times, which enables all specified features.
 154 .RE
 155 .sp
 156 \fB\-\-all\-features\fR
 157 .RS 4
 158 Activate all available features of all selected packages.
 159 .RE
 160 .sp
 161 \fB\-\-no\-default\-features\fR
 162 .RS 4
 163 Do not activate the \fBdefault\fR feature of the selected packages.
 164 .RE
 165 .SS "Compilation Options"
 166 .sp
 167 \fB\-\-target\fR \fItriple\fR
 168 .RS 4
 169 Build for the given architecture. The default is the host architecture. The general format of the triple is
 170 \fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a
 171 list of supported targets. This flag may be specified multiple times.
 172 .sp
 173 This may also be specified with the \fBbuild.target\fR
 174 \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
 175 .sp
 176 Note that specifying this flag makes Cargo run in a different mode where the
 177 target artifacts are placed in a separate directory. See the
 178 \fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
 179 .RE
 180 .sp
 181 \fB\-r\fR,
 182 \fB\-\-release\fR
 183 .RS 4
 184 Build optimized artifacts with the \fBrelease\fR profile.
 185 See also the \fB\-\-profile\fR option for choosing a specific profile by name.
 186 .RE
 187 .sp
 188 \fB\-\-profile\fR \fIname\fR
 189 .RS 4
 190 Build with the given profile.
 191 See the \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles.html> for more details on profiles.
 192 .RE
 193 .sp
 194 \fB\-\-ignore\-rust\-version\fR
 195 .RS 4
 196 Build the target even if the selected Rust compiler is older than the
 197 required Rust version as configured in the project\[cq]s \fBrust\-version\fR field.
 198 .RE
 199 .sp
 200 \fB\-\-timings=\fR\fIfmts\fR
 201 .RS 4
 202 Output information how long each compilation takes, and track concurrency
 203 information over time. Accepts an optional comma\-separated list of output
 204 formats; \fB\-\-timings\fR without an argument will default to \fB\-\-timings=html\fR\&.
 205 Specifying an output format (rather than the default) is unstable and requires
 206 \fB\-Zunstable\-options\fR\&. Valid output formats:
 207 .sp
 208 .RS 4
 209 \h'-04'\(bu\h'+02'\fBhtml\fR (unstable, requires \fB\-Zunstable\-options\fR): Write a human\-readable file \fBcargo\-timing.html\fR to the
 210 \fBtarget/cargo\-timings\fR directory with a report of the compilation. Also write
 211 a report to the same directory with a timestamp in the filename if you want
 212 to look at older runs. HTML output is suitable for human consumption only,
 213 and does not provide machine\-readable timing data.
 214 .RE
 215 .sp
 216 .RS 4
 217 \h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON
 218 information about timing information.
 219 .RE
 220 .RE
 221 .SS "Output Options"
 222 .sp
 223 \fB\-\-target\-dir\fR \fIdirectory\fR
 224 .RS 4
 225 Directory for all generated artifacts and intermediate files. May also be
 226 specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the
 227 \fBbuild.target\-dir\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
 228 Defaults to \fBtarget\fR in the root of the workspace.
 229 .RE
 230 .sp
 231 \fB\-\-out\-dir\fR \fIdirectory\fR
 232 .RS 4
 233 Copy final artifacts to this directory.
 234 .sp
 235 This option is unstable and available only on the
 236 \fInightly channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html>
 237 and requires the \fB\-Z unstable\-options\fR flag to enable.
 238 See <https://github.com/rust\-lang/cargo/issues/6790> for more information.
 239 .RE
 240 .SS "Display Options"
 241 .sp
 242 \fB\-v\fR,
 243 \fB\-\-verbose\fR
 244 .RS 4
 245 Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
 246 includes extra output such as dependency warnings and build script output.
 247 May also be specified with the \fBterm.verbose\fR
 248 \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
 249 .RE
 250 .sp
 251 \fB\-q\fR,
 252 \fB\-\-quiet\fR
 253 .RS 4
 254 Do not print cargo log messages.
 255 May also be specified with the \fBterm.quiet\fR
 256 \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
 257 .RE
 258 .sp
 259 \fB\-\-color\fR \fIwhen\fR
 260 .RS 4
 261 Control when colored output is used. Valid values:
 262 .sp
 263 .RS 4
 264 \h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
 265 terminal.
 266 .RE
 267 .sp
 268 .RS 4
 269 \h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
 270 .RE
 271 .sp
 272 .RS 4
 273 \h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
 274 .RE
 275 .sp
 276 May also be specified with the \fBterm.color\fR
 277 \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
 278 .RE
 279 .sp
 280 \fB\-\-message\-format\fR \fIfmt\fR
 281 .RS 4
 282 The output format for diagnostic messages. Can be specified multiple times
 283 and consists of comma\-separated values. Valid values:
 284 .sp
 285 .RS 4
 286 \h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. Conflicts with
 287 \fBshort\fR and \fBjson\fR\&.
 288 .RE
 289 .sp
 290 .RS 4
 291 \h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. Conflicts with \fBhuman\fR
 292 and \fBjson\fR\&.
 293 .RE
 294 .sp
 295 .RS 4
 296 \h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See
 297 \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages>
 298 for more details. Conflicts with \fBhuman\fR and \fBshort\fR\&.
 299 .RE
 300 .sp
 301 .RS 4
 302 \h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains
 303 the \[lq]short\[rq] rendering from rustc. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
 304 .RE
 305 .sp
 306 .RS 4
 307 \h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages
 308 contains embedded ANSI color codes for respecting rustc\[cq]s default color
 309 scheme. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
 310 .RE
 311 .sp
 312 .RS 4
 313 \h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics
 314 in JSON messages printed, but instead Cargo itself should render the
 315 JSON diagnostics coming from rustc. Cargo\[cq]s own JSON diagnostics and others
 316 coming from rustc are still emitted. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
 317 .RE
 318 .RE
 319 .sp
 320 \fB\-\-build\-plan\fR
 321 .RS 4
 322 Outputs a series of JSON messages to stdout that indicate the commands to run
 323 the build.
 324 .sp
 325 This option is unstable and available only on the
 326 \fInightly channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html>
 327 and requires the \fB\-Z unstable\-options\fR flag to enable.
 328 See <https://github.com/rust\-lang/cargo/issues/5579> for more information.
 329 .RE
 330 .SS "Manifest Options"
 331 .sp
 332 \fB\-\-manifest\-path\fR \fIpath\fR
 333 .RS 4
 334 Path to the \fBCargo.toml\fR file. By default, Cargo searches for the
 335 \fBCargo.toml\fR file in the current directory or any parent directory.
 336 .RE
 337 .sp
 338 \fB\-\-frozen\fR,
 339 \fB\-\-locked\fR
 340 .RS 4
 341 Either of these flags requires that the \fBCargo.lock\fR file is
 342 up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will
 343 exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from
 344 attempting to access the network to determine if it is out\-of\-date.
 345 .sp
 346 These may be used in environments where you want to assert that the
 347 \fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network
 348 access.
 349 .RE
 350 .sp
 351 \fB\-\-offline\fR
 352 .RS 4
 353 Prevents Cargo from accessing the network for any reason. Without this
 354 flag, Cargo will stop with an error if it needs to access the network and
 355 the network is not available. With this flag, Cargo will attempt to
 356 proceed without the network if possible.
 357 .sp
 358 Beware that this may result in different dependency resolution than online
 359 mode. Cargo will restrict itself to crates that are downloaded locally, even
 360 if there might be a newer version as indicated in the local copy of the index.
 361 See the \fBcargo\-fetch\fR(1) command to download dependencies before going
 362 offline.
 363 .sp
 364 May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
 365 .RE
 366 .SS "Common Options"
 367 .sp
 368 \fB+\fR\fItoolchain\fR
 369 .RS 4
 370 If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
 371 begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
 372 as \fB+stable\fR or \fB+nightly\fR).
 373 See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
 374 for more information about how toolchain overrides work.
 375 .RE
 376 .sp
 377 \fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
 378 .RS 4
 379 Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
 380 or provided as a path to an extra configuration file. This flag may be specified multiple times.
 381 See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
 382 .RE
 383 .sp
 384 \fB\-C\fR \fIPATH\fR
 385 .RS 4
 386 Changes the current working directory before executing any specified operations. This affects
 387 things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
 388 the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
 389 appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
 390 .sp
 391 This option is only available on the \fInightly
 392 channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
 393 requires the \fB\-Z unstable\-options\fR flag to enable (see
 394 \fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
 395 .RE
 396 .sp
 397 \fB\-h\fR,
 398 \fB\-\-help\fR
 399 .RS 4
 400 Prints help information.
 401 .RE
 402 .sp
 403 \fB\-Z\fR \fIflag\fR
 404 .RS 4
 405 Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
 406 .RE
 407 .SS "Miscellaneous Options"
 408 .sp
 409 \fB\-j\fR \fIN\fR,
 410 \fB\-\-jobs\fR \fIN\fR
 411 .RS 4
 412 Number of parallel jobs to run. May also be specified with the
 413 \fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
 414 the number of logical CPUs. If negative, it sets the maximum number of
 415 parallel jobs to the number of logical CPUs plus provided value.
 416 Should not be 0.
 417 .RE
 418 .sp
 419 \fB\-\-keep\-going\fR
 420 .RS 4
 421 Build as many crates in the dependency graph as possible, rather than aborting
 422 the build on the first one that fails to build. Unstable, requires
 423 \fB\-Zunstable\-options\fR\&.
 424 .RE
 425 .sp
 426 \fB\-\-future\-incompat\-report\fR
 427 .RS 4
 428 Displays a future\-incompat report for any future\-incompatible warnings
 429 produced during execution of this command
 430 .sp
 431 See \fBcargo\-report\fR(1)
 432 .RE
 433 .SH "ENVIRONMENT"
 434 See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
 435 details on environment variables that Cargo reads.
 436 .SH "EXIT STATUS"
 437 .sp
 438 .RS 4
 439 \h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
 440 .RE
 441 .sp
 442 .RS 4
 443 \h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
 444 .RE
 445 .SH "EXAMPLES"
 446 .sp
 447 .RS 4
 448 \h'-04' 1.\h'+01'Build the local package and all of its dependencies:
 449 .sp
 450 .RS 4
 451 .nf
 452 cargo build
 453 .fi
 454 .RE
 455 .RE
 456 .sp
 457 .RS 4
 458 \h'-04' 2.\h'+01'Build with optimizations:
 459 .sp
 460 .RS 4
 461 .nf
 462 cargo build \-\-release
 463 .fi
 464 .RE
 465 .RE
 466 .SH "SEE ALSO"
 467 \fBcargo\fR(1), \fBcargo\-rustc\fR(1)