This page gives instructions for installing the MultiJava tools, whether in bytecode or source code form. These instructions are also included in the README.html file in the MultiJava directory of the source code archive.

The MultiJava Project

Contents

This document provides the following information:

Source Code Manifest

The files in the source code archive contain all the source code for the MultiJava project. The directory tree rooted at org/multijava contains the source code specific to the MultiJava project. The directory tree rooted at antlr contains the bytecode for the ANTLR translator-generator package used by the project. The directory tree rooted at gnu contains the bytecode for the gnu.getopts package that is used for processing command line arguments. The directory tree rooted at junit contains the JUnit unit testing framework that is used for test case generation and execution. (If you wish to download the source code for these support packages, please follow the package links.)

Installation

There are three different sets of installation instructions here. Choose the correct one depending on whether you are using the bytecode download (mjc-XXX.jar), the source code download (mjc-XXX.tar.gz), or the cvs snapshot (from SourceForge).

Installation of Bytecode Download (mjc-XXX.jar file)

  1. MultiJava requires the Java 2 API, at least version 1.4. Testing has been done using JDK 1.4.1 and 1.4.2 and 1.5.0. JDKs for most operating systems are available from Sun's website. The JDK is included in all Mac OS X installations. (Mac users should run Software Update to make sure they have the latest version of Java.) To see which version of Java you have use the command java -version.
  2. While this release of MultiJava should work with JDK 1.5.0, note that the mjdoc tool does not work with JDK 1.5. Also mjc does not properly parse the new Java 5 features.
  3. Download the mjc-XXX.jar file, where XXX is the version information.
  4. Add the complete path up to and including the mjc-XXX.jar file to your Java CLASSPATH. This makes the MultiJava packages, antlr (version 2.7.6), ant (version 1.6.1 or later), gnu.getopts, and junit (version 3.8.1) available to your Java environment. If you have a newer version of antlr, gnu.getopts, or junit installed you can put the paths to these ahead of the mjc-XXX.jar entry in your CLASSPATH. (Be warned that we test with the versions included in the jar file.)
  5. If you are using Mac OS X, then your installation is complete.
  6. If you are using Windows, Linux, Solaris, or any other OS besides Mac OS X, and if you want to use the mjdoc documentation tool, then you must complete one more step. Locate the directory containing the JDK on your system. Inside this directory should be a subdirectory lib. Inside lib should be a file tools.jar. Add the complete path up to and including the tools.jar file to your Java CLASSPATH.

See below for instructions on running mjc and running mjdoc.

Installation of Source Code Download (mjc-XXX.tar.gz file)

A Makefile system is include for compiling the MultiJava source code. These steps assume you are running under the bash shell in Linux, Unix, Cygwin, or Mac OS X. Follow the steps below to install the MultiJava project:

  1. MultiJava requires the Java 2 API, version 1.4. Testing has been done using JDK 1.4.1 and 1.4.2 and 1.5.0. JDKs for most operating systems are available from Sun's website. The JDK is included in all Mac OS X installations. (Mac users should run Software Update to make sure they have the latest version of Java.) To see which version of Java you have use the command java -version.
  2. If you wish to use Java 2, version 1.5 (Tiger), define the environment variable JAVA5 and the environment variable JAVATOOLS15 to the full path to the file classes.jar. E.g., I use export JAVA5=t and export JAVATOOLS15=/usr/java/jdk-1.5/lib/classes.jar.
  3. If you have not done so already, unzip and untar the archive, mjc-XXX.tar.gz, where XXX is the version information. This can be done with the command tar xvzf mjc-XXX.tar.gz, or on Windows by using the shareware utility WinZip. This unzipping and untarring will create a directory named MultiJava that contains all the other files and subdirectories for the project.
  4. Add the MultiJava directory to your Java CLASSPATH. This makes the MultiJava packages, antlr (version 2.7.2), gnu.getopts, and junit (version 3.8.1) available to your Java environment. If you have a newer version of antlr, gnu.getopts, or junit installed you can put the paths to these ahead of the mjc-XXX.jar entry in your CLASSPATH. (Be warned that we test with the versions included in the jar file.)
  5. If you are using Windows, Linux, Solaris, or any other OS besides Mac OS X, and if you want to use the mjdoc documentation tool, then you must complete this step: Locate the directory containing the JDK on your system. Inside this directory should be a subdirectory lib. Inside lib should be a file tools.jar. Add the complete path up to and including the tools.jar file to your Java CLASSPATH.
  6. Go to the directory MultiJava.
  7. Set environment variables as described below. Some of these settings depend on whether you are running Sun's JDK for Windows or for Linux/Unix/Mac OS X. You may wish to create a shell script for setting these variables. Sample scripts are in the files MultiJava/bin/example-developers-sourceme-cygwin.sh and MultiJava/bin/example-developers-sourceme-unix.sh.
    • Set PLSL_CLASSROOT to the MultiJava directory. I use the command export PLSL_CLASSROOT='/home/cclifton/MultiJava'.
    • Set MJ_CLASSROOT to the MultiJava directory. I use the command export MJ_CLASSROOT='/home/cclifton/MultiJava'.
    • If your JDK implementation uses different path separators than your shell (for example, the JDK for Windows uses Windows-style paths while the Cygwin shell for Windows uses Unix-style paths), then set MJ_JCLASSROOT to the fully qualified path to the MultiJava directory as used by your JDK implementation. Since I run the JDK for Windows, I use the command export MJ_JCLASSROOT='c:\\cygwin\\home\\cclifton\\MultiJava'. The double backslashes are necessary even given the single quotes since this environment variable will be processed by the make system. Under Linux or Mac OS X, I would simply not set the MJ_JCLASSROOT, causing the make system to just use the value of MJ_CLASSROOT instead.
    • Set JFILESEP to the file separator character as used by your JDK implementation. On Windows, I use the command export JFILESEP='\\'. Under Linux or Mac OS X, I would use export JFILESEP='/'.
    • Set JAVAC to the command to invoke your Java compiler. For example, use export JAVAC = javac for the Sun compiler or use export JAVAC = jikes +E +P for IBM's Jikes compiler.
    • If you are using a JDK 1.4 version other than 1.4.1 or 1.4.2, you will not necessarily be able to build or use the mjdoc tool as it currently relies on several undocumented API calls that have changed between versions of the JDK. The same applies to JDK 1.5, for which mjdoc does not work. To skip building mjdoc, you should define the environment variable SKIP_MJDOC; for example: export SKIP_MJDOC=1
    • If you have local copies of the javadoc documentation for the Java APIs you can set environment variables so that the MultiJava javadocs will link to the existing documentation. I use the following command with the JDK for Windows; adjust the paths according to your configuration:
      • export JDKDOCDIR='file:c:\\cygwin\\usr\\local\\jdk1.4\\docs\\api'
  8. To generate the Java bytecode go to the MultiJava directory and use the commands:
    • make clean
    • make
  9. There are many environment variables and compilation targets that can be used for various customizations. Refer to the files MultiJava/Make.ProjDefs and MultiJava/Make.Defs for documentation. Other targets of the make operation include make javadocs, make debug-build, make clean-classes, make pristine, make rebuild-all, make runtests, and make quiet-tests.

Only the bytecode (not the source code) for ANTLR, gnu.getopts, and JUnit is included in the source code tar.gz file. If for some reason you need to recompile any of these packages you will need to download the source code from the appropriate web sites.

See below for instructions on running mjc and running mjdoc.

Installation of CVS version from SourceForge

A snapshot of our current development code is available via anonymous CVS. See the MultiJava CVS page for instructions on access the development code.

The files for ANTLR, gnu.getopts, Apache Ant, and JUnit are not included with the CVS code. You should download and install these utilities separately by following the links. Note that we use, and test with, ANTLR version 2.7.6, Ant 1.6.5, and JUnit version 3.8.1.

After successfully installing these packages and updating your CLASSPATH environment variable accordingly, please proceed with the numbered steps above for the source code download, replacing references to the MultiJava directory with MJ. (You will not need to untar anything in step 2 as the CVS checkout installs individual files.)

Running mjc, a MultiJava Compiler

Assuming that your system is configured to run Java programs, follow these steps to run mjc:

  1. Update your CLASSPATH according to the appropriate installation instructions above.
  2. Invoke the MultiJava compiler with the command java org.multijava.mjc.Main <filename(s)> where <filename(s)> is the name or names of the files to be compiled. The command java org.multijava.mjc.Main --help will display a list of options. Note that the listed options show --longname in the GNU options style. You may use a single dash, i.e., -longname for most options. This allows mjc to be "dropped in" in place of javac.
  3. See below for information on interpreting mjc error messages.

I recommend using a shell script for invoking mjc. The MultiJava/bin directory includes some sample shell scripts (mjc-unix and mjc-cygwin) for invoking mjc that you may find useful. Some users (or system administrators) find it helpful to copy these shell scripts to a directory on their PATH and edit them for their local configuration.

MultiJava also includes an experimental graphical user interface. See Using the GUI below for more information.

Interpreting mjc Error Messages

Messages reported by mjc have the following form:

filename:line:column kind: description [reference]

where:

Running mjdoc, a MultiJava documentation generator

Assuming that your system is configured to run Java programs, follow these steps to run mjdoc:

  1. Update your CLASSPATH according to the appropriate installation instructions above.
  2. Invoke the MultiJava compiler with the command java org.multijava.mjdoc.Main <filename(s)> where <filename(s)> is the name or names of the files to be compiled. The command java org.multijava.mjdoc.Main --help will display a list of options. Note that the listed options show --longname in the GNU options style. You may use a single dash, i.e., -longname for most options. This allows mjdoc to be "dropped in" in place of javadoc.

I recommend using a shell script for invoking mjdoc. The MultiJava/bin directory includes some sample shell scripts (mjdoc-unix and mjdoc-cygwin) for invoking mjdoc that you may find useful. Some users (or system administrators) find it helpful to copy these shell scripts to a directory on their PATH and edit them for their local configuration.

MultiJava also includes an experimental graphical user interface. See Using the GUI below for more information.

Using the GUI

MultiJava ships with an experimental graphical user interface that can be used to launch mjc and mjdoc. If you installed the bytecode .jar file, simply double-clicking the .jar file will start the GUI launcher on most systems. If that doesn't work, or if you performed a source code installation, then you can launch the GUI with the command: java org.multijava.launcher.MjLauncher

Running the test cases

While not required, some users may find it interesting to run the test suite that we use for development. The test suite is included in the source code and CVS downloads (but not in the bytecode download). The tests can be run by switching to the MultiJava directory and executing the command make runtests (or make quiet-tests for less verbose output). Note that the functional tests require that you include the current directory (.) in your CLASSPATH, and also that you have the environment variable TEMP set to a directory to which you have write permissions.

Relaxed MultiJava

An extension to MultiJava, called Relaxed MultiJava, has been developed. Relaxed MultiJava replaces most of MultiJava's static restrictions on top-level methods and multiple dispatching with compile-time warnings, backed up with class-load-time checks. This allows the programmer to write code in a more flexible style, without sacrificing static typechecking, at least at class load-time. It also provides additional support for integrating independently developed libraries. More information about Relaxed MultiJava is in the org/multijava/relaxed subdirectory.

Problems, Questions, and Bug Reports

Given the size of this code base there are certainly bugs remaining. We would appreciate reports of any problems that you find or questions that you have via the support request form. The MultiJava tools are being used on several "real-world" projects, therefore fixing bugs is our highest priority.

up arrow Return to top

Page last modified Wednesday, December 31, 2003.