Compiling the source code

The majority of MRP is written in Java and will be compiled into class files just as with other Java applications. There is also a small portion of MRP that is written in C that must be compiled with a C compiler such as gcc or VisualC. MRP uses Ant version 1.6.5 or later as the build tool that orchestrates the build process and executes the steps required to build MRP.

Note MRP requires a complete install of ant, including the optional tasks. These are present if you download and install ant manually. Some Linux distributions have decided to break ant into multiple packages. So if you are installing on a platform such as Debian you may need to install another package such as 'ant-optional'.

Generating source code

Creating compilers is error prone, in order to reduce errors certain source files are generated using tools. Before building the main source code these source files must be generated. A legacy to Jikes RVM is that some compile time constants are also generated in this step.

Bootstrapping MRP

MRP builds on the Jikes RVM build process. The boot image writer is a Java application that takes Java class files and passes them to the Jikes RVM compilers which produce arrays of code. The generated code and the objects it references are serialized into the boot image. The boot image writer is able to determine the contents of objects for the boot image using reflection. Some "objects" are handled specially by the compilers and effectively become primitives when the VM executes, versions of these special objects that work as true objects for the boot image writer are in the boot image writer tool directory. Discovery of which classes to include in the boot image isn't yet automated. A list of classes known as the primordials is created and passed to the boot image writer.

Whilst it would be possible to create boot image as an executable file, MRP uses a lightweight, portable boot-loader to load and begin executing the boot image.

Class libraries

The Java class library provides standardized utilities such as collections and means for IO. There are different suppliers of class libraries, the main open source providers are:

• the Free Software Foundation with GNU Classpath
• Apache with Apache Harmony
• Oracle with OpenJDK

Setting the ant property classlib.provider (see how to define ant properties) can change the build process to download and build a different class library. The current default is the GNU Classpath library in Linux, or Apache Harmony in Windows.

Instruction Sets and Operating Systems

MRP supports PowerPC 32 and 64 bit Instruction Set Architectures (ISAs) and Intel 32 and 64 bit ISAs. We call these architectures ppc32, ppc64, ia32 and x86_64 respectively.

Note Jikes RVM doesn't support the x86_64 ISA but has x86_64 configurations that builds a 32bit version of Jikes RVM. When switching to MRP make sure that if you use the x86_64 configuration your machine is 64bit. Whilst 64bit architectures offer better integer precision and extra instructions, they also increase the size of references. The increases in memory usage can come at a significant performance cost.

The main operating systems for MRP are Linux, OS/X and Windows. Support for AIX and Solaris exists but are difficult to test.

The machine that MRP is built on is known as the host, the machine on which MRP will run is known as the target. Configuration property files exist in the build/hosts and the build/targets directories. The property files specify the features of an OS and ISA to MRP, the separation of files provides limited support for cross compilation. The host.name and target.name ant properties specify which files will be used in the build. Not specifying a target means the target will be the same as the host.

Java Virtual Machine

MRP requires an existing Java Virtual Machine that conforms to Java 5.0. You can run "java -version" to check you are using the correct JVM.

Ant

Ant version 1.6.5 or later is the tool required to orchestrate the build process. You can download and install the Ant tool from http://ant.apache.org/ if it is not already installed on your system. The remaining build instructions assume that $ANT_HOME/bin is on your path. You can run "ant -version" to check you are running the correct version of ant.

C Tool Chain

MRP requires a C compiler with linking tools. For *nix having GCC installed will provide enough support. For Windows please install Visual C.

Note The free express edition of Visual C and Visual Studio is sufficient to develop and debug MRP.

Bison

As part of the source file generation process, MRP uses the bison tool that is commonly available *nix OSes and which is available through Cygwin for Windows.

Perl and Bash

Perl and Bash are trivially used as part of the build process but this requirement may be removed in future releases. Perl is also used as part of the regression and performance testing framework. For Windows Perl and Bash can be installed with Cygwin.

Awk

GNU Awk is required as part of the regression and performance testing framework but is not required when building MRP.

Building Under Windows

To build Apache Harmony from source requires access to copy and paste support source code not provided with the express version of Visual C. In order to build download the pre-compiled zip file of the Apache Harmony HDK and extract it. Specify the path to the HDK with the property harmony.hdk.dir and define the property harmony.from-hdk to be true.

For example the following builds MRP for Windows:

ant -Dhost.name=ia32-cygwin -Dconfig.name=prototype -Dclasslib.provider=Harmony -Dharmony.from-hdk=true -Dharmony.hdk.dir=<HDK path>

Upon request debug symbols for a pre-compiled Apache Harmony HDK can be supplied by Apache Harmony.

Extra tools recommended for Solaris

pkg-get will greatly simplify installing GNU packages on Solaris. Our patches require that GNU patch is picked up in preference to Sun's, to achieve this, for example, you can create a symbolic link to /usr/bin/gpatch from /opt/csw/bin/patch and make sure /opt/csw/bin is in your path before /usr/bin.

Defining Ant properties

There are a number of ant properties that are used to control the build process of Jikes RVM. These properties may either be specified on the command line by "-Dproperty=variable" or they may be specified in a file named ".ant.properties" in the base directory of the source tree. The ".ant.properties" file is a standard Java property file with each line containing a "property=variable" and comments starting with a # and finishing at the end of the line. The following table describes some properties that are commonly specified.

A minimum is that the user specify the host.name property.

Note If the components.cache.dir option isn't used then the build will download necessary components. If you are behind a proxy then add the following line to build.xml: <setproxy proxyhost="proxy" proxyport="8080" proxyuser="username" proxypassword="userpass"/>

The configuration files in "build/targets/" and "build/hosts/" are designed to work with typical installations but it may be necessary to override specific properties.

Selecting a Configuration

A "configuration" in terms of MRP is the combination of build time parameters and component selection used for a particular Jikes RVM image. Typical configuration names include;

• production: This configuration defines a fully optimized version of the Jikes RVM with most debug options stripped out.
• development: This configuration is the same as production but with debug options enabled. The debug options perform internal verification of MRP and Jikes RVM which means that it builds and executes more slowly.
• prototype: This configuration is compiled using an unoptimized compiler and includes minimal components which means it has the fastest build time.
• prototype-opt: This configuration is compiled using an unoptimized compiler but it includes the adaptive optimization system and optimizing compiler. This configuration has a reasonably fast build time and can be used to debug the optimizing compiler.

If a user is working on a particular configuration most of the time they may specify the config.name ant property in ".ant.properties" otherwise it should be passed in on the command line "-Dconfig.name=...".

Fetching Dependencies

MRP will automatically fetch dependencies and place them in the components directory. If you wish to manually download components you can do so and identify the directory containing the downloads using "-Dcomponents.cache.dir=<download directory>" when you build with ant.

Building MRP

The next step in building MRP is to run the ant command "ant" or "ant -Dconfig.name=...". This should build a complete MRP runtime in the directory "${dist.dir}/${config.name}_${target.name}". The following table describes some of the ant targets that can be executed. A complete list of documented targets can be listed by executing the command "ant -projecthelp"

Running MRP

MRP can be executed in a similar way to most Java Virtual Machines. The difference is that the command is "rvm" and resides in the runtime directory (i.e. "${dist.dir}/${config.name}_${target.name}").