Installation guide for rr
=========================


A) Hardware/Software requirements
---------------------------------

The current version of rr requires a Linux kernel version 2.6.39 and larger.
To enable PEBS support for the hardware performance counters (HPC) a kernel
version >= 3.0 is required. Furthermore, rr does not support x86_64. rr was
developed under Ubuntu 11.04.

rr requires two additional libraries:

(1) libpfm-4.1.0: The library can be downloaded from:
http://sourceforge.net/projects/perfmon2/files/libpfm4/libpfm-4.1.0.tar.gz/download

(2) libdisasm-dev



B) Building 
-----------

rr is developed with Eclipse CDT plugin. You can import the project directly into
Eclipse. Eclipse then generates a makefile which you can use to build the project.


C) Usage
--------

Before calling either the recorder or the replayer make sure that address space
randomization is disabled. You can do this by e.g., with the following command:

sysctl -w kernel.randomize_va_space=0


Typing rr --record /path/to/binary invokes the recorder. The recorder
creates a path in the current directory which contains the trace file(s).
To replay the application, type rr --replay /path/to/trace. The checks the 
replayed execution corresponds to the recorded execution are quite rigorous
at the moment. This is why the '/path/to/binary' should have the exact length
as '/path/to/trace'. You can do this easily by creating a symbolic link with
the appropriate length. Pretty hacky :-)
 
Note that talking to particular kernel drivers (by ioctl(...)) requires the
rr to have knowledge about what the driver is doing. For example, if you
record GUI applications that make use a grapphics driver with 3d-support
rr will fail.