How to run and Java programs

1. Making sure prerequisites are installed

Your machine or the host you are logged in to must have these tools correctly installed:

  1. Java SDK, version 1.5 at least
  2. Flex [download] [manual]
  3. Bison [download] [manual]

2. Setting up your environment

Some of the scripts in this course depend on certain environment variables being set.

JAVADIR

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

JOOSDIR

This variable tells scripts where to find the JOOS binaries and libraries. Example: 
      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

This is the A- JOOS compiler. It converts Java source code .java files to Jasmin assembler .j files that contain human-readable representations of Java bytecode.

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.

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.

Task: convert the Jasmin .j files generated by some JOOS compiler into real Java .class files: 

      $ jasmin f1.j f2.j ... fn.j

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.

4. Understanding the tool relationships

Maintained by Laurie Hendren [HOME]