TUTORIAL
********

The following presents a step-by-step explanation of how to compile Ovm,
install Ovm to a location of your choice, compile RTSJ code against
Ovm's runtime library, and generate a virtual machine containing an RTSJ
program (namely `HelloWorld').  In the rest of this example, we will
refer to the Ovm's toplevel directory (`OpenVM/') as OVM-DIR.  An
executable version of this example is available in
`OVM-DIR/examples/Makefile'.

Compiling and installing the Ovm distribution
=============================================

Choose a directory (OVM-BIN-DIR) under which the built runtime files
should be stored. OVM-BIN-DIR can be OVM-DIR if you like.

     $ cd OVM-BIN-DIR
     $ OVM-DIR/configure && make
      You can also install the runtime files by specifying the "install"
  target to make. By default this will install `gen-ovm' and the
runtime    files in `/usr/local/ovm'. To change the install location
use the    `--prefix' option when running `configure', eg:
     $ cd OVM-BIN_DIR
     $ OVM-DIR/configure --prefix=$HOME && make all install
      will install `gen-ovm' into `$HOME/bin'.

   The value of `--prefix' is the OVM-INSTALL-DIR.

Compiling Realtime Java code for use with Ovm
=============================================

Create your Hello World application, i.e. create a file
`HelloWorld.java' with:
     public class HelloWorld {
             public static void main(String args[]) {
                     System.out.println("Hello, World");
             }
     }

   Compile HelloWorld.java against the OVM runtime libraries:
     $ javac -target 1.1                                      \
             -bootclasspath OVM-JAR-DIR/ovm_rt_user.jar \
             HelloWorld.java
   The OVM-JAR-DIR depends on where you built ovm and where you
installed it.
   * If you built, but did not install ovm then OVM-JAR-DIR is:
      `OVM-BIN-DIR/src/syslib/user'.

   * If you installed ovm, using `make install' then OVM-JAR-DIR is:
       `OVM-INSTALL-DIR/ovm/classes'.

   *NOTE:* It is a current limitation with ovm that all .class files
are generated with the format defined by the `javac' `-target 1.1'
option. Failure to do this may result in runtime exceptions, or
crashes, due to missing fields or methods.

Build an OVM image with the Hello World application inside
==========================================================

Choose directory into which the executable and built image should be
stored. This is the OVM-EXE-DIR. Again OVM-EXE-DIR could be OVM-DIR.
     $ cd OVM-EXE-DIR
     $ OVM-BIN-DIR/bin/gen-ovm -main=HelloWorld \
                     -classpath=CLASSPATH TO `HELLOWORLD.CLASS'
   If you installed ovm then you could use OVM-INSTALL-DIR/bin/gen-ovm

   Have a cup of coffee while the image is built.

Run the executable
==================

     $ cd OVM-EXE-DIR
     $ ./ovm img HelloWorld