| <h2 id="cargo_bench_name">NAME</h2> |
| <div class="sectionbody"> |
| <p>cargo-bench - Execute benchmarks of a package</p> |
| </div> |
| <div class="sect1"> |
| <h2 id="cargo_bench_synopsis">SYNOPSIS</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p><code>cargo bench [<em>OPTIONS</em>] [BENCHNAME] [-- <em>BENCH-OPTIONS</em>]</code></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="cargo_bench_description">DESCRIPTION</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Compile and execute benchmarks.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The benchmark filtering argument <code>BENCHNAME</code> and all the arguments following |
| the two dashes (<code>--</code>) are passed to the benchmark binaries and thus to |
| <em>libtest</em> (rustc’s built in unit-test and micro-benchmarking framework). 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. For details about libtest’s |
| arguments see the output of <code>cargo bench -- --help</code>. As an example, this will |
| run only the benchmark named <code>foo</code> (and skip other similarly named benchmarks |
| like <code>foobar</code>):</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>cargo bench -- foo --exact</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Benchmarks are built with the <code>--test</code> option to <code>rustc</code> which creates an |
| executable with a <code>main</code> function that automatically runs all functions |
| annotated with the <code>#[bench]</code> attribute. Cargo passes the <code>--bench</code> flag to |
| the test harness to tell it to run only benchmarks.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The libtest harness may be disabled by setting <code>harness = false</code> in the target |
| manifest settings, in which case your code will need to provide its own <code>main</code> |
| function to handle running benchmarks.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="cargo_bench_options">OPTIONS</h2> |
| <div class="sectionbody"> |
| <div class="sect2"> |
| <h3 id="cargo_bench_benchmark_options">Benchmark Options</h3> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><strong>--no-run</strong></dt> |
| <dd> |
| <p>Compile, but don’t run benchmarks.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--no-fail-fast</strong></dt> |
| <dd> |
| <p>Run all benchmarks regardless of failure. Without this flag, Cargo will exit |
| after the first executable fails. The Rust test harness will run all |
| benchmarks within the executable to completion, this flag only applies to |
| the executable as a whole.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="cargo_bench_package_selection">Package Selection</h3> |
| <div class="paragraph"> |
| <p>By default, when no package selection options are given, the packages selected |
| depend on the selected manifest file (based on the current working directory if |
| <code>--manifest-path</code> is not given). If the manifest is the root of a workspace then |
| the workspaces default members are selected, otherwise only the package defined |
| by the manifest will be selected.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The default members of a workspace can be set explicitly with the |
| <code>workspace.default-members</code> key in the root manifest. If this is not set, a |
| virtual workspace will include all workspace members (equivalent to passing |
| <code>--workspace</code>), and a non-virtual workspace will include only the root crate itself.</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>Benchmark only the specified packages. See <a href="cargo-pkgid.html">cargo-pkgid(1)</a> for the |
| SPEC format. This flag may be specified multiple times.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--workspace</strong></dt> |
| <dd> |
| <p>Benchmark all members in the workspace.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--all</strong></dt> |
| <dd> |
| <p>Deprecated alias for <code>--workspace</code>.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--exclude</strong> <em>SPEC</em>…​</dt> |
| <dd> |
| <p>Exclude the specified packages. Must be used in conjunction with the |
| <code>--workspace</code> flag. This flag may be specified multiple times.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="cargo_bench_target_selection">Target Selection</h3> |
| <div class="paragraph"> |
| <p>When no target selection options are given, <code>cargo bench</code> will build the |
| following targets of the selected packages:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>lib — used to link with binaries and benchmarks</p> |
| </li> |
| <li> |
| <p>bins (only if benchmark targets are built and required features are |
| available)</p> |
| </li> |
| <li> |
| <p>lib as a benchmark</p> |
| </li> |
| <li> |
| <p>bins as benchmarks</p> |
| </li> |
| <li> |
| <p>benchmark targets</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The default behavior can be changed by setting the <code>bench</code> flag for the target |
| in the manifest settings. Setting examples to <code>bench = true</code> will build and |
| run the example as a benchmark. Setting targets to <code>bench = false</code> will stop |
| them from being benchmarked by default. Target selection options that take a |
| target by name ignore the <code>bench</code> flag and will always benchmark the given |
| target.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Passing target selection flags will benchmark only the |
| specified targets.</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><strong>--lib</strong></dt> |
| <dd> |
| <p>Benchmark the package’s library.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--bin</strong> <em>NAME</em>…​</dt> |
| <dd> |
| <p>Benchmark the specified binary. This flag may be specified multiple times.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--bins</strong></dt> |
| <dd> |
| <p>Benchmark all binary targets.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--example</strong> <em>NAME</em>…​</dt> |
| <dd> |
| <p>Benchmark the specified example. This flag may be specified multiple times.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--examples</strong></dt> |
| <dd> |
| <p>Benchmark all example targets.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--test</strong> <em>NAME</em>…​</dt> |
| <dd> |
| <p>Benchmark the specified integration test. This flag may be specified multiple |
| times.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--tests</strong></dt> |
| <dd> |
| <p>Benchmark all targets in test mode that have the <code>test = true</code> manifest |
| flag set. By default this includes the library and binaries built as |
| unittests, and integration tests. Be aware that this will also build any |
| required dependencies, so the lib target may be built twice (once as a |
| unittest, and once as a dependency for binaries, integration tests, etc.). |
| Targets may be enabled or disabled by setting the <code>test</code> flag in the |
| manifest settings for the target.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--bench</strong> <em>NAME</em>…​</dt> |
| <dd> |
| <p>Benchmark the specified benchmark. This flag may be specified multiple times.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--benches</strong></dt> |
| <dd> |
| <p>Benchmark all targets in benchmark mode that have the <code>bench = true</code> |
| manifest flag set. By default this includes the library and binaries built |
| as benchmarks, and bench targets. Be aware that this will also build any |
| required dependencies, so the lib target may be built twice (once as a |
| benchmark, and once as a dependency for binaries, benchmarks, etc.). |
| Targets may be enabled or disabled by setting the <code>bench</code> flag in the |
| manifest settings for the target.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--all-targets</strong></dt> |
| <dd> |
| <p>Benchmark all targets. This is equivalent to specifying <code>--lib --bins |
| --tests --benches --examples</code>.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="cargo_bench_feature_selection">Feature Selection</h3> |
| <div class="paragraph"> |
| <p>The feature flags allow you to control the enabled features for the "current" |
| package. The "current" package is the package in the current directory, or the |
| one specified in <code>--manifest-path</code>. If running in the root of a virtual |
| workspace, then the default features are selected for all workspace members, |
| or all features if <code>--all-features</code> is specified.</p> |
| </div> |
| <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. This flag may be |
| specified multiple times, which enables all specified features.</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_bench_compilation_options">Compilation Options</h3> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><strong>--target</strong> <em>TRIPLE</em></dt> |
| <dd> |
| <p>Benchmark 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> |
| <div class="paragraph"> |
| <p>Note that specifying this flag makes Cargo run in a different mode where the |
| target artifacts are placed in a separate directory. See the |
| <a href="../guide/build-cache.html">build cache</a> documentation for more details.</p> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="cargo_bench_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_bench_display_options">Display Options</h3> |
| <div class="paragraph"> |
| <p>By default the Rust test harness hides output from benchmark execution to keep |
| results readable. Benchmark output can be recovered (e.g., for debugging) by |
| passing <code>--nocapture</code> to the benchmark binaries:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>cargo bench -- --nocapture</pre> |
| </div> |
| </div> |
| <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. See |
| <a href="../reference/external-tools.html#json-messages">the reference</a> |
| for more details.</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_bench_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_bench_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_bench_miscellaneous_options">Miscellaneous Options</h3> |
| <div class="paragraph"> |
| <p>The <code>--jobs</code> argument affects the building of the benchmark executable but |
| does not affect how many threads are used when running the benchmarks. The |
| Rust test harness runs benchmarks serially in a single thread.</p> |
| </div> |
| <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_bench_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/profiles.html">the reference</a> |
| for more details.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Benchmarks are always built with the <code>bench</code> profile. Binary and lib targets |
| are built separately as benchmarks with the <code>bench</code> profile. Library targets |
| are built with the <code>release</code> profiles when linked to binaries and benchmarks. |
| Dependencies use the <code>release</code> profile.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If you need a debug build of a benchmark, try building it with |
| <a href="cargo-build.html">cargo-build(1)</a> which will use the <code>test</code> profile which is by default |
| unoptimized and includes debug information. You can then run the debug-enabled |
| benchmark manually.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="cargo_bench_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_bench_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_bench_examples">EXAMPLES</h2> |
| <div class="sectionbody"> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Build and execute all the benchmarks of the current package:</p> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>cargo bench</pre> |
| </div> |
| </div> |
| </li> |
| <li> |
| <p>Run only a specific benchmark within a specific benchmark target:</p> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>cargo bench --bench bench_name -- modname::some_benchmark</pre> |
| </div> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="cargo_bench_see_also">SEE ALSO</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p><a href="index.html">cargo(1)</a>, <a href="cargo-test.html">cargo-test(1)</a></p> |
| </div> |
| </div> |
| </div> |