How to run and Java programs

1. Making sure prerequisites are installed

2. Setting up your environment

Some of the scripts in this course depend on certain
environment variables being set. You will be able to run
the Java and JOOS tools on mimi (Sun Solaris) or
any of the Gentoo Linux or FreeBSD machines. These instructions
work for both the default tcsh shell as well as
bash. It is strongly recommended that you log in
to mimi and change your shell to bash
unless you have a particular affinity for tcsh:

JAVADIR

This variable must point to the location of the directory
containing your desired installation of the Java SDK.

To set up a Java environment that will work on the
{FreeBSD,linux,solaris} machines in the SOCS labs, you
can add some startup scripts that run when you log in. If you
are using tcsh as your shell you can add the
following to your .cshrc:

Notice that the bash code is actually a little bit
more robust, and will warn you properly on
willy.cs.mcgill.ca where Java 1.5 is not installed.
The reason we specify Java 1.5 is that you will actually analyse
the output of javac in the peephole contest and it
helps if everybody is using the same version.

You may want to add new cases to these scripts. If you find
another lab machine at school with a Java 1.5 installation in a
different directory, please let us know about it.

JOOSDIR

This variable tells scripts where to find the JOOS binaries and
libraries. Once you have checked out
the public_html directory of the class SVN repository, and
assuming its in $HOME/cs520/public_html/, then you
should add the following to your .cshrc:

setenv JOOSDIR $HOME/cs520/public_html/joos

if you are using tcsh, or the following to your
.bash_profile:

export JOOSDIR=$HOME/cs520/public_html/joos

if you are using bash.

CLASSPATH

This variable tells javac and java
where to find required libraries. We would like to add the
current directory . to our CLASSPATH as well the
jar file containing the JOOS libraries,
jooslib.jar:

setenv CLASSPATH .:$JOOSDIR/jooslib.jar:$CLASSPATH

or

export CLASSPATH=.:$JOOSDIR/jooslib.jar:$CLASSPATH

for tcsh and bash respectively.

PATH

Now you can add the JAVADIR and JOOSDIR binaries to your path using:

setenv PATH $JAVADIR/bin:$JOOSDIR/bin:$PATH

or

export PATH=$JAVADIR/bin:$JOOSDIR/bin:$PATH

for tcsh and bash respectively. Note
that since $PATH appears at the end of the string,
these directories will be searched for binaries before any of
the directories found in the old value of PATH.

Note: as you will be modifying the A- JOOS compiler, you may
find it convenient to place the directory containing your
modifications on your path as well.

3. Using the various tools

This section describes the use of the various tools needed for
the JOOS project. It assumes that the environment variables in
the previous section have been set properly.

joosa+

This is the A+ JOOS compiler. It is actually a wrapper script
around binaries for several different architectures that
looks at the value of $HOSTTYPE to determine
what to execute.

Task: compile JOOS programs using the A+ compiler into a similar
collection of Jasmin files:

$ joosa+ f1.java f2.java ... fn.java f1.joos f2.joos ... fn.joos

Note that JOOS programs are really collections of regular
.java files (f1.java through
fn.java) along with special externs that
provide access to the Java class libraries (f1.joos
through fn.joos). Many externs are already present
in $JOOSDIR/joos/extern and get pulled in
automatically by the script. This means that quite possibly you
will not need to specify any of your own. The
.java extension for JOOS classes is used so that
JOOS programs can also be compiled easily with
javac.

joos

The A- source code is in $JOOSDIR/a-, but you will
be copying it to your own group repository for the course
deliverables. You should build the binary from the source
yourself by typing make. You should then add the
source directory to your PATH so that joos is found
by the joosa- script described later. Initially, it
is fine to add $JOOSDIR/a- to your PATH; just
remember that you can override it by
prepending additional directories in the future.

Task: set up PATH, compile joos for the
scanning and parsing deliverable, and then experiment with a
test program:

Note that ideally the first step will go into your
.bash_profile and that you will define a make
check target that performs the last two steps for you,
converts the .j files to .class files,
and then verifies and executes the program.

joosa-

This is a wrapper around the A- JOOS compiler. It expects to
find a binary called joos on your PATH, and for the
JOOSDIR environment variable to be set.
Task: Compile a JOOS program using the
joosa- script:

$ joos f1.java f2.java ... fn.java f1.joos f2.joos ... fn.joos

Note that here the .joos extern files are ones that
you have written; the script already pulls in all of the externs
from the $JOOSDIR/extern directory.

jasmin

This is the Jasmin assembler. It is actually a wrapper script
that calls java to execute jasmin.Main.

joosc

This is a convenience wrapper script that calls
joosa- and then calls jasmin for a JOOS
program.
Task: compile a JOOS program directly to Java bytecode:

$ joosc f1.java f2.java ... fn.java f1.joos f2.joos ... fn.joos

Note that this will also leave the intermediate .j
files in the current directory.

javac

This is the official Java compiler. You can confirm that it is
version 1.5 by typing java -version.

Task: compile JOOS programs, which are also Java
programs, into a similar collection of class files using the
official JDK:

$ javac f1.java f2.java ... fn.java

If your CLASSPATH is set properly this will work, because
javac will search the JOOS libraries as necessary.
Note that all files must end with .java.

dejava

This is the D-Java .class file disassembler. It is
actually a wrapper script around binaries for several different
architectures that looks at the value of $HOSTTYPE
to determine what to execute.

Task: disassemble a collection of Java
.class files that constitute a JOOS/Java program
into a collection of Jasmin assembler .j files:

$ dejava f1.class f2.class ... fn.class

java -verify

This is the Java virtual machine running with the class file
verifier turned on. The verifier makes sure that the bytecode
obeys the rules of the Java
Virtual Machine Specification.

Task: execute and verify .class files
containing Java bytecode:

$ java -verify Main

where Main is the main class of the application. Note that you
must not use an extension here. If your CLASSPATH is set
properly this will work, because java will search
the JOOS libraries as necessary.