How to run JOOS 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:

Java SDK, version 1.5
Flex [download] [manual]
Bison [download] [manual]

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:

      [mimi] [~] passwd -r nis -e
      Enter existing login password: 
      Old shell: /usr/local/bin/tcsh
      New shell: /usr/local/bin/bash
      passwd: password information changed for cpicke

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:

      if ( $OSTYPE == FreeBSD ) then
        setenv JAVADIR /usr/local/diablo-jdk1.5.0
      else if ( $OSTYPE == solaris ) then
        setenv JAVADIR /usr/local/jdk1.5.0_08
      else if ( $OSTYPE == linux ) then
        setenv JAVADIR /opt/sun-jdk-1.5.0.12
      else
        echo "Unable to set JAVADIR properly."
      endif

Alternatively, if you are using bash you can add the following to your .bash_profile:

      case $OSTYPE in
        freebsd*)
          JAVADIR=/usr/local/jdk1.5.0
          ;;
        solaris*)
          JAVADIR=/usr/local/jdk1.5.0_08
          ;;
        linux*)
          JAVADIR=/opt/sun-jdk-1.5.0.12
          ;;
        *)
          JAVADIR=
          ;;
      esac
      
      if test -d $JAVADIR
        then
          export JAVADIR
        else
          echo "Unable to set JAVADIR properly."
      fi

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.

For .cshrc:

      setenv JOOSDIR $HOME/cs520/joos

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

      export JOOSDIR=$HOME/cs520/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

      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

      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.

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

      $ export PATH=$HOME/cs520/group-X/joos/scanparse/:$PATH
      $ cd $HOME/cs520/group-X/joos/scanparse/
      $ make
      $ cd tests
      $ joos CheckForLoops.java $JOOSDIR/externs/*.joos

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.

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