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.
  8. To generate the Java bytecode go to the MultiJava directory and use the commands:
  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.