<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>src/doc/man/cargo-bench.md - fork/cargo @ 0.87.0</title>
<meta name="description" content="src/doc/man/cargo-bench.md in fork/cargo at 0.87.0.">
<meta property="og:title" content="src/doc/man/cargo-bench.md - fork/cargo @ 0.87.0">
<meta property="og:description" content="src/doc/man/cargo-bench.md in fork/cargo at 0.87.0.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="git.julia.blue">
<link rel="stylesheet" href="/css/style.css?v=62">
<script type="module" src="/js/main.js?v=62"></script>
</head>
<body>
<main data-ref="0.87.0" data-tip="adf9b6ad14cfa10ff680d5806741a144f7163698">
<noscript>
  <div class="callout">
    <p>
      hey! this is a static git repo viewer. commit diffs, file history,
      older commits and other revisions won't load without javascript.
    </p>
    <p>
      you are still able to view source files on branch/tag tips,
      but the experience is degraded.
    </p>
  </div>
</noscript>
<header class="repo"><div>
<h1>fork/cargo</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/cargo</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">bors</span><span class="commit-message" data-commit="3293d22f009b1de2b0a6245e7a6adee6d877e01c">Auto merge of #14326 - Ifropc:5707-lock-path, r=weihanglo</span><span class="snapshot-sha sha" data-commit="3293d22f009b1de2b0a6245e7a6adee6d877e01c">3293d22f0</span><time datetime="2024-08-16T14:38:39+00:00" title="2024-08-16 14:38:39 +0000">2024-08-16</time></p>
<header class="topbar"><details class="switcher"><summary>0.87.0</summary><div class="menu"><strong>branches</strong><a href="/fork/cargo/ref/master/">master</a><strong>tags</strong><a class="current" href="/fork/cargo/ref/0.87.0/">0.87.0</a><a href="/fork/cargo/ref/0.88.0/">0.88.0</a><a href="/fork/cargo/ref/0.89.0/">0.89.0</a><a href="/fork/cargo/ref/0.90.0/">0.90.0</a><a href="/fork/cargo/ref/0.91.0/">0.91.0</a><a href="/fork/cargo/ref/0.92.0/">0.92.0</a><a href="/fork/cargo/ref/0.93.0/">0.93.0</a><a href="/fork/cargo/ref/home-0.5.12/">home-0.5.12</a><a class="all" href="/fork/cargo/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/cargo/">cargo</a> / <a href="/fork/cargo/ref/0.87.0/tree/src/">src</a> / <a href="/fork/cargo/ref/0.87.0/tree/src/doc/">doc</a> / <a href="/fork/cargo/ref/0.87.0/tree/src/doc/man/">man</a> / <span class="cur">cargo-bench.md</span></nav>
<span class="view-stats"><span>5.5 KiB</span><span>188 lines</span></span><span class="actions"><a class="raw" href="/fork/cargo/raw/9e8ce249074b6ec7d9b0af246267e89710220309/src/doc/man/cargo-bench.md">raw</a></span></header>
<div class="markdown-view"><input type="radio" name="markdown-view" id="markdown-rendered" checked><label for="markdown-rendered">rendered</label><input type="radio" name="markdown-view" id="markdown-code"><label for="markdown-code">code</label><section class="readme rendered"><h1>cargo-bench(1)</h1>
<p>{{<del>*set command="bench"}}
{{</del>*set actionverb="Benchmark"}}
{{<del>*set nouns="benchmarks"}}
{{</del>*set multitarget=true}}</p>
<h2>NAME</h2>
<p>cargo-bench --- Execute benchmarks of a package</p>
<h2>SYNOPSIS</h2>
<p><code>cargo bench</code> [<em>options</em>] [<em>benchname</em>] [<code>--</code> <em>bench-options</em>]</p>
<h2>DESCRIPTION</h2>
<p>Compile and execute benchmarks.</p>
<p>The benchmark filtering argument <em>benchname</em> and all the arguments following
the two dashes (<code>--</code>) are passed to the benchmark binaries and thus to
<em>libtest</em> (rustc's built in unit-test and micro-benchmarking framework). If
you are passing arguments to both Cargo and the binary, the ones after <code>--</code> go
to the binary, the ones before go to Cargo. For details about libtest's
arguments see the output of <code>cargo bench -- --help</code> and check out the rustc
book's chapter on how tests work at
<a href="https://doc.rust-lang.org/rustc/tests/index.html">https://doc.rust-lang.org/rustc/tests/index.html</a>.</p>
<p>As an example, this will run only the benchmark named <code>foo</code> (and skip other
similarly named benchmarks like <code>foobar</code>):</p>
<pre><code>cargo bench -- foo --exact
</code></pre>
<p>Benchmarks are built with the <code>--test</code> option to <code>rustc</code> which creates a
special executable by linking your code with libtest. The executable
automatically runs all functions annotated with the <code>#[bench]</code> attribute.
Cargo passes the <code>--bench</code> flag to the test harness to tell it to run
only benchmarks, regardless of whether the harness is libtest or a custom harness.</p>
<p>The libtest harness may be disabled by setting <code>harness = false</code> in the target
manifest settings, in which case your code will need to provide its own <code>main</code>
function to handle running benchmarks.</p>
<blockquote>
<p><strong>Note</strong>: The
<a href="https://doc.rust-lang.org/nightly/unstable-book/library-features/test.html"><code>#[bench]</code> attribute</a>
is currently unstable and only available on the
<a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly channel</a>.
There are some packages available on
<a href="https://crates.io/keywords/benchmark">crates.io</a> that may help with
running benchmarks on the stable channel, such as
<a href="https://crates.io/crates/criterion">Criterion</a>.</p>
</blockquote>
<p>By default, <code>cargo bench</code> uses the <a href="../reference/profiles.html#bench"><code>bench</code> profile</a>, which enables
optimizations and disables debugging information. If you need to debug a
benchmark, you can use the <code>--profile=dev</code> command-line option to switch to
the dev profile. You can then run the debug-enabled benchmark within a
debugger.</p>
<h3>Working directory of benchmarks</h3>
<p>The working directory of every benchmark is set to the root directory of the
package the benchmark belongs to.
Setting the working directory of benchmarks to the package's root directory
makes it possible for benchmarks to reliably access the package's files using
relative paths, regardless from where <code>cargo bench</code> was executed from.</p>
<h2>OPTIONS</h2>
<h3>Benchmark Options</h3>
<p>{{&gt; options-test }}</p>
<p>{{&gt; section-package-selection }}</p>
<h3>Target Selection</h3>
<p>When no target selection options are given, <code>cargo bench</code> will build the
following targets of the selected packages:</p>
<ul>
<li>lib --- used to link with binaries and benchmarks</li>
<li>bins (only if benchmark targets are built and required features are
available)</li>
<li>lib as a benchmark</li>
<li>bins as benchmarks</li>
<li>benchmark targets</li>
</ul>
<p>The default behavior can be changed by setting the <code>bench</code> flag for the target
in the manifest settings. Setting examples to <code>bench = true</code> will build and
run the example as a benchmark, replacing the example's <code>main</code> function with
the libtest harness.</p>
<p>Setting targets to <code>bench = false</code> will stop them from being benchmarked by
default. Target selection options that take a target by name (such as
<code>--example foo</code>) ignore the <code>bench</code> flag and will always benchmark the given
target.</p>
<p>See <a href="../reference/cargo-targets.html#configuring-a-target">Configuring a target</a>
for more information on per-target settings.</p>
<p>{{&gt; options-targets-bin-auto-built }}</p>
<p>{{&gt; options-targets }}</p>
<p>{{&gt; section-features }}</p>
<h3>Compilation Options</h3>
<p>{{#options}}</p>
<p>{{&gt; options-target-triple }}</p>
<p>{{&gt; options-profile }}</p>
<p>{{&gt; options-timings }}</p>
<p>{{/options}}</p>
<h3>Output Options</h3>
<p>{{#options}}
{{&gt; options-target-dir }}
{{/options}}</p>
<h3>Display Options</h3>
<p>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 <code>--nocapture</code> to the benchmark binaries:</p>
<pre><code>cargo bench -- --nocapture
</code></pre>
<p>{{#options}}</p>
<p>{{&gt; options-display }}</p>
<p>{{&gt; options-message-format }}</p>
<p>{{/options}}</p>
<h3>Manifest Options</h3>
<p>{{#options}}
{{&gt; options-manifest-path }}</p>
<p>{{&gt; options-ignore-rust-version }}</p>
<p>{{&gt; options-locked }}</p>
<p>{{&gt; options-lockfile-path }}
{{/options}}</p>
<p>{{&gt; section-options-common }}</p>
<h3>Miscellaneous Options</h3>
<p>The <code>--jobs</code> 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.</p>
<p>{{#options}}
{{&gt; options-jobs }}
{{/options}}</p>
<p>While <code>cargo bench</code> involves compilation, it does not provide a <code>--keep-going</code>
flag. Use <code>--no-fail-fast</code> to run as many benchmarks as possible without
stopping at the first failure. To "compile" as many benchmarks as possible, use
<code>--benches</code> to build benchmark binaries separately. For example:</p>
<pre><code>cargo build --benches --release --keep-going
cargo bench --no-fail-fast
</code></pre>
<p>{{&gt; section-environment }}</p>
<p>{{&gt; section-exit-status }}</p>
<h2>EXAMPLES</h2>
<ol>
<li>
<p>Build and execute all the benchmarks of the current package:</p>
<pre><code>cargo bench
</code></pre>
</li>
<li>
<p>Run only a specific benchmark within a specific benchmark target:</p>
<pre><code>cargo bench --bench bench_name -- modname::some_benchmark
</code></pre>
</li>
</ol>
<h2>SEE ALSO</h2>
<p>{{man "cargo" 1}}, {{man "cargo-test" 1}}</p>
</section><div class="code-panel"><pre class="code src language-markdown"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text"><a-p>#</a-p> <a-tt>cargo-bench(1)</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text">{{~*set command=&quot;bench&quot;}}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text">{{~*set actionverb=&quot;Benchmark&quot;}}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text">{{~*set nouns=&quot;benchmarks&quot;}}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text">{{~*set multitarget=true}}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text"><a-p>##</a-p> <a-tt>NAME</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text">cargo-bench --- Execute benchmarks of a package</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text"><a-p>##</a-p> <a-tt>SYNOPSIS</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text">`cargo bench` [_options_] [_benchname_] [`--` _bench-options_]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text"><a-p>##</a-p> <a-tt>DESCRIPTION</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text">Compile and execute benchmarks.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text">The benchmark filtering argument _benchname_ and all the arguments following</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text">the two dashes (`--`) are passed to the benchmark binaries and thus to</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text">_libtest_ (rustc&#39;s built in unit-test and micro-benchmarking framework). If</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text">you are passing arguments to both Cargo and the binary, the ones after `--` go</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text">to the binary, the ones before go to Cargo. For details about libtest&#39;s</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text">arguments see the output of `cargo bench -- --help` and check out the rustc</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text">book&#39;s chapter on how tests work at</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text">&lt;https://doc.rust-lang.org/rustc/tests/index.html&gt;.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text">As an example, this will run only the benchmark named `foo` (and skip other</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text">similarly named benchmarks like `foobar`):</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text"><a-tl>    cargo bench -- foo --exact</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text">Benchmarks are built with the `--test` option to `rustc` which creates a</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text">special executable by linking your code with libtest. The executable</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text">automatically runs all functions annotated with the `#[bench]` attribute.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text">Cargo passes the `--bench` flag to the test harness to tell it to run</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L37" href="#L37">37</a><span class="code-text">only benchmarks, regardless of whether the harness is libtest or a custom harness.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L38" href="#L38">38</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L39" href="#L39">39</a><span class="code-text">The libtest harness may be disabled by setting `harness = false` in the target</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L40" href="#L40">40</a><span class="code-text">manifest settings, in which case your code will need to provide its own `main`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</a><span class="code-text">function to handle running benchmarks.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L42" href="#L42">42</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L43" href="#L43">43</a><span class="code-text"><a-p>&gt; </a-p>**Note**: The</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L44" href="#L44">44</a><span class="code-text"><a-p>&gt; </a-p>[`#[bench]` attribute](https://doc.rust-lang.org/nightly/unstable-book/library-features/test.html)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L45" href="#L45">45</a><span class="code-text"><a-p>&gt; </a-p>is currently unstable and only available on the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L46" href="#L46">46</a><span class="code-text"><a-p>&gt; </a-p>[nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L47" href="#L47">47</a><span class="code-text"><a-p>&gt; </a-p>There are some packages available on</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L48" href="#L48">48</a><span class="code-text"><a-p>&gt; </a-p>[crates.io](https://crates.io/keywords/benchmark) that may help with</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L49" href="#L49">49</a><span class="code-text"><a-p>&gt; </a-p>running benchmarks on the stable channel, such as</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L50" href="#L50">50</a><span class="code-text"><a-p>&gt; </a-p>[Criterion](https://crates.io/crates/criterion).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L51" href="#L51">51</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L52" href="#L52">52</a><span class="code-text">By default, `cargo bench` uses the [`bench` profile], which enables</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L53" href="#L53">53</a><span class="code-text">optimizations and disables debugging information. If you need to debug a</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L54" href="#L54">54</a><span class="code-text">benchmark, you can use the `--profile=dev` command-line option to switch to</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L55" href="#L55">55</a><span class="code-text">the dev profile. You can then run the debug-enabled benchmark within a</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L56" href="#L56">56</a><span class="code-text">debugger.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L57" href="#L57">57</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L58" href="#L58">58</a><span class="code-text"><a-tu>[`bench` profile]</a-tu>: <a-tu>../reference/profiles.html#bench</a-tu></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L59" href="#L59">59</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L60" href="#L60">60</a><span class="code-text"><a-p>###</a-p> <a-tt>Working directory of benchmarks</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L61" href="#L61">61</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L62" href="#L62">62</a><span class="code-text">The working directory of every benchmark is set to the root directory of the </span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L63" href="#L63">63</a><span class="code-text">package the benchmark belongs to.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L64" href="#L64">64</a><span class="code-text">Setting the working directory of benchmarks to the package&#39;s root directory </span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L65" href="#L65">65</a><span class="code-text">makes it possible for benchmarks to reliably access the package&#39;s files using </span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L66" href="#L66">66</a><span class="code-text">relative paths, regardless from where `cargo bench` was executed from.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L67" href="#L67">67</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L68" href="#L68">68</a><span class="code-text"><a-p>##</a-p> <a-tt>OPTIONS</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L69" href="#L69">69</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L70" href="#L70">70</a><span class="code-text"><a-p>###</a-p> <a-tt>Benchmark Options</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L71" href="#L71">71</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L72" href="#L72">72</a><span class="code-text">{{&gt; options-test }}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L73" href="#L73">73</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L74" href="#L74">74</a><span class="code-text">{{&gt; section-package-selection }}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L75" href="#L75">75</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L76" href="#L76">76</a><span class="code-text"><a-p>###</a-p> <a-tt>Target Selection</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L77" href="#L77">77</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L78" href="#L78">78</a><span class="code-text">When no target selection options are given, `cargo bench` will build the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L79" href="#L79">79</a><span class="code-text">following targets of the selected packages:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L80" href="#L80">80</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L81" href="#L81">81</a><span class="code-text"><a-p>- </a-p>lib --- used to link with binaries and benchmarks</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L82" href="#L82">82</a><span class="code-text"><a-p>- </a-p>bins (only if benchmark targets are built and required features are</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L83" href="#L83">83</a><span class="code-text"><a-p>  </a-p>available)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L84" href="#L84">84</a><span class="code-text"><a-p>- </a-p>lib as a benchmark</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L85" href="#L85">85</a><span class="code-text"><a-p>- </a-p>bins as benchmarks</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L86" href="#L86">86</a><span class="code-text"><a-p>- </a-p>benchmark targets</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L87" href="#L87">87</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L88" href="#L88">88</a><span class="code-text"><a-p>The default behavior can be changed by setting the `bench` flag for the target</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L89" href="#L89">89</a><span class="code-text"><a-p>in the manifest settings. Setting examples to `bench = true` will build and</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L90" href="#L90">90</a><span class="code-text"><a-p>run the example as a benchmark, replacing the example&#39;s `main` function with</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L91" href="#L91">91</a><span class="code-text"><a-p>the libtest harness.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L92" href="#L92">92</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L93" href="#L93">93</a><span class="code-text"><a-p>Setting targets to `bench = false` will stop them from being benchmarked by</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L94" href="#L94">94</a><span class="code-text"><a-p>default. Target selection options that take a target by name (such as</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L95" href="#L95">95</a><span class="code-text"><a-p>`--example foo`) ignore the `bench` flag and will always benchmark the given</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L96" href="#L96">96</a><span class="code-text"><a-p>target.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L97" href="#L97">97</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L98" href="#L98">98</a><span class="code-text"><a-p>See [Configuring a target](../reference/cargo-targets.html#configuring-a-target)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L99" href="#L99">99</a><span class="code-text"><a-p>for more information on per-target settings.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L100" href="#L100">100</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L101" href="#L101">101</a><span class="code-text"><a-p>{{&gt; options-targets-bin-auto-built }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L102" href="#L102">102</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L103" href="#L103">103</a><span class="code-text"><a-p>{{&gt; options-targets }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L104" href="#L104">104</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L105" href="#L105">105</a><span class="code-text"><a-p>{{&gt; section-features }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L106" href="#L106">106</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L107" href="#L107">107</a><span class="code-text"><a-p>### </a-p><a-tt>Compilation Options</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L108" href="#L108">108</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L109" href="#L109">109</a><span class="code-text"><a-p>{{#options}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L110" href="#L110">110</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L111" href="#L111">111</a><span class="code-text"><a-p>{{&gt; options-target-triple }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L112" href="#L112">112</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L113" href="#L113">113</a><span class="code-text"><a-p>{{&gt; options-profile }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L114" href="#L114">114</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L115" href="#L115">115</a><span class="code-text"><a-p>{{&gt; options-timings }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L116" href="#L116">116</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L117" href="#L117">117</a><span class="code-text"><a-p>{{/options}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L118" href="#L118">118</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L119" href="#L119">119</a><span class="code-text"><a-p>### </a-p><a-tt>Output Options</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L120" href="#L120">120</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L121" href="#L121">121</a><span class="code-text"><a-p>{{#options}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L122" href="#L122">122</a><span class="code-text"><a-p>{{&gt; options-target-dir }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L123" href="#L123">123</a><span class="code-text"><a-p>{{/options}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L124" href="#L124">124</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L125" href="#L125">125</a><span class="code-text"><a-p>### </a-p><a-tt>Display Options</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L126" href="#L126">126</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L127" href="#L127">127</a><span class="code-text"><a-p>By default the Rust test harness hides output from benchmark execution to keep</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L128" href="#L128">128</a><span class="code-text"><a-p>results readable. Benchmark output can be recovered (e.g., for debugging) by</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L129" href="#L129">129</a><span class="code-text"><a-p>passing `--nocapture` to the benchmark binaries:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L130" href="#L130">130</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L131" href="#L131">131</a><span class="code-text"><a-tl>    cargo bench -- --nocapture</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L132" href="#L132">132</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L133" href="#L133">133</a><span class="code-text"><a-p>{{#options}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L134" href="#L134">134</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L135" href="#L135">135</a><span class="code-text"><a-p>{{&gt; options-display }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L136" href="#L136">136</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L137" href="#L137">137</a><span class="code-text"><a-p>{{&gt; options-message-format }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L138" href="#L138">138</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L139" href="#L139">139</a><span class="code-text"><a-p>{{/options}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L140" href="#L140">140</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L141" href="#L141">141</a><span class="code-text"><a-p>### </a-p><a-tt>Manifest Options</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L142" href="#L142">142</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L143" href="#L143">143</a><span class="code-text"><a-p>{{#options}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L144" href="#L144">144</a><span class="code-text"><a-p>{{&gt; options-manifest-path }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L145" href="#L145">145</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L146" href="#L146">146</a><span class="code-text"><a-p>{{&gt; options-ignore-rust-version }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L147" href="#L147">147</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L148" href="#L148">148</a><span class="code-text"><a-p>{{&gt; options-locked }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L149" href="#L149">149</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L150" href="#L150">150</a><span class="code-text"><a-p>{{&gt; options-lockfile-path }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L151" href="#L151">151</a><span class="code-text"><a-p>{{/options}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L152" href="#L152">152</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L153" href="#L153">153</a><span class="code-text"><a-p>{{&gt; section-options-common }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L154" href="#L154">154</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L155" href="#L155">155</a><span class="code-text"><a-p>### </a-p><a-tt>Miscellaneous Options</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L156" href="#L156">156</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L157" href="#L157">157</a><span class="code-text"><a-p>The `--jobs` argument affects the building of the benchmark executable but</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L158" href="#L158">158</a><span class="code-text"><a-p>does not affect how many threads are used when running the benchmarks. The</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L159" href="#L159">159</a><span class="code-text"><a-p>Rust test harness runs benchmarks serially in a single thread.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L160" href="#L160">160</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L161" href="#L161">161</a><span class="code-text"><a-p>{{#options}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L162" href="#L162">162</a><span class="code-text"><a-p>{{&gt; options-jobs }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L163" href="#L163">163</a><span class="code-text"><a-p>{{/options}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L164" href="#L164">164</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L165" href="#L165">165</a><span class="code-text"><a-p>While `cargo bench` involves compilation, it does not provide a `--keep-going`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L166" href="#L166">166</a><span class="code-text"><a-p>flag. Use `--no-fail-fast` to run as many benchmarks as possible without</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L167" href="#L167">167</a><span class="code-text"><a-p>stopping at the first failure. To &quot;compile&quot; as many benchmarks as possible, use</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L168" href="#L168">168</a><span class="code-text"><a-p>`--benches` to build benchmark binaries separately. For example:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L169" href="#L169">169</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L170" href="#L170">170</a><span class="code-text"><a-tl>    cargo build --benches --release --keep-going</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L171" href="#L171">171</a><span class="code-text"><a-p>    </a-p><a-tl>cargo bench --no-fail-fast</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L172" href="#L172">172</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L173" href="#L173">173</a><span class="code-text"><a-p>{{&gt; section-environment }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L174" href="#L174">174</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L175" href="#L175">175</a><span class="code-text"><a-p>{{&gt; section-exit-status }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L176" href="#L176">176</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L177" href="#L177">177</a><span class="code-text"><a-p>## </a-p><a-tt>EXAMPLES</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L178" href="#L178">178</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L179" href="#L179">179</a><span class="code-text"><a-p>1. Build and execute all the benchmarks of the current package:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L180" href="#L180">180</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L181" href="#L181">181</a><span class="code-text"><a-p>   </a-p><a-tl>    cargo bench</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L182" href="#L182">182</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L183" href="#L183">183</a><span class="code-text"><a-p>2. Run only a specific benchmark within a specific benchmark target:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L184" href="#L184">184</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L185" href="#L185">185</a><span class="code-text"><a-p>   </a-p><a-tl>    cargo bench --bench bench_name -- modname::some_benchmark</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L186" href="#L186">186</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L187" href="#L187">187</a><span class="code-text"><a-p>## </a-p><a-tt>SEE ALSO</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L188" href="#L188">188</a><span class="code-text">{{man &quot;cargo&quot; 1}}, {{man &quot;cargo-test&quot; 1}}</span></span></pre></div></div>
</main>
</body>
</html>
