This document provides the following information:
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.)
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).
java -version
.mjc-XXX.jar
file, where
XXX
is the version information.
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.)
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.
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:
java -version
.classes.jar
. E.g., I use export JAVA5=t
and export JAVATOOLS15=/usr/java/jdk-1.5/lib/classes.jar
.
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.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.) 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. MultiJava
.MultiJava/bin/example-developers-sourceme-cygwin.sh
and
MultiJava/bin/example-developers-sourceme-unix.sh
.
PLSL_CLASSROOT
to the MultiJava directory. I use the
command export PLSL_CLASSROOT='/home/cclifton/MultiJava'
.MJ_CLASSROOT
to the MultiJava directory. I use the
command export MJ_CLASSROOT='/home/cclifton/MultiJava'
.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.export JFILESEP='\\'
. Under Linux or Mac OS X, I would use
export JFILESEP='/'
.export JAVAC = javac
for
the Sun compiler or use export JAVAC = jikes +E +P
for
IBM's Jikes compiler.export SKIP_MJDOC=1
export
JDKDOCDIR='file:c:\\cygwin\\usr\\local\\jdk1.4\\docs\\api'
MultiJava
directory
and use the commands:
make clean
make
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.
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.)
Assuming that your system is configured to run Java programs, follow these steps to run mjc:
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.
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.
Messages reported by mjc have the following form:
filename:
line:
column
kind:
description
[
reference]
where:
error
, a problem that prevents compilation from
completingcaution
, a problem that should be fixed in the
code, but does not prevent compilation from completingwarning
, a potential problem in the code, but one
that may not actually be wrong and does not prevent compilation
from completingJLS
, the Java Language Specification, First EditionJLS2
, the Java Language Specification, Second EditionMultiJava
, Clifton's masters thesisCLCM 00
, the OOPSLA 2000 paper by Clifton, et
al.RMJ
, the Relaxed MultiJava paper by Millstein,
Reay, and ChambersAssuming that your system is configured to run Java programs, follow these steps to run mjdoc:
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.
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
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.
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.
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.