rr is packaged by many Linux distributions, includingUbuntu,Debian,Fedora, andArch. Support for the latest hardware and kernel features may require building rr from Github master.

Fedora

sudo dnf install \  ccache cmake make gcc gcc-c++ gdb lldb libgcc libgcc.i686 \  glibc-devel glibc-devel.i686 libstdc++-devel libstdc++-devel.i686 libstdc++-devel.x86_64 \  python3-pexpect man-pages ninja-build capnproto capnproto-libs capnproto-devel \  zlib-devel libzstd-devel

Debian

sudo apt-get install ccache cmake make g++-multilib gdb lldb \  pkg-config coreutils python3-pexpect manpages-dev git \  ninja-build capnproto libcapnp-dev zlib1g-dev libzstd-dev

Ubuntu

sudo apt-get install ccache cmake make g++-multilib gdb lldb \  pkg-config coreutils python3-pexpect manpages-dev git \  ninja-build capnproto libcapnp-dev zlib1g-dev libzstd-dev

On some old distros such as Ubuntu 14.04libcapnp-dev doesn't includecapnp.pc. To build rr on such distros, manually installcapnproto usingthe instructions here. You may need to accommodatepkg-config for your distro (e.g. by setting thePKG_CONFIG_PATH when invokingcmake); seeissue rr#2697 for more discussion.

rr uses the CMake build system, which is able to generate multiple build environments. This enables you to choose whichever build driver you prefer to use. The commands below show building rr in a separateobj directory. This is recommended becausecmake generates alot of auxiliary files. A fully optimized rr build requires the CMake parameter-DCMAKE_BUILD_TYPE=Release. If you intend to work on rr this can be omitted, alternatively you can use-DCMAKE_BUILD_TYPE=RelWithDebInfo if you want optimizations and debug info.:

git clone https://github.com/rr-debugger/rr.gitmkdir obj&&cd obj&& cmake -DCMAKE_BUILD_TYPE=Release ../rr

Then to usemake and the system default compiler to build:

make -j8sudo make install

Or to use clang and Ninja to build (faster!):

CC=clang CXX=clang++ cmake -G Ninja -DCMAKE_BUILD_TYPE=Release ../rrcmake --build.sudo cmake --build. --target install

RHEL7/CentOS7 with EPEL requires installingpython36-pexpect and runningcmake3;it will only work with anupdated kernel.

To use Eclipse:

mkdir obj&&cd objcmake -G"Eclipse CDT4 - Unix Makefiles" -DCMAKE_BUILD_TYPE=Release ../rr

Next, import the project into Eclipse. By default Eclipse will automatically build the project when files change. You can force Eclipse to rebuild the project by pressing Ctrl-B.

PaX kernel:

If your kernel is a PaX kernel (if these words don't mean anything to you, you can skip this paragraph), then you will need to disableMPROTECT on the built filesbin/rr,bin/rr_exec_stub andbin/rr_exec_stub_32.

If you use PT header flags, for example, you should run:

paxctl -cm bin/rr bin/rr_exec_stub bin/rr_exec_stub_32

in your build directory.

For a quick check:Will rr work on my system?

Supported CPUs are:

• an Intel CPU withNehalem (2010) or later microarchitecture
• certain AMD Zen or later processors (seehttps://github.com/rr-debugger/rr/wiki/Zen)
• certain AArch64 microarchitectures (e.g. ARM Neoverse N1 or the Apple Silicon M-series)

Note that you may have to pin the testsuite / your programs to specific cores, e.g.taskset -c 0; seeissue rr#3338 for more discussion.

Linux kernel 4.7 or higher is required (check withuname -r). rr 5.6.0 worked with kernel 3.11.

/proc/sys/kernel/perf_event_paranoid must be <= 1 for rr to work efficiently (i.e. be able to useperf counters). Some distros set it to 2 or higher, in which case you either need to set it to 1 or userr record -n, which is slow. Temporarily change the setting by running

$ sudo sysctl kernel.perf_event_paranoid=1

Apply the setup automatically on startup by running

# echo 'kernel.perf_event_paranoid=1' | sudo tee '/etc/sysctl.d/51-enable-perf-events.conf'

If you run rr in a virtual machine,MAKE SURE VIRTUALIZATION OF PERF COUNTERS IS ENABLED. Virtual machines that work with rr and the settings required are listed below.

• VMWare Workstation/Fusion (Windows):
  • The default is for counter virtualization to bedisabled. You have to enable it in the VM settings (advanced processor options).
  • Set the Preferred virtualization engine in the Advanced tab to Intel VT-x with EPT (it may default to Automatic).
  • Enable the code profiling applications in the Processors & Memory tab.
  • Addmonitor_control.disable_hvsim_clusters = true to the VM's.vmx file (more information).
• Qemu: On QEMU command line use

  -cpu host

• Libvirt/KVM: Specify CPU passthrough in domain XML definition:

  <cpu mode='host-passthrough'/>

• Hyper-V: Run the PowerShell commandSet-VMProcessor MyVMName -Perfmon @("pmu")

VirtualBoxdoes not work at this time because it doesn't support PMU virtualization. It would be great if someone contributed that to the open-source project...

Xen's PMU virtualization hasbugs that prevent rr from working.

Apparently VMWare on MacOS Big Sur and later does not support performance counter virtualization, and therefore does not support rr. No other virtualization on Mac does either.

Some Digital Ocean instances have worked in the past.

Amazon EC2 instance typesc5[d].9xlarge,c5[d].18xlarge,m5[d].12xlarge, andm5[d].24xlarge should work. All bare metal instance types should work. Some other instance types may work (those that use the "Nitro" hypervisor and where the instance occupies a whole CPU socket).

Make sure rr works on the machine outside of Docker, then follow theDocker-specific instructions.

If rr isn't working at all, rundmesg|grep PMU. If you get output like

[    0.311273] Performance Events: Fam15h core perfctr, Broken PMU hardware detected, using software events only.[    0.311279] Failed to access perfctr msr (MSR c0010201 is 25c6c8c489)

then something is disabled in your BIOS, or perhaps you have a broken hardware configuration, or you're in a VM without PMU virtualization.

Seethis page.

Be sure to read theusage instructions before running tests.

Remember to setperf_event_paranoid to level 1 or lower, because otherwise many tests will fail.
If the tests seem to be hung, then commonly they timed out and/proc/sys/kernel/yama/ptrace_scope is set higher than zero.Consider running the tests as root or temporarily adjusting the level. This isnot needed for general rr usage.Likewise/proc/sys/kernel/apparmor_restrict_unprivileged_userns must be 0 for tests to run correctly, but not for general rr usage.

rr has a suite of tests in$rr/src/test. To run them you first need to enter the build directory, and then, depending on the build system you chose, execute aninja test ormake -j$(nproc) test.

Alternatively, you can run them manually, by callingctest. E.g. with minimal output:

ctest -j$(nproc)

or with full output:

ctest -j$(nproc) -VV

Thevideo_capture test may briefly turn on an attached camera, if you have one --- do not be alarmed!

Easiest way isctest -R test_name. For example:

 $ ctest -R 64bit_child-no-syscallbufTest project /home/constantine/Projects/rr/build    Start 3: 64bit_child-no-syscallbuf1/1 Test #3: 64bit_child-no-syscallbuf ........   Passed    0.62 sec100% tests passed, 0 tests failed out of 1Total Test time (real) =   0.72 sec

This runs tests matching a regular expression. So for example, given testspro-foo,foo,foo-2,foo-3, running actest -r foo will result in all of them running. If you want to run exactly the testsfoo,bar,buzz, but not anything else like afoo-3, you can execute the following:

 $ ctest -R '^(foo|bar|buzz)$'

See alsoman ctest.

Alternatively, each test consists of a C source file and a.run file, which is a shell script. To run an individual basic test outside the harness:

cd$rr/src/testbash basic_test.run$test

To run a non-basic test:

cd$rr/src/testbash$test.run

To run a non-basic test in 32-bit mode:

cd$rr/src/testbash$test.run$test_32

Watch out for a line like171: timeout 120 exceeded. That means a single recording or replaying of a test controlled bytest-monitor took longer than 120 seconds. This can happen if some tests are run at aged hardware.Or the test really got stuck - maybe compare it with the running time of a working git revision or system.

Iftest-monitor hits this timeout it appends a huge amount of information describing the current state of the current processes still running. And following is the attempt to kill the test processes and might lead to a rr crash, which is just caused by gdb inducing theforce_close_record_session into rr being in an bad state for it. The maybe more helpful information is the backtraces that get written before theforce_close_record_session.

Sometime the diagnostic processtest-monitor use to print the status of the process may also hang which causes the whole test run to hang indefinitely. While this behavior may be useful for manually attaching a debugger to identify the problem, the environment variableRR_TEST_DIAGNOSE_TIMEOUT can be used to set a timeout (in seconds) for each of the diagnostic process and allow the whole test suite to proceed.