blob: 32c98dadaebe6ef3a132e097085508994d57f868 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
# cargo-bench(1)
{{*set actionverb="Benchmark"}}
{{*set nouns="benchmarks"}}
{{*set multitarget=true}}
## 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 are 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` and check out the rustc
book's chapter on how tests work at
<https://doc.rust-lang.org/rustc/tests/index.html>.
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 a
special executable by linking your code with libtest. The executable
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.
> **Note**: The
> [`#[bench]` attribute](https://doc.rust-lang.org/nightly/unstable-book/library-features/test.html)
> is currently unstable and only available on the
> [nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html).
> There are some packages available on
> [crates.io](https://crates.io/keywords/benchmark) that may help with
> running benchmarks on the stable channel, such as
> [Criterion](https://crates.io/crates/criterion).
By default, `cargo bench` uses the [`bench` profile], which enables
optimizations and disables debugging information. If you need to debug a
benchmark, you can use the `--profile=dev` command-line option to switch to
the dev profile. You can then run the debug-enabled benchmark within a
debugger.
[`bench` profile]: ../reference/profiles.html#bench
## OPTIONS
### Benchmark Options
{{> options-test }}
{{> section-package-selection }}
### 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.
{{> options-targets-bin-auto-built }}
{{> options-targets }}
{{> section-features }}
### Compilation Options
{{#options}}
{{> options-target-triple }}
{{> options-profile }}
{{> options-ignore-rust-version }}
{{> options-timings }}
{{/options}}
### Output Options
{{#options}}
{{> options-target-dir }}
{{/options}}
### 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
{{#options}}
{{> options-display }}
{{> options-message-format }}
{{/options}}
### Manifest Options
{{#options}}
{{> options-manifest-path }}
{{> options-locked }}
{{/options}}
{{> section-options-common }}
### 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.
{{#options}}
{{> options-jobs }}
{{> options-keep-going }}
{{/options}}
{{> section-environment }}
{{> section-exit-status }}
## EXAMPLES
1. Build and execute all the benchmarks of the current package:
cargo bench
2. 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}}
|
