src/tools/cargo/src/doc/man/generated_txt/cargo-check.txt

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