bencher (libtest) compatibility layer documentation

A compatibility layer for bencher, a port of the unstable libtest benchmarking framework

Overview

codspeed-bencher-compat is a Bencher compatibility layer for CodSpeed that allows seamless integration of Rust’s built-in benchmarking framework with CodSpeed performance measurement.

This crate acts as a drop-in replacement for the standard bencher crate, maintaining your existing benchmark code while enabling CodSpeed integration.

Bencher is a port of the unstable libtest benchmarking framework. It is not recommended for new projects, consider using Divan for new projects as it offers better ergonomics and features.

Installation

Install the compatibility layer and rename it to bencher to maintain compatibility with existing code:

cargo add --dev codspeed-bencher-compat --rename bencher

This will install the codspeed-bencher-compat crate and rename it to bencher in your Cargo.toml. This way, you can keep your existing imports and the compatibility layer will take care of the rest.

Using the compatibility layer won’t change the behavior of your benchmark suite and bencher will still run it as usual.

If you prefer, you can also install codspeed-bencher-compat as is and change your imports to use this new crate name.

Usage

Let’s start with the example from the Bencher documentation, creating a benchmark suite for 2 simple functions (in benches/example.rs):

use bencher::{benchmark_group, benchmark_main, Bencher};

fn a(bench: &mut Bencher) {
    bench.iter(|| {
        (0..1000).fold(0, |x, y| x + y)
    })
}

fn b(bench: &mut Bencher) {
    const N: usize = 1024;
    bench.iter(|| {
        vec![0u8; N]
    });

    bench.bytes = N as u64;
}

benchmark_group!(benches, a, b);
benchmark_main!(benches);

The last step in creating the Bencher benchmark is to add the new benchmark target in your Cargo.toml:

Cargo.toml

[[bench]]
name = "example"
harness = false

And that’s it! You can now run your benchmark suite with CodSpeed:

terminal

$ cargo codspeed build
    Finished release [optimized] target(s) in 0.12s
    Finished built 1 benchmark suite(s)

$ cargo codspeed run
   Collected 1 benchmark suite(s) to run
     Running example
Using codspeed-bencher-compat v1.0.0 compatibility layer
NOTICE: codspeed is enabled, but no performance measurement will
be made since it's running in an unknown environment.
Checked: benches/example.rs::a (group: benches)
Checked: benches/example.rs::b (group: benches)
        Done running bencher_example
    Finished running 1 benchmark suite(s)

Resources

• Official bencher documentation
• Official bencher GitHub repository