= cargo-bench(1)
:idprefix: cargo_bench_
:doctype: manpage
:actionverb: Benchmark
:nouns: benchmarks

== NAME

cargo-bench - Execute benchmarks of a package

== SYNOPSIS

`cargo bench [_OPTIONS_] [BENCHNAME] [-- _BENCH-OPTIONS_]`

== DESCRIPTION

Compile and execute benchmarks.

The benchmark filtering argument `BENCHNAME` and all the arguments following
the two dashes (`--`) are passed to the benchmark binaries and thus to
_libtest_ (rustc's built in unit-test and micro-benchmarking framework).  If
you're passing arguments to both Cargo and the binary, the ones after `--` go
to the binary, the ones before go to Cargo.  For details about libtest's
arguments see the output of `cargo bench \-- --help`.  As an example, this will
run only the benchmark named `foo` (and skip other similarly named benchmarks
like `foobar`):

    cargo bench -- foo --exact

Benchmarks are built with the `--test` option to `rustc` which creates an
executable with a `main` function that automatically runs all functions
annotated with the `#[bench]` attribute. Cargo passes the `--bench` flag to
the test harness to tell it to run only benchmarks.

The libtest harness may be disabled by setting `harness = false` in the target
manifest settings, in which case your code will need to provide its own `main`
function to handle running benchmarks.

== OPTIONS

=== Benchmark Options

include::options-test.adoc[]

=== Package Selection

include::options-packages.adoc[]

=== Target Selection

When no target selection options are given, `cargo bench` will build the
following targets of the selected packages:

- lib — used to link with binaries and benchmarks
- bins (only if benchmark targets are built and required features are
  available)
- lib as a benchmark
- bins as benchmarks
- benchmark targets

The default behavior can be changed by setting the `bench` flag for the target
in the manifest settings. Setting examples to `bench = true` will build and
run the example as a benchmark. Setting targets to `bench = false` will stop
them from being benchmarked by default. Target selection options that take a
target by name ignore the `bench` flag and will always benchmark the given
target.

include::options-targets.adoc[]

include::options-features.adoc[]

=== Compilation Options

include::options-target-triple.adoc[]

=== Output Options

include::options-target-dir.adoc[]

=== Display Options

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 `--nocapture` to the benchmark binaries:

    cargo bench -- --nocapture

include::options-display.adoc[]

include::options-message-format.adoc[]

=== Manifest Options

include::options-manifest-path.adoc[]

include::options-locked.adoc[]

=== Common Options

include::options-common.adoc[]

=== Miscellaneous Options

The `--jobs` 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.

include::options-jobs.adoc[]

== PROFILES

Profiles may be used to configure compiler options such as optimization levels
and debug settings. See
linkcargo:reference/profiles.html[the reference]
for more details.

Benchmarks are always built with the `bench` profile. Binary and lib targets
are built separately as benchmarks with the `bench` profile. Library targets
are built with the `release` profiles when linked to binaries and benchmarks.
Dependencies use the `release` profile.

If you need a debug build of a benchmark, try building it with
man:cargo-build[1] which will use the `test` profile which is by default
unoptimized and includes debug information. You can then run the debug-enabled
benchmark manually.

include::section-environment.adoc[]

include::section-exit-status.adoc[]

== EXAMPLES

. Build and execute all the benchmarks of the current package:

    cargo bench

. Run only a specific benchmark within a specific benchmark target:

    cargo bench --bench bench_name -- modname::some_benchmark

== SEE ALSO
man:cargo[1], man:cargo-test[1]
