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 The feature flags allow you to control the enabled features for the
148 "current" package. The "current" package is the package in the current
149 directory, or the one specified in --manifest-path. If running in the
150 root of a virtual workspace, then the default features are selected for
151 all workspace members, or all features if --all-features is specified.
152 When no feature options are given, the default feature is activated for
154 every selected package.
155 --features FEATURES
157 Space or comma separated list of features to activate. These
158 features only apply to the current directory’s package. Features of
159 direct dependencies may be enabled with <dep-name>/<feature-name>
160 syntax. This flag may be specified multiple times, which enables
161 all specified features.
162 --all-features
164 Activate all available features of all selected packages.
165 --no-default-features
167 Do not activate the default feature of the current directory’s
168 package.
169 Compilation Options
171 --target TRIPLE
172 Benchmark for the given architecture. The default is the host
173 architecture. The general format of the triple is
174 <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for
175 a list of supported targets.
176 This may also be specified with the build.target config value
178 <https://doc.rust-lang.org/cargo/reference/config.html>.
179 Note that specifying this flag makes Cargo run in a different mode
181 where the target artifacts are placed in a separate directory. See
182 the build cache
183 <https://doc.rust-lang.org/cargo/guide/build-cache.html>
184 documentation for more details.
185 Output Options
187 --target-dir DIRECTORY
188 Directory for all generated artifacts and intermediate files. May
189 also be specified with the CARGO_TARGET_DIR environment variable,
190 or the build.target-dir config value
191 <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults
192 to target in the root of the workspace.
193 Display Options
195 By default the Rust test harness hides output from benchmark execution
196 to keep results readable. Benchmark output can be recovered (e.g., for
197 debugging) by passing --nocapture to the benchmark binaries:
198 cargo bench -- --nocapture
200 -v, --verbose
202 Use verbose output. May be specified twice for "very verbose"
203 output which includes extra output such as dependency warnings and
204 build script output. May also be specified with the term.verbose
205 config value
206 <https://doc.rust-lang.org/cargo/reference/config.html>.
207 -q, --quiet
209 No output printed to stdout.
210 --color WHEN
212 Control when colored output is used. Valid values:
213 · auto (default): Automatically detect if color support is
215 available on the terminal.
216 · always: Always display colors.
218 · never: Never display colors.
220 May also be specified with the term.color config value
222 <https://doc.rust-lang.org/cargo/reference/config.html>.
223 --message-format FMT
225 The output format for diagnostic messages. Can be specified
226 multiple times and consists of comma-separated values. Valid
227 values:
228 · human (default): Display in a human-readable text format.
230 · short: Emit shorter, human-readable text messages.
232 · json: Emit JSON messages to stdout. See the reference
234 <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages>
235 for more details.
236 · json-diagnostic-short: Ensure the rendered field of JSON
238 messages contains the "short" rendering from rustc.
239 · json-diagnostic-rendered-ansi: Ensure the rendered field of
241 JSON messages contains embedded ANSI color codes for respecting
242 rustc’s default color scheme.
243 · json-render-diagnostics: Instruct Cargo to not include rustc
245 diagnostics in in JSON messages printed, but instead Cargo
246 itself should render the JSON diagnostics coming from rustc.
247 Cargo’s own JSON diagnostics and others coming from rustc are
248 still emitted.
249 Manifest Options
251 --manifest-path PATH
252 Path to the Cargo.toml file. By default, Cargo searches for the
253 Cargo.toml file in the current directory or any parent directory.
254 --frozen, --locked
256 Either of these flags requires that the Cargo.lock file is
257 up-to-date. If the lock file is missing, or it needs to be updated,
258 Cargo will exit with an error. The --frozen flag also prevents
259 Cargo from attempting to access the network to determine if it is
260 out-of-date.
261 These may be used in environments where you want to assert that the
263 Cargo.lock file is up-to-date (such as a CI build) or want to avoid
264 network access.
265 --offline
267 Prevents Cargo from accessing the network for any reason. Without
268 this flag, Cargo will stop with an error if it needs to access the
269 network and the network is not available. With this flag, Cargo
270 will attempt to proceed without the network if possible.
271 Beware that this may result in different dependency resolution than
273 online mode. Cargo will restrict itself to crates that are
274 downloaded locally, even if there might be a newer version as
275 indicated in the local copy of the index. See the cargo-fetch(1)
276 command to download dependencies before going offline.
277 May also be specified with the net.offline config value
279 <https://doc.rust-lang.org/cargo/reference/config.html>.
280 Common Options
282 -h, --help
283 Prints help information.
284 -Z FLAG...
286 Unstable (nightly-only) flags to Cargo. Run cargo -Z help for
287 details.
288 Miscellaneous Options
290 The --jobs argument affects the building of the benchmark executable
291 but does not affect how many threads are used when running the
292 benchmarks. The Rust test harness runs benchmarks serially in a single
293 thread.
294 -j N, --jobs N
296 Number of parallel jobs to run. May also be specified with the
297 build.jobs config value
298 <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults
299 to the number of CPUs.
300
302 Profiles may be used to configure compiler options such as optimization
303 levels and debug settings. See the reference
304 <https://doc.rust-lang.org/cargo/reference/profiles.html> for more
305 details.
306 Benchmarks are always built with the bench profile. Binary and lib
308 targets are built separately as benchmarks with the bench profile.
309 Library targets are built with the release profiles when linked to
310 binaries and benchmarks. Dependencies use the release profile.
311 If you need a debug build of a benchmark, try building it with
313 cargo-build(1) which will use the test profile which is by default
314 unoptimized and includes debug information. You can then run the
315 debug-enabled benchmark manually.
316
318 See the reference
319 <https://doc.rust-lang.org/cargo/reference/environment-variables.html>
320 for details on environment variables that Cargo reads.
321
323 0
324 Cargo succeeded.
325 101
327 Cargo failed to complete.
328
330 1. Build and execute all the benchmarks of the current package:
331 cargo bench
333 2. Run only a specific benchmark within a specific benchmark target:
335 cargo bench --bench bench_name -- modname::some_benchmark
337
339 cargo(1), cargo-test(1)
340 2020-02-06 CARGO-BENCH(1)