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

   1 CARGO-RUN(1)
   2
   3 NAME
   4        cargo-run — Run the current package
   5
   6 SYNOPSIS
   7        cargo run [options] [-- args]
   8
   9 DESCRIPTION
  10        Run a binary or example of the local package.
  11
  12        All the arguments following the two dashes (--) are passed to the binary
  13        to run. If you’re passing arguments to both Cargo and the binary, the
  14        ones after -- go to the binary, the ones before go to Cargo.
  15
  16        Unlike cargo-test(1) and cargo-bench(1), cargo run sets the working
  17        directory of the binary executed to the current working directory, same
  18        as if it was executed in the shell directly.
  19
  20 OPTIONS
  21    Package Selection
  22        By default, the package in the current working directory is selected.
  23        The -p flag can be used to choose a different package in a workspace.
  24
  25        -p spec, --package spec
  26            The package to run. See cargo-pkgid(1) for the SPEC format.
  27
  28    Target Selection
  29        When no target selection options are given, cargo run will run the
  30        binary target. If there are multiple binary targets, you must pass a
  31        target flag to choose one. Or, the default-run field may be specified in
  32        the [package] section of Cargo.toml to choose the name of the binary to
  33        run by default.
  34
  35        --bin name
  36            Run the specified binary.
  37
  38        --example name
  39            Run the specified example.
  40
  41    Feature Selection
  42        The feature flags allow you to control which features are enabled. When
  43        no feature options are given, the default feature is activated for every
  44        selected package.
  45
  46        See the features documentation
  47        <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options>
  48        for more details.
  49
  50        -F features, --features features
  51            Space or comma separated list of features to activate. Features of
  52            workspace members may be enabled with package-name/feature-name
  53            syntax. This flag may be specified multiple times, which enables all
  54            specified features.
  55
  56        --all-features
  57            Activate all available features of all selected packages.
  58
  59        --no-default-features
  60            Do not activate the default feature of the selected packages.
  61
  62    Compilation Options
  63        --target triple
  64            Run for the given architecture. The default is the host
  65            architecture. The general format of the triple is
  66            <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for
  67            a list of supported targets.
  68
  69            This may also be specified with the build.target config value
  70            <https://doc.rust-lang.org/cargo/reference/config.html>.
  71
  72            Note that specifying this flag makes Cargo run in a different mode
  73            where the target artifacts are placed in a separate directory. See
  74            the build cache
  75            <https://doc.rust-lang.org/cargo/guide/build-cache.html>
  76            documentation for more details.
  77
  78        -r, --release
  79            Run optimized artifacts with the release profile. See also the
  80            --profile option for choosing a specific profile by name.
  81
  82        --profile name
  83            Run with the given profile. See the the reference
  84            <https://doc.rust-lang.org/cargo/reference/profiles.html> for more
  85            details on profiles.
  86
  87        --ignore-rust-version
  88            Run the target even if the selected Rust compiler is older than the
  89            required Rust version as configured in the project’s rust-version
  90            field.
  91
  92        --timings=fmts
  93            Output information how long each compilation takes, and track
  94            concurrency information over time. Accepts an optional
  95            comma-separated list of output formats; --timings without an
  96            argument will default to --timings=html. Specifying an output format
  97            (rather than the default) is unstable and requires
  98            -Zunstable-options. Valid output formats:
  99
 100            o  html (unstable, requires -Zunstable-options): Write a
 101               human-readable file cargo-timing.html to the target/cargo-timings
 102               directory with a report of the compilation. Also write a report
 103               to the same directory with a timestamp in the filename if you
 104               want to look at older runs. HTML output is suitable for human
 105               consumption only, and does not provide machine-readable timing
 106               data.
 107
 108            o  json (unstable, requires -Zunstable-options): Emit
 109               machine-readable JSON information about timing information.
 110
 111    Output Options
 112        --target-dir directory
 113            Directory for all generated artifacts and intermediate files. May
 114            also be specified with the CARGO_TARGET_DIR environment variable, or
 115            the build.target-dir config value
 116            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
 117            target in the root of the workspace.
 118
 119    Display Options
 120        -v, --verbose
 121            Use verbose output. May be specified twice for “very verbose”
 122            output which includes extra output such as dependency warnings and
 123            build script output. May also be specified with the term.verbose
 124            config value
 125            <https://doc.rust-lang.org/cargo/reference/config.html>.
 126
 127        -q, --quiet
 128            Do not print cargo log messages. May also be specified with the
 129            term.quiet config value
 130            <https://doc.rust-lang.org/cargo/reference/config.html>.
 131
 132        --color when
 133            Control when colored output is used. Valid values:
 134
 135            o  auto (default): Automatically detect if color support is
 136               available on the terminal.
 137
 138            o  always: Always display colors.
 139
 140            o  never: Never display colors.
 141
 142            May also be specified with the term.color config value
 143            <https://doc.rust-lang.org/cargo/reference/config.html>.
 144
 145        --message-format fmt
 146            The output format for diagnostic messages. Can be specified multiple
 147            times and consists of comma-separated values. Valid values:
 148
 149            o  human (default): Display in a human-readable text format.
 150               Conflicts with short and json.
 151
 152            o  short: Emit shorter, human-readable text messages. Conflicts with
 153               human and json.
 154
 155            o  json: Emit JSON messages to stdout. See the reference
 156               <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages>
 157               for more details. Conflicts with human and short.
 158
 159            o  json-diagnostic-short: Ensure the rendered field of JSON messages
 160               contains the “short” rendering from rustc. Cannot be used
 161               with human or short.
 162
 163            o  json-diagnostic-rendered-ansi: Ensure the rendered field of JSON
 164               messages contains embedded ANSI color codes for respecting
 165               rustc’s default color scheme. Cannot be used with human or
 166               short.
 167
 168            o  json-render-diagnostics: Instruct Cargo to not include rustc
 169               diagnostics in JSON messages printed, but instead Cargo itself
 170               should render the JSON diagnostics coming from rustc. Cargo’s
 171               own JSON diagnostics and others coming from rustc are still
 172               emitted. Cannot be used with human or short.
 173
 174    Manifest Options
 175        --manifest-path path
 176            Path to the Cargo.toml file. By default, Cargo searches for the
 177            Cargo.toml file in the current directory or any parent directory.
 178
 179        --frozen, --locked
 180            Either of these flags requires that the Cargo.lock file is
 181            up-to-date. If the lock file is missing, or it needs to be updated,
 182            Cargo will exit with an error. The --frozen flag also prevents Cargo
 183            from attempting to access the network to determine if it is
 184            out-of-date.
 185
 186            These may be used in environments where you want to assert that the
 187            Cargo.lock file is up-to-date (such as a CI build) or want to avoid
 188            network access.
 189
 190        --offline
 191            Prevents Cargo from accessing the network for any reason. Without
 192            this flag, Cargo will stop with an error if it needs to access the
 193            network and the network is not available. With this flag, Cargo will
 194            attempt to proceed without the network if possible.
 195
 196            Beware that this may result in different dependency resolution than
 197            online mode. Cargo will restrict itself to crates that are
 198            downloaded locally, even if there might be a newer version as
 199            indicated in the local copy of the index. See the cargo-fetch(1)
 200            command to download dependencies before going offline.
 201
 202            May also be specified with the net.offline config value
 203            <https://doc.rust-lang.org/cargo/reference/config.html>.
 204
 205    Common Options
 206        +toolchain
 207            If Cargo has been installed with rustup, and the first argument to
 208            cargo begins with +, it will be interpreted as a rustup toolchain
 209            name (such as +stable or +nightly). See the rustup documentation
 210            <https://rust-lang.github.io/rustup/overrides.html> for more
 211            information about how toolchain overrides work.
 212
 213        --config KEY=VALUE or PATH
 214            Overrides a Cargo configuration value. The argument should be in
 215            TOML syntax of KEY=VALUE, or provided as a path to an extra
 216            configuration file. This flag may be specified multiple times. See
 217            the command-line overrides section
 218            <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides>
 219            for more information.
 220
 221        -C PATH
 222            Changes the current working directory before executing any specified
 223            operations. This affects things like where cargo looks by default
 224            for the project manifest (Cargo.toml), as well as the directories
 225            searched for discovering .cargo/config.toml, for example. This
 226            option must appear before the command name, for example cargo -C
 227            path/to/my-project build.
 228
 229            This option is only available on the nightly channel
 230            <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and
 231            requires the -Z unstable-options flag to enable (see #10098
 232            <https://github.com/rust-lang/cargo/issues/10098>).
 233
 234        -h, --help
 235            Prints help information.
 236
 237        -Z flag
 238            Unstable (nightly-only) flags to Cargo. Run cargo -Z help for
 239            details.
 240
 241    Miscellaneous Options
 242        -j N, --jobs N
 243            Number of parallel jobs to run. May also be specified with the
 244            build.jobs config value
 245            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
 246            the number of logical CPUs. If negative, it sets the maximum number
 247            of parallel jobs to the number of logical CPUs plus provided value.
 248            If a string default is provided, it sets the value back to defaults.
 249            Should not be 0.
 250
 251        --keep-going
 252            Build as many crates in the dependency graph as possible, rather
 253            than aborting the build on the first one that fails to build.
 254
 255            For example if the current package depends on dependencies fails and
 256            works, one of which fails to build, cargo run -j1 may or may not
 257            build the one that succeeds (depending on which one of the two
 258            builds Cargo picked to run first), whereas cargo run -j1
 259            --keep-going would definitely run both builds, even if the one run
 260            first fails.
 261
 262 ENVIRONMENT
 263        See the reference
 264        <https://doc.rust-lang.org/cargo/reference/environment-variables.html>
 265        for details on environment variables that Cargo reads.
 266
 267 EXIT STATUS
 268        o  0: Cargo succeeded.
 269
 270        o  101: Cargo failed to complete.
 271
 272 EXAMPLES
 273        1. Build the local package and run its main target (assuming only one
 274           binary):
 275
 276               cargo run
 277
 278        2. Run an example with extra arguments:
 279
 280               cargo run --example exname -- --exoption exarg1 exarg2
 281
 282 SEE ALSO
 283        cargo(1), cargo-build(1)
 284