divan compatibility layer documentation

A compatibility layer for divan

Overview

codspeed-divan-compat is a Divan compatibility layer for CodSpeed that allows seamless integration of Divan benchmarks with CodSpeed performance measurement.

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

Divan is the recommended benchmarking framework for Rust when using CodSpeed due to its modern design and excellent performance characteristics.

Installation

cargo add --dev codspeed-divan-compat --rename divan

This will install the codspeed-divan-compat crate and rename it to divan 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 divan will still run it as usual.

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

Usage

Let’s start with the example from the divan documentation, creating a benchmark suite for the Fibonacci function (in benches/my_benchmark.rs):

fn main() {
    // Run registered benchmarks.
    divan::main();
}

// Register a `fibonacci` function and benchmark it over multiple cases.
#[divan::bench(args = [1, 2, 4, 8, 16, 32])]
fn fibonacci(n: u64) -> u64 {
    if n <= 1 {
        1
    } else {
        fibonacci(n - 2) + fibonacci(n - 1)
    }
}

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

Cargo.toml

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

And that’s it! You can now run your benchmark suite with cargo-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 my_benchmark
NOTICE: codspeed is enabled, but no performance measurement will be made since it's running in an unknown environment.
Checked: benches/my_benchmark.rs::fibonacci[1]
Checked: benches/my_benchmark.rs::fibonacci[2]
Checked: benches/my_benchmark.rs::fibonacci[4]
Checked: benches/my_benchmark.rs::fibonacci[8]
Checked: benches/my_benchmark.rs::fibonacci[16]
Checked: benches/my_benchmark.rs::fibonacci[32]
Done running my_benchmark
Finished running 1 benchmark suite(s)

Compatibility

Not (yet) supported

• divan::bench(crate = xxx): due to how the compatibility layer works internally, we do not plan to support this feature.
• divan::bench_group: we do not support benchmark grouping yet, if you need it don’t hesitate to create an issue.

Resources

• Official divan documentation
• Official divan GitHub repository