Running Examples and Benchmarks with Cargo for Rust Projects

When working on Rust projects, managing dependencies, compiling, running tests, and benchmarks is efficiently handled by Cargo, Rust's package manager and build system. In this article, we'll look at how to use Cargo to run examples and benchmarks within your Rust projects to optimize performance and ensure smooth execution.

Running Examples

Examples provide a useful way of demonstrating or testing functionality in a Rust project. They reside in the examples directory in your project and are a great way to give an introduction or specific walkthrough of your project's capabilities.

Creating Example Files

To start, create an examples directory at the root of your project if it doesn't already exist:

mkdir examples

Next, add a new Rust file inside this directory. For instance, you can create a file called example_name.rs:

touch examples/example_name.rs

Within example_name.rs, you can write Rust code that showcases some functionality. Here’s a simple example:

fn main() {
    println!("Hello from the example!");
}

Running an Example

To run your example using Cargo, use the following command:

cargo run --example example_name

This will compile and execute the example_name.rs file, producing output in your terminal.

Running Benchmarks

Benchmarks are a crucial part of performance tuning in Rust projects. The default path for benchmarks is the benches directory in your project.

Setting Up Benchmark Files

Begin by including the following dev-dependencies in your Cargo.toml file:

[dev-dependencies]
criterion = "0.4.0"

Criterion.rs is a popular choice for benchmarks given its capabilities and ease of use.

Create a benches directory in the root of your project:

mkdir benches

Add your first benchmark file, e.g., benchmark_name.rs:

touch benches/benchmark_name.rs

Include the following Rust code as a basic benchmark using Criterion:

use criterion::{criterion_group, criterion_main, Criterion};

fn benchmark_example(c: &mut Criterion) {
    c.bench_function("expensive_calculation", |b| b.iter(|| expensive_calculation()));
}

criterion_group!(benches, benchmark_example);
criterion_main!(benches);

fn expensive_calculation() {
    // Imagine this is some complex computation
    let mut a = 0;
    for i in 1..1000 {
        a += i;
    }
}