Software and Programmer Efficiency Research Group

Requirements

RDB uses LLDB to control the Jikes RVM process.

On Mac OS X

LLDB framework is installed as part of XCode command line tools installation. To install the XCode command line tools run at the terminal prompt the following command:

xcode-select --install

If the tools have been installed the command will print

xcode-select: error: command line tools are already installed, use "Software Update" to install updates

RDB build expects XCode to be installed in the default location /Applications/Xcode.app/Contents/Developer.

On Linux

LLDB is available via the package manager installation. On Ubuntu install lldb-3.5 and lldb-3.5-dev

sudo apt-get install lldb-3.5 lldb-3.5-dev

The actual version of LLDB is not important. As of this writing the version 3.5 is available for Ubuntu distributions. On Fedora or other rpm-like system install lldb and lldb-devel

sudo yum install lldb lldb-devel

Warning: lldb-3.4 appears to be broken on Fedora.

RDB build requires C++ compiler. On Linux the version of GCC must be at least 4.7 because RDB is built with -std=c++11 command line option.

Clone the RDB Mercurial Repository

The RDB repository is a clone of the Jikes RVM repository, with some extra files that constitute the RDB. Note that we frequently pull in changes from the Jikes RVM repository to keep in sync with Jikes RVM development.

Build a Configuration of the Jikes RVM

To build the RDB, you only need to build the Jikes RVM. So, for example, to build the BaseBaseMarkSweep configuration on Mac OS X, run the following ant command:

ant -Dhost.name=x86_64-osx -Dconfig.name=BaseBaseMarkSweep

RDB is built automatically when you build the Jikes RVM. For more information on how to build the Jikes RVM, read the corresponding section in the Jikes RVM User's Guide.

Change to the Directory Containing the Built Configuration

The build process creates a full Jikes RVM build in the dist directory. Besides the rvm script that is used to launch the Jikes RVM normally, the build process also creates the rdb script, which is used to launch the Jikes RDB.

cd dist/BaseBaseMarkSweep_x86_64-osx

Find or Create a Java Application

RDB will run Jikes RVM, and the Jikes RVM will want to run some Java application. Either find an existing Java application, or write and compile a little Java HelloWorld program:

public class HelloWorld {
  public static void main(String[] args) {
    String s = null;
    // s.length() will throw a NullPointerException
    System.out.println("Hello World!"+s.length());
  }
}

javac HelloWorld.java

Try the Jikes RVM

Just to make sure your build worked, run the Java application with the Jikes RVM:

./rvm HelloWorld

This has nothing to do with RDB. It just runs the normal Jikes RVM. If this doesn't run, you may have to reconfigure and rebuild the Jikes RVM.

Launch RDB

If you were successful in running the Jikes RVM, then it's time to run RDB.

./rdb HelloWorld

RDB needs to locate the class files of the application being executed. To specify the paths to class files or jar files use -X:rdb: command line option. For example, this is how to invoke RDB if your application uses classes from mylib.jar and classes from the directory /some/obscure/classes/

./rdb -X:rdb:/path/to/mylib.jar:/some/obscure/classes HelloWorld

Alternatively, RDB can be invoked from any directory, then by default it will assume the application class files are located in the current working directory

/home/user/jikesrvm/dist/BaseBaseMarkSweep_x86_64-osx/rdb -X:rdb:/path/to/mylib.jar HelloWorld

Inspect the Boot Image

RDB (the debugger GUI application) is running, but it has not yet launched a Jikes RVM process. RDB currently just shows the boot image (based on the boot image files — RVM.code.image, RVM.data.image, and RVM.rmap.image — generated during the Jikes RVM build process). However, RDB allows you to inspect the boot image in exactly the same way it allows you to inspect a running process. There just won't be any running threads, no call stacks, and no register contents to see in the "State" view.

The above screenshot shows how RDB initially inspects the BootRecord, the "root" to Jikes RVM's internal data structures. The BootRecord is a normal Java object, located at a well known address (the object's official address is 0x3100000C, it's header actually starts a little bit before that, at address 0x31000000). The BootRecord is the structure in which the boot image runner, the small native code program that maps the boot image files into virtual memory, will store some initial runtime information it needs to pass to the RVM. The screenshot shows the boot record as it exists in the boot image, before the boot image runner has updated its values. One of the values in the boot record is the instruction address to which the boot image runner needs to jump for booting the RVM. This is the "ipRegister" field (showing the value 0x3532E330). Double-clicking on the corresponding row in the table inspects the entity located at that address:

RDB understands that the entity located at address 0x3532E330 is the code of a compiled method. Particularly, it is the code of method VM.boot(). This is the entry point to the virtual machine. The method was compiled during boot image writing, and its code is located in the code section of the boot image, from which RDB loaded it to show it here.

Set a Breakpoint

Before you launch the Jikes RVM, it may make sense to set a breakpoint, so that you can look at the Jikes RVM process before it terminates. Note that it is not necessary to set a breakpoint if you just want to suspend the Jikes RVM process on hardware-traps (i.e., NullPointerExceptions or IndexOutOfBoundsExceptions caused by trap instructions).

To set a breakpoint in a Code[] like the one of VM.boot(), make sure you are on the "Disassembly" tab (showing the machine code) and right-click in the left-most column of a disassembled machine instruction. The breakpoint is indicated in the left-most column with a red icon. It can be disabled and enabled again with a right-click. If you switch to the "Breakpoints" view (by picking the corresponding tab on left side of the window), you can see a list of all breakpoints. You can enable or disable a breakpoint with the checkmark, and you can double-click on a breakpoint to inspect the corresponding Code[].

Launch the Jikes RVM

Hit the "Run RVM" button in the tool bar. This will launch a Jikes RVM process that will run your Java application. The process will get suspended when (a) it hits a breakpoint or (b) it throws a hardware-trap based exception. The process will terminate when (c) the Java application terminates.

In cases (a) or (b), RDB will show the state of the suspended process in its "State" view, and you can resume or single-step to continue execution. In case (c), the Jikes RVM process will terminate, and RDB will show just the boot image (and you will be able to launch a new Jikes RVM process with the "Run JVM" button).