| <h2 id="cargo_run_name">NAME</h2> |
| <div class="sectionbody"> |
| <p>cargo-run - Run the current package</p> |
| </div> |
| <div class="sect1"> |
| <h2 id="cargo_run_synopsis">SYNOPSIS</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p><code>cargo run [<em>OPTIONS</em>] [-- <em>ARGS</em>]</code></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="cargo_run_description">DESCRIPTION</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Run a binary or example of the local package.</p> |
| </div> |
| <div class="paragraph"> |
| <p>All the arguments following the two dashes (<code>--</code>) are passed to the binary to |
| run. If you’re passing arguments to both Cargo and the binary, the ones after |
| <code>--</code> go to the binary, the ones before go to Cargo.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="cargo_run_options">OPTIONS</h2> |
| <div class="sectionbody"> |
| <div class="sect2"> |
| <h3 id="cargo_run_package_selection">Package Selection</h3> |
| <div class="paragraph"> |
| <p>By default, the package in the current working directory is selected. The <code>-p</code> |
| flag can be used to choose a different package in a workspace.</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><strong>-p</strong> <em>SPEC</em></dt> |
| <dt class="hdlist1"><strong>--package</strong> <em>SPEC</em></dt> |
| <dd> |
| <p>The package to run. See <a href="cargo-pkgid.html">cargo-pkgid(1)</a> for |
| the SPEC format.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="cargo_run_target_selection">Target Selection</h3> |
| <div class="paragraph"> |
| <p>When no target selection options are given, <code>cargo run</code> will run the binary |
| target. If there are multiple binary targets, you must pass a target flag to |
| choose one. Or, the <code>default-run</code> field may be specified in the <code>[package]</code> |
| section of <code>Cargo.toml</code> to choose the name of the binary to run by default.</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><strong>--bin</strong> <em>NAME</em></dt> |
| <dd> |
| <p>Run the specified binary.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--example</strong> <em>NAME</em></dt> |
| <dd> |
| <p>Run the specified example.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="cargo_run_feature_selection">Feature Selection</h3> |
| <div class="paragraph"> |
| <p>When no feature options are given, the <code>default</code> feature is activated for |
| every selected package.</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><strong>--features</strong> <em>FEATURES</em></dt> |
| <dd> |
| <p>Space or comma separated list of features to activate. These features only |
| apply to the current directory’s package. Features of direct dependencies |
| may be enabled with <code><dep-name>/<feature-name></code> syntax.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--all-features</strong></dt> |
| <dd> |
| <p>Activate all available features of all selected packages.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--no-default-features</strong></dt> |
| <dd> |
| <p>Do not activate the <code>default</code> feature of the current directory’s |
| package.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="cargo_run_compilation_options">Compilation Options</h3> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><strong>--target</strong> <em>TRIPLE</em></dt> |
| <dd> |
| <p>Run for the given architecture. The default is the host |
| architecture. The general format of the triple is |
| <code><arch><sub>-<vendor>-<sys>-<abi></code>. Run <code>rustc --print target-list</code> for a |
| list of supported targets.</p> |
| <div class="paragraph"> |
| <p>This may also be specified with the <code>build.target</code> |
| <a href="../reference/config.html">config value</a>.</p> |
| </div> |
| </dd> |
| <dt class="hdlist1"><strong>--release</strong></dt> |
| <dd> |
| <p>Run optimized artifacts with the <code>release</code> profile. See the |
| <a href="#cargo_run_profiles">PROFILES</a> section for details on how this affects profile selection.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="cargo_run_output_options">Output Options</h3> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><strong>--target-dir</strong> <em>DIRECTORY</em></dt> |
| <dd> |
| <p>Directory for all generated artifacts and intermediate files. May also be |
| specified with the <code>CARGO_TARGET_DIR</code> environment variable, or the |
| <code>build.target-dir</code> <a href="../reference/config.html">config value</a>. Defaults |
| to <code>target</code> in the root of the workspace.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="cargo_run_display_options">Display Options</h3> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><strong>-v</strong></dt> |
| <dt class="hdlist1"><strong>--verbose</strong></dt> |
| <dd> |
| <p>Use verbose output. May be specified twice for "very verbose" output which |
| includes extra output such as dependency warnings and build script output. |
| May also be specified with the <code>term.verbose</code> |
| <a href="../reference/config.html">config value</a>.</p> |
| </dd> |
| <dt class="hdlist1"><strong>-q</strong></dt> |
| <dt class="hdlist1"><strong>--quiet</strong></dt> |
| <dd> |
| <p>No output printed to stdout.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--color</strong> <em>WHEN</em></dt> |
| <dd> |
| <p>Control when colored output is used. Valid values:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>auto</code> (default): Automatically detect if color support is available on the |
| terminal.</p> |
| </li> |
| <li> |
| <p><code>always</code>: Always display colors.</p> |
| </li> |
| <li> |
| <p><code>never</code>: Never display colors.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>May also be specified with the <code>term.color</code> |
| <a href="../reference/config.html">config value</a>.</p> |
| </div> |
| </dd> |
| <dt class="hdlist1"><strong>--message-format</strong> <em>FMT</em></dt> |
| <dd> |
| <p>The output format for diagnostic messages. Can be specified multiple times |
| and consists of comma-separated values. Valid values:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>human</code> (default): Display in a human-readable text format.</p> |
| </li> |
| <li> |
| <p><code>short</code>: Emit shorter, human-readable text messages.</p> |
| </li> |
| <li> |
| <p><code>json</code>: Emit JSON messages to stdout.</p> |
| </li> |
| <li> |
| <p><code>json-diagnostic-short</code>: Ensure the <code>rendered</code> field of JSON messages contains |
| the "short" rendering from rustc.</p> |
| </li> |
| <li> |
| <p><code>json-diagnostic-rendered-ansi</code>: Ensure the <code>rendered</code> field of JSON messages |
| contains embedded ANSI color codes for respecting rustc’s default color |
| scheme.</p> |
| </li> |
| <li> |
| <p><code>json-render-diagnostics</code>: Instruct Cargo to not include rustc diagnostics in |
| in JSON messages printed, but instead Cargo itself should render the |
| JSON diagnostics coming from rustc. Cargo’s own JSON diagnostics and others |
| coming from rustc are still emitted.</p> |
| </li> |
| </ul> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="cargo_run_manifest_options">Manifest Options</h3> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><strong>--manifest-path</strong> <em>PATH</em></dt> |
| <dd> |
| <p>Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the |
| <code>Cargo.toml</code> file in the current directory or any parent directory.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--frozen</strong></dt> |
| <dt class="hdlist1"><strong>--locked</strong></dt> |
| <dd> |
| <p>Either of these flags requires that the <code>Cargo.lock</code> file is |
| up-to-date. If the lock file is missing, or it needs to be updated, Cargo will |
| exit with an error. The <code>--frozen</code> flag also prevents Cargo from |
| attempting to access the network to determine if it is out-of-date.</p> |
| <div class="paragraph"> |
| <p>These may be used in environments where you want to assert that the |
| <code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network |
| access.</p> |
| </div> |
| </dd> |
| <dt class="hdlist1"><strong>--offline</strong></dt> |
| <dd> |
| <p>Prevents Cargo from accessing the network for any reason. Without this |
| flag, Cargo will stop with an error if it needs to access the network and |
| the network is not available. With this flag, Cargo will attempt to |
| proceed without the network if possible.</p> |
| <div class="paragraph"> |
| <p>Beware that this may result in different dependency resolution than online |
| mode. Cargo will restrict itself to crates that are downloaded locally, even |
| if there might be a newer version as indicated in the local copy of the index. |
| See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going |
| offline.</p> |
| </div> |
| <div class="paragraph"> |
| <p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</p> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="cargo_run_common_options">Common Options</h3> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><strong>-h</strong></dt> |
| <dt class="hdlist1"><strong>--help</strong></dt> |
| <dd> |
| <p>Prints help information.</p> |
| </dd> |
| <dt class="hdlist1"><strong>-Z</strong> <em>FLAG</em>…​</dt> |
| <dd> |
| <p>Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for |
| details.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="cargo_run_miscellaneous_options">Miscellaneous Options</h3> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><strong>-j</strong> <em>N</em></dt> |
| <dt class="hdlist1"><strong>--jobs</strong> <em>N</em></dt> |
| <dd> |
| <p>Number of parallel jobs to run. May also be specified with the |
| <code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to |
| the number of CPUs.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="cargo_run_profiles">PROFILES</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Profiles may be used to configure compiler options such as optimization levels |
| and debug settings. See |
| <a href="../reference/manifest.html#the-profile-sections">the reference</a> |
| for more details.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Profile selection depends on the target and crate being built. By default the |
| <code>dev</code> or <code>test</code> profiles are used. If the <code>--release</code> flag is given, then the |
| <code>release</code> or <code>bench</code> profiles are used.</p> |
| </div> |
| <table class="tableblock frame-all grid-all fit-content"> |
| <colgroup> |
| <col> |
| <col> |
| <col> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Target</th> |
| <th class="tableblock halign-left valign-top">Default Profile</th> |
| <th class="tableblock halign-left valign-top"><code>--release</code> Profile</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">lib, bin, example</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>dev</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>release</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">test, bench, or any target<br> |
| in "test" or "bench" mode</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>test</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>bench</code></p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>Dependencies use the <code>dev</code>/<code>release</code> profiles.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="cargo_run_environment">ENVIRONMENT</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>See <a href="../reference/environment-variables.html">the reference</a> for |
| details on environment variables that Cargo reads.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="cargo_run_exit_status">Exit Status</h2> |
| <div class="sectionbody"> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">0</dt> |
| <dd> |
| <p>Cargo succeeded.</p> |
| </dd> |
| <dt class="hdlist1">101</dt> |
| <dd> |
| <p>Cargo failed to complete.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="cargo_run_examples">EXAMPLES</h2> |
| <div class="sectionbody"> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Build the local package and run its main target (assuming only one binary):</p> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>cargo run</pre> |
| </div> |
| </div> |
| </li> |
| <li> |
| <p>Run an example with extra arguments:</p> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>cargo run --example exname -- --exoption exarg1 exarg2</pre> |
| </div> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="cargo_run_see_also">SEE ALSO</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p><a href="index.html">cargo(1)</a>, <a href="cargo-build.html">cargo-build(1)</a></p> |
| </div> |
| </div> |
| </div> |