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 selected manifest file (based on the current
48 working directory if --manifest-path is not given). If the manifest is
49 the root of a workspace then the workspaces default members are
50 selected, otherwise only the package defined by the manifest will be
51 selected.
52 The default members of a workspace can be set explicitly with the
54 workspace.default-members key in the root manifest. If this is not set,
55 a virtual workspace will include all workspace members (equivalent to
56 passing --workspace), and a non-virtual workspace will include only the
57 root crate itself.
58 -p SPEC..., --package SPEC...
60 Benchmark only the specified packages. See cargo-pkgid(1) for the
61 SPEC format. This flag may be specified multiple times.
62 --workspace
64 Benchmark all members in the workspace.
65 --all
67 Deprecated alias for --workspace.
68 --exclude SPEC...
70 Exclude the specified packages. Must be used in conjunction with
71 the --workspace flag. This flag may be specified multiple times.
72 Target Selection
74 When no target selection options are given, cargo bench will build the
75 following targets of the selected packages:
76 · lib — used to link with binaries and benchmarks
78 · bins (only if benchmark targets are built and required features are
80 available)
81 · lib as a benchmark
83 · bins as benchmarks
85 · benchmark targets
87 The default behavior can be changed by setting the bench flag for the
89 target in the manifest settings. Setting examples to bench = true will
90 build and run the example as a benchmark. Setting targets to bench =
91 false will stop them from being benchmarked by default. Target
92 selection options that take a target by name ignore the bench flag and
93 will always benchmark the given target.
94 Passing target selection flags will benchmark only the specified
96 targets.
97 --lib
99 Benchmark the package’s library.
100 --bin NAME...
102 Benchmark the specified binary. This flag may be specified multiple
103 times.
104 --bins
106 Benchmark all binary targets.
107 --example NAME...
109 Benchmark the specified example. This flag may be specified
110 multiple times.
111 --examples
113 Benchmark all example targets.
114 --test NAME...
116 Benchmark the specified integration test. This flag may be
117 specified multiple times.
118 --tests
120 Benchmark all targets in test mode that have the test = true
121 manifest flag set. By default this includes the library and
122 binaries built as unittests, and integration tests. Be aware that
123 this will also build any required dependencies, so the lib target
124 may be built twice (once as a unittest, and once as a dependency
125 for binaries, integration tests, etc.). Targets may be enabled or
126 disabled by setting the test flag in the manifest settings for the
127 target.
128 --bench NAME...
130 Benchmark the specified benchmark. This flag may be specified
131 multiple times.
132 --benches
134 Benchmark all targets in benchmark mode that have the bench = true
135 manifest flag set. By default this includes the library and
136 binaries built as benchmarks, and bench targets. Be aware that this
137 will also build any required dependencies, so the lib target may be
138 built twice (once as a benchmark, and once as a dependency for
139 binaries, benchmarks, etc.). Targets may be enabled or disabled by
140 setting the bench flag in the manifest settings for the target.
141 --all-targets
143 Benchmark all targets. This is equivalent to specifying --lib
144 --bins --tests --benches --examples.
145 Feature Selection
147 When no feature options are given, the default feature is activated for
148 every selected package.
149 --features FEATURES
151 Space or comma separated list of features to activate. These
152 features only apply to the current directory’s package. Features of
153 direct dependencies may be enabled with <dep-name>/<feature-name>
154 syntax.
155 --all-features
157 Activate all available features of all selected packages.
158 --no-default-features
160 Do not activate the default feature of the current directory’s
161 package.
162 Compilation Options
164 --target TRIPLE
165 Benchmark for the given architecture. The default is the host
166 architecture. The general format of the triple is
167 <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for
168 a list of supported targets.
169 This may also be specified with the build.target config value
171 <https://doc.rust-lang.org/cargo/reference/config.html>.
172 Output Options
174 --target-dir DIRECTORY
175 Directory for all generated artifacts and intermediate files. May
176 also be specified with the CARGO_TARGET_DIR environment variable,
177 or the build.target-dir config value
178 <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults
179 to target in the root of the workspace.
180 Display Options
182 By default the Rust test harness hides output from benchmark execution
183 to keep results readable. Benchmark output can be recovered (e.g., for
184 debugging) by passing --nocapture to the benchmark binaries:
185 cargo bench -- --nocapture
187 -v, --verbose
189 Use verbose output. May be specified twice for "very verbose"
190 output which includes extra output such as dependency warnings and
191 build script output. May also be specified with the term.verbose
192 config value
193 <https://doc.rust-lang.org/cargo/reference/config.html>.
194 -q, --quiet
196 No output printed to stdout.
197 --color WHEN
199 Control when colored output is used. Valid values:
200 · auto (default): Automatically detect if color support is
202 available on the terminal.
203 · always: Always display colors.
205 · never: Never display colors.
207 May also be specified with the term.color config value
209 <https://doc.rust-lang.org/cargo/reference/config.html>.
210 --message-format FMT
212 The output format for diagnostic messages. Can be specified
213 multiple times and consists of comma-separated values. Valid
214 values:
215 · human (default): Display in a human-readable text format.
217 · short: Emit shorter, human-readable text messages.
219 · json: Emit JSON messages to stdout.
221 · json-diagnostic-short: Ensure the rendered field of JSON
223 messages contains the "short" rendering from rustc.
224 · json-diagnostic-rendered-ansi: Ensure the rendered field of
226 JSON messages contains embedded ANSI color codes for respecting
227 rustc’s default color scheme.
228 · json-render-diagnostics: Instruct Cargo to not include rustc
230 diagnostics in in JSON messages printed, but instead Cargo
231 itself should render the JSON diagnostics coming from rustc.
232 Cargo’s own JSON diagnostics and others coming from rustc are
233 still emitted.
234 Manifest Options
236 --manifest-path PATH
237 Path to the Cargo.toml file. By default, Cargo searches in the
238 current directory or any parent directory for the Cargo.toml file.
239 --frozen, --locked
241 Either of these flags requires that the Cargo.lock file is
242 up-to-date. If the lock file is missing, or it needs to be updated,
243 Cargo will exit with an error. The --frozen flag also prevents
244 Cargo from attempting to access the network to determine if it is
245 out-of-date.
246 These may be used in environments where you want to assert that the
248 Cargo.lock file is up-to-date (such as a CI build) or want to avoid
249 network access.
250 --offline
252 Prevents Cargo from accessing the network for any reason. Without
253 this flag, Cargo will stop with an error if it needs to access the
254 network and the network is not available. With this flag, Cargo
255 will attempt to proceed without the network if possible.
256 Beware that this may result in different dependency resolution than
258 online mode. Cargo will restrict itself to crates that are
259 downloaded locally, even if there might be a newer version as
260 indicated in the local copy of the index. See the cargo-fetch(1)
261 command to download dependencies before going offline.
262 May also be specified with the net.offline config value
264 <https://doc.rust-lang.org/cargo/reference/config.html>.
265 Common Options
267 -h, --help
268 Prints help information.
269 -Z FLAG...
271 Unstable (nightly-only) flags to Cargo. Run cargo -Z help for
272 details.
273 Miscellaneous Options
275 The --jobs argument affects the building of the benchmark executable
276 but does not affect how many threads are used when running the
277 benchmarks. The Rust test harness runs benchmarks serially in a single
278 thread.
279 -j N, --jobs N
281 Number of parallel jobs to run. May also be specified with the
282 build.jobs config value
283 <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults
284 to the number of CPUs.
285
287 Profiles may be used to configure compiler options such as optimization
288 levels and debug settings. See the reference
289 <https://doc.rust-lang.org/cargo/reference/manifest.html#the-profile-sections>
290 for more details.
291 Benchmarks are always built with the bench profile. Binary and lib
293 targets are built separately as benchmarks with the bench profile.
294 Library targets are built with the release profiles when linked to
295 binaries and benchmarks. Dependencies use the release profile.
296 If you need a debug build of a benchmark, try building it with
298 cargo-build(1) which will use the test profile which is by default
299 unoptimized and includes debug information. You can then run the
300 debug-enabled benchmark manually.
301
303 See the reference
304 <https://doc.rust-lang.org/cargo/reference/environment-variables.html>
305 for details on environment variables that Cargo reads.
306
308 0
309 Cargo succeeded.
310 101
312 Cargo failed to complete.
313
315 1. Build and execute all the benchmarks of the current package:
316 cargo bench
318 2. Run only a specific benchmark within a specific benchmark target:
320 cargo bench --bench bench_name -- modname::some_benchmark
322
324 cargo(1), cargo-test(1)
325 2019-08-19 CARGO-BENCH(1)