A light wrapper around rr, the time-travelling debugger.
Do you find yourself running the same test over and over in the debugger, trying to figure out how the code got in a bad state? We have a tool for you! Easy to install and setup, it will record an execution trace, and that gives magical new powers to gdb. Step backwards, run backwards, see where variables changed their value or when a function was last called on an object (using conditional breakpoints). (source)
Suppose we ran a test my_test and got a failure. We first re-run the test under rr
to record the entire execution (including everything else on your system the test
interacts with).
```bash
cargo rr test my_test
thread 'main' panicked at 'assertion failed: (left == right)
left: 1,
right: 2', tests/tests.rs:100
test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 2 filtered out; finished in 0.06s ```
Let's replay the recording.
```bash
cargo rr replay
(rr) continue
thread 'main' panicked at 'assertion failed: (left == right)
left: 1,
right: 42', tests/tests.rs:100
test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 2 filtered out; finished in 0.06s ```
We'll go backwards until we return to the failed assertion so we can have a look at a and b.
```bash (rr) break tests/tests.rs:100 (rr) reverse-continue Continuing.
Breakpoint 1, tests::main () at tests/tests.rs:100 100 assert_eq!(a, b);
(rr) print a $1 = 1
(rr) print b $2 = 42 ```
I wonder where a is set to 1?
```bash (rr) watch -l a (rr) reverse-continue
Old value = 1 New value = -1992923200 0x000055dcac485ed9 in tests::main () at tests/tests.rs:30 30 let a = some_calculation();
```
Note that since we're going in reverse the old and new values are backwards.
-1992923200 is whatever used to be at the address 0x000055dcac485ed9
before it was used for a.
cargo-rr is a custom cargo subcommand. It can be installed
by installing the cargo-rr package from crates.io: just run
bash
cargo install cargo-rr
in a terminal. After installing you can run cargo rr in the terminal to access cargo-rr.
Run cargo rr test or cargo rr run with any options you'd normally give to cargo test or cargo run. For example, you might run cargo rr test --test my_integration_test some_filter.
Once you've made a recording you can replay the last recording in a debugger with cargo rr replay.
You can pass options to rr by putting them after the separater --. If you do so, you are responsible for making sure the options you set don't conflict with the options cargo-rr sets for you. In general, you should be fine if you avoid customizing where traces go or what they're named. Please file a bug if you run into a conflict so I can add the option you want to cargo-rr.
cargo rr test and cargo rr run call rr record under the hood, so you can see the full list of rr options by running rr record -h. For example, cargo rr test --test my_test -- --chaos runs the tests under chaos mode, which randomizes scheduling decisions to try to surface concurrency bugs.
cargo rr replay calls rr replay under the hood, so you can see the full list of rr options by running rr replay -h. For example, rr replay -- --stats=10000 displays brief stats every 10,000 steps.
Run cargo rr help to see the full usage.