Overview

See the overview for an introduction to the project.

Requirements

Rust is required for this project. To download Rustup and install Rust:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Build

To build this project:

Checkout main branch from github using git clone.
From top-level directory run cargo build.
- For best profiling specify cargo build --release as cargo will default to debug.

To build a sample program:

```
cargo build -p file-io
```
```
cargo build -p fp-calc
```

Install

To install this project:

With the project repository downloaded, run cargo install --path *ruperf_path* where *ruperf_path* is the path to the ruperf repository on your machine.
For configuration information about cargo install including information about how to specify installation location, etc see documentation
Another option is to build the code using cargo build and then cd into the target directory and select the target.

Run

See ./ruperf --help

Examples:

./ruperf stat -e cycles -e instructions -e task-clock -e L1D-cache-reads ls -a

```
./ruperf test --json
```
```
./ruperf gui
```

See our rustdocs for more documentation by running cargo doc --no-deps --open in the ruperf repository.

Verification

Verification is done through a combination of cargo test, manual inspection comparing output of perf stat with output of ruperf on programs as documented in pull request history, and through inspection of contributor code.

Demo/Walkthrough

Watch our demo video about ruperf on YouTube:

Permissions

This tool uses the perf_event_open() system call, which requires some special permissions. While our tool currently checks if perf_event_paranoid is equal to 0, this is less than ideal is some situations. A way around this is to change the capabilities of the ruperf executable using setcap.

For Linux 5.8+, use CAP_PERFMON; otherwise use CAP_SYSADMIN.

Contributing Guidelines

ruperf is an open source project and is open to recieving contributions!

Please see CONTRIBUTING

Code of Conduct

We are committed to providing a friendly, safe and welcoming environment for all, regardless of level of experience, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, nationality, or other similar characteristic.

Rust Community Code of Conduct