Prerequisites

Gungraun requires at least one supported profiling tool for the benchmark target. Valgrind is required for the default Callgrind configuration and the other Valgrind tools. On Linux, Gungraun also supports perf, so a benchmark configured exclusively for perf does not require Valgrind.

If you want to benchmark with perf, Gungraun requires Linux perf version >= 5.9. Its measured-region control uses --control=fd:...,ack, which was added in that release.

Target support and runtime availability are separate. A configured tool must be installed and executable in the environment where the benchmark runs. Perf may also require suitable kernel permissions for the requested events.

The default benchmarking tool is Callgrind and is in most cases perfectly suited to do the job but if you want or need to use Cachegrind instead of Callgrind you require Valgrind version >= 3.22 and client requests (see below).

Debug Symbols

It’s required to run the Gungraun benchmarks with debugging symbols switched on. For example in your ~/.cargo/config or your project’s Cargo.toml:

[profile.bench]
debug = true

Now, all benchmarks which are run with cargo bench include the debug symbols. (See also Cargo Profiles and Cargo Config).

It’s required that settings like strip = true or other configuration options stripping the debug symbols need to be disabled explicitly in the bench profile if you have changed this option for the release profile. For example:

[profile.release]
strip = true

[profile.bench]
debug = true
strip = false

Valgrind Client Requests

If you want to make use of the Valgrind Client Requests which are a re-export of the valgrind-requests package, you also need libclang (clang >= 5.0) installed. See also the requirements of bindgen and of cc.

More details on the usage and requirements of Valgrind Client Requests in this chapter of the guide.

Installation of Valgrind

Gungraun is intentionally independent of a specific version of Valgrind. However, Gungraun was only tested with versions of Valgrind >= 3.20.0. It is therefore highly recommended to use a recent version of Valgrind. Also, if you want or need to, building valgrind from source is usually a straightforward process. Just make sure the valgrind binary is in your $PATH so that Gungraun can find it. See installation in the CI for tips to install Valgrind in the CI.

Installation of Valgrind with Your Package Manager

Alpine Linux

apk add valgrind

Arch Linux

pacman -Sy valgrind

Debian/Ubuntu

apt-get install valgrind

Fedora Linux

dnf install valgrind

FreeBSD

pkg install valgrind

Running Valgrind or perf in Containers

If Valgrind or perf cannot be installed directly on your host system, or you want to customize tool execution in a wrapper, you can use the --tool-runner argument to run the selected tool through a container runtime like Docker or Podman.

For detailed instructions and more examples, see Running Tools with a Custom Runner.

Gungraun Guide