Prerequisites

In order to use Gungraun, you must have Valgrind installed. This means that Gungraun cannot be used on platforms that are not supported by Valgrind.

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 Valgrind Client Requests shipped with Gungraun, you also need libclang (clang >= 5.0) installed. See also the requirements of bindgen and of cc. It's worth noting that you can use the Valgrind Client Requests of Gungraun without the rest of Gungraun by specifying the client_requests feature and disabling the default features.

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 in Containers

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

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

Gungraun Guide