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.

   *NOTE:* if you build a real-time application then add
ovm_rt_user_realtime.jar to the bootclasspath.

   * 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

   If your system supports the necessary linker magic then the output
ovm file is a combined executable and image, and you can execute your
application simply by doing:

     $ ./ovm HelloWorld

   Otherwise you pass the ovm executable the name of the image file:
     $ ./ovm img HelloWorld
   Note that the img file always exists even when linked into the
executable. If you see an error message that class "img" was not found,
then you are using the wrong form of invocation.

