Jaguar Installation Guide

Jaguar Installation Guide

Matt Welsh, mdw at cs dot berkeley dot edu
Jaguar v2.1 - Last modified 17 May 2000

[ Back to the Jaguar Documentation Index ]

Introduction

This is the release documentation for Jaguar v2.1, dated 17 May 2000. Jaguar is a system developed by Matt Welsh at the UC Berkeley Computer Science Division which supports high-performance Java communication and I/O. For more information, see the Jaguar Project web pages.

Jaguar v2.1 (Release 17 May, 2000) is now available for download. Click here to download the release.

System requirements:

Jaguar has only been tested on x86-based Linux systems with kernel version 2.2.x and glibc 2.1.x or later (e.g., Red Hat 6.0 or later). However, it is very likely that the system will work on other platforms; in fact, Jaguar's compiler extensions are machine-independent. Please if you have success running Jaguar on other systems.
Some version of the JDK 1.1 or 1.2.
If you are using the JIT Jaguar compiler (based on OpenJIT), you need to use a version of the JDK supported by that compiler. I use the Sun JDK v1.1.7v3 with green threads from the Blackdown porting team. Other JDK versions (for other processors and operating systems) are supported by OpenJIT; see the OpenJIT web page for details.
If you are using the static Jaguar compiler (based on GCJ), any version of the JDK is fine, since this is only needed for compiling Java to bytecode, and running the Jaguar front-end compiler. Eventually these functions can be performed directly by gcj; see missing features below.
If you wish to use JaguarVia, the Jaguar interface to the VIA communications interface, you will need to download and install Berkeley VIA for Myrinet. Note that this requires a LanAI 4.x based Myrinet interface hardware. See the JaguarVia section in the Jaguar User Guide for more information.
There are two Jaguar back-end compilers available. The first is a JIT compiler based on OpenJIT, which is a JIT compiler (written in Java!) from Fujitsu Labs and the Tokyo Institute of Technology. It produces very efficient code, is open source, and based it's written in Java is a good platform for experimentation. You will need to download and install the "Jaguar-enhanced" version of OpenJIT from this site; this is described in installation, below.
The other back-end compiler is a modified version of GCJ, a static Java compiler and runtime library based on GCC (also known as EGCS). You will need to download and install GCJ and the libgcj runtime library which accompanies it; this is described in installation, below.
OpenJIT-Jaguar is useful if you want to run a complete JVM environment; GCJ-Jaguar produces faster code but does not support the full range of Java libraries. Dynamic class loading and RMI are two notable missing features.
You also need some version of Perl installed, GNU make (regular make will not work), and a Bourne-compatible UNIX shell, such as bash.

License

Jaguar is Copyright (c) 1999-2000 by Matt Welsh and the Regents of the University of California. Jaguar is entirely Open Source, but is covered under several different software licenses, as explained below.

All software in the Jaguar code tree is covered by the terms of the UC Berkeley License, with the following exceptions:

The patch to GCJ to support Jaguar is covered by the GNU General Public License.
The Jaguar.compiler.classfile package is derived from demonstration code included with the Java Beans Development Kit (BDK 1.1) which is covered Clause 2 of the BDK 1.1 license, which is an Open Source license.

Installation

(Note to users at Berkeley: You shouldn't have to go through all of this to use Jaguar; just about getting access to machines with Jaguar pre-installed.)

Here's how to download and install Jaguar:

First, select either OpenJIT-Jaguar or GCJ-Jaguar as your back-end compiler. Both are available from the Jaguar release page.
Alternately, if you wish to use OpenJIT-Jaguar, you may also obtain the latest OpenJIT release from www.openjit.org, and apply the patch from patches/OpenJIT-1.1.10-jaguar-patch.gz to it.
If you wish to use GCJ-Jaguar, another way is to obtain the GCC 2.95.2 and libgcj 2.95.2 trees from Cygnus, at sourceware.cygnus.com/java. If you go this route, you will need to patch the GCC source tree with the patch from patches/gcc-2.95.2-jaguar-patch.gz, and the libgcj source tree with the patch from patches/libgcj-2.95.2-patch.gz, both of which are found in the Jaguar distribution. (The former patch adds Jaguar support to GCJ; the latter is a set of fixes for libgcj 2.95.2 which have nothing to do with Jaguar, but are required). Note that you may wish to upgrade to a newer version of GCJ/libgcj (perhaps to overcome some of the missing features described below), in which case you will need to adapt the gcc-2.95.2-jaguar-patch.gz for that version of GCJ. The libgcj patch should no longer be required if you do this.
The complete source trees provided on the Jaguar release page already have these patches applied.
Compile the back-end compiler. Here are instructions on doing this:
Compiling OpenJIT-Jaguar: Unpack the source distribution, run ./configure, make, and make install. That should be it! If you have problems see the file INSTALL in the OpenJIT source tree.
Once you have installed OpenJIT-Jaguar, be sure to set JAVA_COMPILER to Jaguar, e,g.,
```
  export JAVA_COMPILER=Jaguar
```
This will cause the JDK to use the OpenJIT-Jaguar compiler. Note that the startup time for Java applications (including javac) may be affected, since OpenJIT is implemented in Java and first compiles itself. If this is the case, using the commandline argument
```
  -Dcompile.disable=OpenJIT
```
to java should help.
Compiling GCJ-Jaguar: Issue the following commands (I put these in a script). Set EGCS_SRC_DIR, EGCS_OBJ_DIR, and EGCS_INSTALL_DIR to whatever you like. Note that EGCS_OBJ_DIR is only used during the build, so it can be a temporary directory.
```
  export CC=gcc
  export EGCS_SRC_DIR = /home/gcc-2.95.2-jaguar       (whatever you like)
  export EGCS_OBJ_DIR = /tmp/gcc-2.95.2-jaguar-build  (whatever you like)
  export EGCS_INSTALL_DIR = /usr/local/gcj-jaguar     (whatever you like)
  mkdir -p $EGCS_OBJ_DIR
  mkdir -p $EGCS_INSTALL_DIR
  cd $EGCS_OBJ_DIR
  $EGCS_SRC_DIR/configure --prefix=$EGCS_INSTALL_DIR --enable-languages=c,java,c++ --enable-threads=posix --enable-jaguar=yes
  make boostrap-lean
  make install
  
```
This compile takes a long time; I strongly suggest that the install and build directories be located on a local disk. You'll need a lot of disk space; on my system, the EGCS source tree takes up 63 MBytes, the build directory 54 MBytes, and the install directory (including libgcj) 40 MBytes.

Next, compile libgcj. Issue the following commands; again, I put these in a script.
```
  export EGCS_INSTALL_DIR = /usr/local/gcj-jaguar   (must be same as above)
  export LIBGCJ_SRC_DIR = /home/libgcj-2.95.2       (whatever you like)
  export LIBGCJ_OBJ_DIR = /tmp/libgcj-build         (whatever you like)
  export PATH=$EGCS_INSTALL_DIR:$PATH
  mkdir -p $LIBGCJ_OBJ_DIR
  $LIBGCJ_SRC_DIR/configure --prefix $EGCS_INSTALL_DIR --enable-threads=posix --enable-interpreter=yes
  make
  make install
```
This also takes a long time. The libgcj source directory takes up about 16 MBytes, and the build directory 33 MBytes.
If you ever want to move the installed location of GCJ-Jaguar and libgcj, you will need to re-configure and recompile the source from scratch. This is because the prefix defined in the configure commands sets hardwired paths in various binaries and configuration files.
Download Jaguar from this web page. Unpack the tarfile somewhere meaningful. It should contain a directory jaguar2.
Put the directory jaguar2/classpath on your CLASSPATH, e.g.,
```
  export CLASSPATH=$CLASSPATH:/home/jaguar2/classpath
```
Put the directory jaguar2/bin on your PATH, e.g.,
```
  export PATH=$PATH:/home/jaguar2/bin
```
This will allow the build process to locate a couple of scripts that it requires.
If you are using OpenJIT-Jaguar, put the directory jaguar2/lib on your LD_LIBRARY_PATH, e.g.,
```
  export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/jaguar2/lib
```
This will allow the JVM to pick up any native methods that are used by the Jaguar libraries. Also, be sure to set JAVA_COMPILER to Jaguar.
If you wish to use JaguarVia, the Jaguar driver for the Berkeley VIA fast communications layer, you need to download and install Berkeley VIA from this web page. Get the latest version for Linux and the LanAI 4.x Myrinet NIC. (Note for users at Berkeley: about getting access to machines with Berkeley VIA pre-installed.)
To compile the tree, do the following:
- Type ./configure in the jaguar2 directory. This will automatically determine the location of your JDK (and GCJ, if you have it) installation. If you are using GCJ be sure that the gcj command is on your PATH.
  If you plan to use JaguarVIA, instead type ./configure --with-via=via-install-dir where via-install-dir is the location where Berkeley VIA is installed.
- If you are using OpenJIT-Jaguar, type make. This builds the Jaguar front-end compiler, the Jaguar driver translation rules, the various Jaguar libraries, and finally various test programs which make use of those libraries and drivers.
- If you are using GCJ-Jaguar, instead type make all-gcj. This builds the Jaguar tree to make use of GCJ rather than OpenJIT. Note that currently a single Jaguar code tree cannot be used for both OpenJIT and GCJ installations.
To get an initial idea of whether Jaguar is working at all, do the following:
```
  cd classpath/Jaguar/PSO/test
  java PSOTest   (if you are using OpenJIT-Jaguar)
  ./PSOTest      (if you are using GCJ-Jaguar)
```
This will run a series of simple tests of Jaguar's PSO mechanism, which will fail if Jaguar isn't properly installed and working. To double-check that everything's working correctly, compare the output of PSOTest against the file PSOTEST-CORRECT-RESULTS in that directory. (Note: The output of PSOTest may differ slightly based on which JDK you are using. However, if the output of the test looks basically right, everything's fine.)
The Jaguar front-end compiler and libraries can be optionally installed to your JDK or GCJ installation directory.
To install Jaguar for use with OpenJIT-Jaguar, type make install. This will install the Jaguar software in your JDK installation directory (alongside the OpenJIT-Jaguar installation). The file README.Jaguar will be created in that directory telling you how to set up your environment variables to make use of this installation. If you wish to remove this installation later, you can type make uninstall.
To install Jaguar for use with GCJ, type make install-gcj. This will install the Jaguar software in your GCJ installation directory. The file README will be created in that directory telling you how to set up your environment variables to make use of this installation.

[ Back to the Jaguar Documentation Index ]

M. Welsh
Berkeley Jaguar Project