1CARGO-BENCH(1)              General Commands Manual             CARGO-BENCH(1)
2
3
4

NAME

6       cargo-bench - Execute benchmarks of a package
7

SYNOPSIS

9       cargo bench [options] [benchname] [-- bench-options]
10

DESCRIPTION

12       Compile and execute benchmarks.
13
14       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 are 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 and check out the rustc book's chapter on how tests work at
21       <https://doc.rust-lang.org/rustc/tests/index.html>.
22
23       As an example, this will run only the benchmark named foo (and skip
24       other similarly named benchmarks like foobar):
25
26           cargo bench -- foo --exact
27
28       Benchmarks are built with the --test option to rustc which creates an
29       executable with a main function that automatically runs all functions
30       annotated with the #[bench] attribute. Cargo passes the --bench flag to
31       the test harness to tell it to run only benchmarks.
32
33       The libtest harness may be disabled by setting harness = false in the
34       target manifest settings, in which case your code will need to provide
35       its own main function to handle running benchmarks.
36
37          Note: The #[bench] attribute
38          <https://doc.rust-lang.org/nightly/unstable-book/library-features/test.html>
39          is currently unstable and only available on the nightly channel
40          <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html>.
41          There are some packages available on crates.io
42          <https://crates.io/keywords/benchmark> that may help with
43          running benchmarks on the stable channel, such as Criterion
44          <https://crates.io/crates/criterion>.
45
46       By default, cargo bench uses the bench profile
47       <https://doc.rust-lang.org/cargo/reference/profiles.html#bench>, which
48       enables optimizations and disables debugging information. If you need
49       to debug a benchmark, you can use the --profile=dev command-line option
50       to switch to the dev profile. You can then run the debug-enabled
51       benchmark within a debugger.
52

OPTIONS

54   Benchmark Options
55       --no-run
56           Compile, but don't run benchmarks.
57
58       --no-fail-fast
59           Run all benchmarks regardless of failure. Without this flag, Cargo
60           will exit after the first executable fails. The Rust test harness
61           will run all benchmarks within the executable to completion, this
62           flag only applies to the executable as a whole.
63
64   Package Selection
65       By default, when no package selection options are given, the packages
66       selected depend on the selected manifest file (based on the current
67       working directory if --manifest-path is not given). If the manifest is
68       the root of a workspace then the workspaces default members are
69       selected, otherwise only the package defined by the manifest will be
70       selected.
71
72       The default members of a workspace can be set explicitly with the
73       workspace.default-members key in the root manifest. If this is not set,
74       a virtual workspace will include all workspace members (equivalent to
75       passing --workspace), and a non-virtual workspace will include only the
76       root crate itself.
77
78       -p spec..., --package spec...
79           Benchmark only the specified packages. See cargo-pkgid(1) for the
80           SPEC format. This flag may be specified multiple times and supports
81           common Unix glob patterns like *, ? and []. However, to avoid your
82           shell accidentally expanding glob patterns before Cargo handles
83           them, you must use single quotes or double quotes around each
84           pattern.
85
86       --workspace
87           Benchmark all members in the workspace.
88
89       --all
90           Deprecated alias for --workspace.
91
92       --exclude SPEC...
93           Exclude the specified packages. Must be used in conjunction with
94           the --workspace flag. This flag may be specified multiple times and
95           supports common Unix glob patterns like *, ? and []. However, to
96           avoid your shell accidentally expanding glob patterns before Cargo
97           handles them, you must use single quotes or double quotes around
98           each pattern.
99
100   Target Selection
101       When no target selection options are given, cargo bench will build the
102       following targets of the selected packages:
103
104       •  lib — used to link with binaries and benchmarks
105
106       •  bins (only if benchmark targets are built and required features are
107           available)
108
109       •  lib as a benchmark
110
111       •  bins as benchmarks
112
113       •  benchmark targets
114
115       The default behavior can be changed by setting the bench flag for the
116       target in the manifest settings. Setting examples to bench = true will
117       build and run the example as a benchmark. Setting targets to bench =
118       false will stop them from being benchmarked by default. Target
119       selection options that take a target by name ignore the bench flag and
120       will always benchmark the given target.
121
122       Passing target selection flags will benchmark only the specified
123       targets.
124
125       Note that --bin, --example, --test and --bench flags also support
126       common Unix glob patterns like *, ? and []. However, to avoid your
127       shell accidentally expanding glob patterns before Cargo handles them,
128       you must use single quotes or double quotes around each glob pattern.
129
130       --lib
131           Benchmark the package's library.
132
133       --bin name...
134           Benchmark the specified binary. This flag may be specified multiple
135           times and supports common Unix glob patterns.
136
137       --bins
138           Benchmark all binary targets.
139
140       --example name...
141           Benchmark the specified example. This flag may be specified
142           multiple times and supports common Unix glob patterns.
143
144       --examples
145           Benchmark all example targets.
146
147       --test name...
148           Benchmark the specified integration test. This flag may be
149           specified multiple times and supports common Unix glob patterns.
150
151       --tests
152           Benchmark all targets in test mode that have the test = true
153           manifest flag set. By default this includes the library and
154           binaries built as unittests, and integration tests. Be aware that
155           this will also build any required dependencies, so the lib target
156           may be built twice (once as a unittest, and once as a dependency
157           for binaries, integration tests, etc.). Targets may be enabled or
158           disabled by setting the test flag in the manifest settings for the
159           target.
160
161       --bench name...
162           Benchmark the specified benchmark. This flag may be specified
163           multiple times and supports common Unix glob patterns.
164
165       --benches
166           Benchmark all targets in benchmark mode that have the bench = true
167           manifest flag set. By default this includes the library and
168           binaries built as benchmarks, and bench targets. Be aware that this
169           will also build any required dependencies, so the lib target may be
170           built twice (once as a benchmark, and once as a dependency for
171           binaries, benchmarks, etc.). Targets may be enabled or disabled by
172           setting the bench flag in the manifest settings for the target.
173
174       --all-targets
175           Benchmark all targets. This is equivalent to specifying --lib
176           --bins --tests --benches --examples.
177
178   Feature Selection
179       The feature flags allow you to control which features are enabled. When
180       no feature options are given, the default feature is activated for
181       every selected package.
182
183       See the features documentation
184       <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options>
185       for more details.
186
187       -F features, --features features
188           Space or comma separated list of features to activate. Features of
189           workspace members may be enabled with package-name/feature-name
190           syntax. This flag may be specified multiple times, which enables
191           all specified features.
192
193       --all-features
194           Activate all available features of all selected packages.
195
196       --no-default-features
197           Do not activate the default feature of the selected packages.
198
199   Compilation Options
200       --target triple
201           Benchmark for the given architecture. The default is the host
202           architecture. The general format of the triple is
203           <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for
204           a list of supported targets.
205
206           This may also be specified with the build.target config value
207           <https://doc.rust-lang.org/cargo/reference/config.html>.
208
209           Note that specifying this flag makes Cargo run in a different mode
210           where the target artifacts are placed in a separate directory. See
211           the build cache
212           <https://doc.rust-lang.org/cargo/guide/build-cache.html>
213           documentation for more details.
214
215       --profile name
216           Benchmark with the given profile. See the the reference
217           <https://doc.rust-lang.org/cargo/reference/profiles.html> for more
218           details on profiles.
219
220       --ignore-rust-version
221           Benchmark the target even if the selected Rust compiler is older
222           than the required Rust version as configured in the project's
223           rust-version field.
224
225       --timings=fmts
226           Output information how long each compilation takes, and track
227           concurrency information over time. Accepts an optional
228           comma-separated list of output formats; --timings without an
229           argument will default to --timings=html. Specifying an output
230           format (rather than the default) is unstable and requires
231           -Zunstable-options. Valid output formats:
232
233html: Write a human-readable file cargo-timing.html to the
234               target/cargo-timings directory with a report of the
235               compilation. Also write a report to the same directory with a
236               timestamp in the filename if you want to look at older runs.
237               HTML output is suitable for human consumption only, and does
238               not provide machine-readable timing data.
239
240json (unstable, requires -Zunstable-options): Emit
241               machine-readable JSON information about timing information.
242
243   Output Options
244       --target-dir directory
245           Directory for all generated artifacts and intermediate files. May
246           also be specified with the CARGO_TARGET_DIR environment variable,
247           or the build.target-dir config value
248           <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults
249           to target in the root of the workspace.
250
251   Display Options
252       By default the Rust test harness hides output from benchmark execution
253       to keep results readable. Benchmark output can be recovered (e.g., for
254       debugging) by passing --nocapture to the benchmark binaries:
255
256           cargo bench -- --nocapture
257
258       -v, --verbose
259           Use verbose output. May be specified twice for "very verbose"
260           output which includes extra output such as dependency warnings and
261           build script output. May also be specified with the term.verbose
262           config value
263           <https://doc.rust-lang.org/cargo/reference/config.html>.
264
265       -q, --quiet
266           Do not print cargo log messages. May also be specified with the
267           term.quiet config value
268           <https://doc.rust-lang.org/cargo/reference/config.html>.
269
270       --color when
271           Control when colored output is used. Valid values:
272
273auto (default): Automatically detect if color support is
274               available on the terminal.
275
276always: Always display colors.
277
278never: Never display colors.
279
280           May also be specified with the term.color config value
281           <https://doc.rust-lang.org/cargo/reference/config.html>.
282
283       --message-format fmt
284           The output format for diagnostic messages. Can be specified
285           multiple times and consists of comma-separated values. Valid
286           values:
287
288human (default): Display in a human-readable text format.
289               Conflicts with short and json.
290
291short: Emit shorter, human-readable text messages. Conflicts
292               with human and json.
293
294json: Emit JSON messages to stdout. See the reference
295               <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages>
296               for more details. Conflicts with human and short.
297
298json-diagnostic-short: Ensure the rendered field of JSON
299               messages contains the "short" rendering from rustc. Cannot be
300               used with human or short.
301
302json-diagnostic-rendered-ansi: Ensure the rendered field of JSON
303               messages contains embedded ANSI color codes for respecting
304               rustc's default color scheme. Cannot be used with human or
305               short.
306
307json-render-diagnostics: Instruct Cargo to not include rustc
308               diagnostics in in JSON messages printed, but instead Cargo
309               itself should render the JSON diagnostics coming from rustc.
310               Cargo's own JSON diagnostics and others coming from rustc are
311               still emitted. Cannot be used with human or short.
312
313   Manifest Options
314       --manifest-path path
315           Path to the Cargo.toml file. By default, Cargo searches for the
316           Cargo.toml file in the current directory or any parent directory.
317
318       --frozen, --locked
319           Either of these flags requires that the Cargo.lock file is
320           up-to-date. If the lock file is missing, or it needs to be updated,
321           Cargo will exit with an error. The --frozen flag also prevents
322           Cargo from attempting to access the network to determine if it is
323           out-of-date.
324
325           These may be used in environments where you want to assert that the
326           Cargo.lock file is up-to-date (such as a CI build) or want to avoid
327           network access.
328
329       --offline
330           Prevents Cargo from accessing the network for any reason. Without
331           this flag, Cargo will stop with an error if it needs to access the
332           network and the network is not available. With this flag, Cargo
333           will attempt to proceed without the network if possible.
334
335           Beware that this may result in different dependency resolution than
336           online mode. Cargo will restrict itself to crates that are
337           downloaded locally, even if there might be a newer version as
338           indicated in the local copy of the index. See the cargo-fetch(1)
339           command to download dependencies before going offline.
340
341           May also be specified with the net.offline config value
342           <https://doc.rust-lang.org/cargo/reference/config.html>.
343
344   Common Options
345       +toolchain
346           If Cargo has been installed with rustup, and the first argument to
347           cargo begins with +, it will be interpreted as a rustup toolchain
348           name (such as +stable or +nightly). See the rustup documentation
349           <https://rust-lang.github.io/rustup/overrides.html> for more
350           information about how toolchain overrides work.
351
352       -h, --help
353           Prints help information.
354
355       -Z flag
356           Unstable (nightly-only) flags to Cargo. Run cargo -Z help for
357           details.
358
359   Miscellaneous Options
360       The --jobs argument affects the building of the benchmark executable
361       but does not affect how many threads are used when running the
362       benchmarks. The Rust test harness runs benchmarks serially in a single
363       thread.
364
365       -j N, --jobs N
366           Number of parallel jobs to run. May also be specified with the
367           build.jobs config value
368           <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults
369           to the number of CPUs.
370
371       --keep-going
372           Build as many crates in the dependency graph as possible, rather
373           than aborting the build on the first one that fails to build.
374           Unstable, requires -Zunstable-options.
375

ENVIRONMENT

377       See the reference
378       <https://doc.rust-lang.org/cargo/reference/environment-variables.html>
379       for details on environment variables that Cargo reads.
380

EXIT STATUS

3820: Cargo succeeded.
383
384101: Cargo failed to complete.
385

EXAMPLES

387        1. Build and execute all the benchmarks of the current package:
388
389               cargo bench
390
391        2. Run only a specific benchmark within a specific benchmark target:
392
393               cargo bench --bench bench_name -- modname::some_benchmark
394

SEE ALSO

396       cargo(1), cargo-test(1)
397
398
399
400                                                                CARGO-BENCH(1)
Impressum