1CARGO-BENCH(1) CARGO-BENCH(1)
2
6 cargo-bench - Execute benchmarks of a package
7
9 cargo bench [OPTIONS] [BENCHNAME] [-- BENCH-OPTIONS]
10
12 Compile and execute benchmarks.
13 The benchmark filtering argument BENCHNAME and all the arguments
15 following the two dashes (--) are passed to the benchmark binaries and
16 thus to libtest (rustc’s built in unit-test and micro-benchmarking
17 framework). If you’re passing arguments to both Cargo and the binary,
18 the ones after -- go to the binary, the ones before go to Cargo. For
19 details about libtest’s arguments see the output of cargo bench —
20 --help. As an example, this will run only the benchmark named foo (and
21 skip other similarly named benchmarks like foobar):
22 cargo bench -- foo --exact
24 Benchmarks are built with the --test option to rustc which creates an
26 executable with a main function that automatically runs all functions
27 annotated with the #[bench] attribute. Cargo passes the --bench flag to
28 the test harness to tell it to run only benchmarks.
29 The libtest harness may be disabled by setting harness = false in the
31 target manifest settings, in which case your code will need to provide
32 its own main function to handle running benchmarks.
33
35 Benchmark Options
36 --no-run
37 Compile, but don’t run benchmarks.
38 --no-fail-fast
40 Run all benchmarks regardless of failure. Without this flag, Cargo
41 will exit after the first executable fails. The Rust test harness
42 will run all benchmarks within the executable to completion, this
43 flag only applies to the executable as a whole.
44 Package Selection
46 By default, when no package selection options are given, the packages
47 selected depend on the current working directory. In the root of a
48 virtual workspace, all workspace members are selected (--all is
49 implied). Otherwise, only the package in the current directory will be
50 selected. The default packages may be overridden with the
51 workspace.default-members key in the root Cargo.toml manifest.
52 -p SPEC..., --package SPEC...
54 Benchmark only the specified packages. See cargo-pkgid(1) for the
55 SPEC format. This flag may be specified multiple times.
56 --all
58 Benchmark all members in the workspace.
59 --exclude SPEC...
61 Exclude the specified packages. Must be used in conjunction with
62 the --all flag. This flag may be specified multiple times.
63 Target Selection
65 When no target selection options are given, cargo bench will build the
66 following targets of the selected packages:
67 · lib — used to link with binaries and benchmarks
69 · bins (only if benchmark targets are built and required features are
71 available)
72 · lib as a benchmark
74 · bins as benchmarks
76 · benchmark targets
78 The default behavior can be changed by setting the bench flag for the
80 target in the manifest settings. Setting examples to bench = true will
81 build and run the example as a benchmark. Setting targets to bench =
82 false will stop them from being benchmarked by default. Target
83 selection options that take a target by name ignore the bench flag and
84 will always benchmark the given target.
85 Passing target selection flags will benchmark only the specified
87 targets.
88 --lib
90 Benchmark the package’s library.
91 --bin NAME...
93 Benchmark the specified binary. This flag may be specified multiple
94 times.
95 --bins
97 Benchmark all binary targets.
98 --example NAME...
100 Benchmark the specified example. This flag may be specified
101 multiple times.
102 --examples
104 Benchmark all example targets.
105 --test NAME...
107 Benchmark the specified integration test. This flag may be
108 specified multiple times.
109 --tests
111 Benchmark all targets in test mode that have the test = true
112 manifest flag set. By default this includes the library and
113 binaries built as unittests, and integration tests. Be aware that
114 this will also build any required dependencies, so the lib target
115 may be built twice (once as a unittest, and once as a dependency
116 for binaries, integration tests, etc.). Targets may be enabled or
117 disabled by setting the test flag in the manifest settings for the
118 target.
119 --bench NAME...
121 Benchmark the specified benchmark. This flag may be specified
122 multiple times.
123 --benches
125 Benchmark all targets in benchmark mode that have the bench = true
126 manifest flag set. By default this includes the library and
127 binaries built as benchmarks, and bench targets. Be aware that this
128 will also build any required dependencies, so the lib target may be
129 built twice (once as a benchmark, and once as a dependency for
130 binaries, benchmarks, etc.). Targets may be enabled or disabled by
131 setting the bench flag in the manifest settings for the target.
132 --all-targets
134 Benchmark all targets. This is equivalent to specifying --lib
135 --bins --tests --benches --examples.
136 Feature Selection
138 When no feature options are given, the default feature is activated for
139 every selected package.
140 --features FEATURES
142 Space or comma separated list of features to activate. These
143 features only apply to the current directory’s package. Features of
144 direct dependencies may be enabled with <dep-name>/<feature-name>
145 syntax.
146 --all-features
148 Activate all available features of all selected packages.
149 --no-default-features
151 Do not activate the default feature of the current directory’s
152 package.
153 Compilation Options
155 --target TRIPLE
156 Benchmark for the given architecture. The default is the host
157 architecture. The general format of the triple is
158 <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for
159 a list of supported targets.
160 This may also be specified with the build.target config value
162 <https://doc.rust-lang.org/cargo/reference/config.html>.
163 Output Options
165 --target-dir DIRECTORY
166 Directory for all generated artifacts and intermediate files. May
167 also be specified with the CARGO_TARGET_DIR environment variable,
168 or the build.target-dir config value
169 <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults
170 to target in the root of the workspace.
171 Display Options
173 By default the Rust test harness hides output from benchmark execution
174 to keep results readable. Benchmark output can be recovered (e.g., for
175 debugging) by passing --nocapture to the benchmark binaries:
176 cargo bench -- --nocapture
178 -v, --verbose
180 Use verbose output. May be specified twice for "very verbose"
181 output which includes extra output such as dependency warnings and
182 build script output. May also be specified with the term.verbose
183 config value
184 <https://doc.rust-lang.org/cargo/reference/config.html>.
185 -q, --quiet
187 No output printed to stdout.
188 --color WHEN
190 Control when colored output is used. Valid values:
191 · auto (default): Automatically detect if color support is
193 available on the terminal.
194 · always: Always display colors.
196 · never: Never display colors.
198 May also be specified with the term.color config value
200 <https://doc.rust-lang.org/cargo/reference/config.html>.
201 --message-format FMT
203 The output format for diagnostic messages. Valid values:
204 · human (default): Display in a human-readable text format.
206 · json: Emit JSON messages to stdout.
208 · short: Emit shorter, human-readable text messages.
210 Manifest Options
212 --manifest-path PATH
213 Path to the Cargo.toml file. By default, Cargo searches in the
214 current directory or any parent directory for the Cargo.toml file.
215 --frozen, --locked
217 Either of these flags requires that the Cargo.lock file is
218 up-to-date. If the lock file is missing, or it needs to be updated,
219 Cargo will exit with an error. The --frozen flag also prevents
220 Cargo from attempting to access the network to determine if it is
221 out-of-date.
222 These may be used in environments where you want to assert that the
224 Cargo.lock file is up-to-date (such as a CI build) or want to avoid
225 network access.
226 Common Options
228 -h, --help
229 Prints help information.
230 -Z FLAG...
232 Unstable (nightly-only) flags to Cargo. Run cargo -Z help for
233 details.
234 Miscellaneous Options
236 The --jobs argument affects the building of the benchmark executable
237 but does not affect how many threads are used when running the
238 benchmarks. The Rust test harness runs benchmarks serially in a single
239 thread.
240 -j N, --jobs N
242 Number of parallel jobs to run. May also be specified with the
243 build.jobs config value
244 <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults
245 to the number of CPUs.
246
248 Profiles may be used to configure compiler options such as optimization
249 levels and debug settings. See the reference
250 <https://doc.rust-lang.org/cargo/reference/manifest.html#the-profile-sections>
251 for more details.
252 Benchmarks are always built with the bench profile. Binary and lib
254 targets are built separately as benchmarks with the bench profile.
255 Library targets are built with the release profiles when linked to
256 binaries and benchmarks. Dependencies use the release profile.
257 If you need a debug build of a benchmark, try building it with
259 cargo-build(1) which will use the test profile which is by default
260 unoptimized and includes debug information. You can then run the
261 debug-enabled benchmark manually.
262
264 See the reference
265 <https://doc.rust-lang.org/cargo/reference/environment-variables.html>
266 for details on environment variables that Cargo reads.
267
269 0
270 Cargo succeeded.
271 101
273 Cargo failed to complete.
274
276 1. Build and execute all the benchmarks of the current package:
277 cargo bench
279 2. Run only a specific benchmark within a specific benchmark target:
281 cargo bench --bench bench_name -- modname::some_benchmark
283
285 cargo(1), cargo-test(1)
286 2018-12-23 CARGO-BENCH(1)