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' and `ovm-config' into    `$HOME/bin'.

   The value of `--prefix' is the OVM-INSTALL-DIR, and    the remainder
of this example assumes that    `OVM-INSTALL-DIR/bin' is on your search
path.

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.  With
Ovm's `bin' directory on your `$PATH', do the following:
     $ rt=`ovm-config -threads=RealtimeJVM get-string bootclasspath`
     $ javac -source 1.4 -target 1.4 -bootclasspath $rt HelloWorld.java

   *NOTE:* It is a current limitation with ovm that all .class files
are generated with the format defined by the `javac' `-target 1.4' or
lower option. Failure to do this may result in build failures due to
the lack of Java Two 5.0 version 1.5 classes.

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
     $ gen-ovm -threads=RealtimeJVM -main=HelloWorld \
               -classpath=CLASSPATH TO `HELLOWORLD.CLASS'

   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.  If you aren't sure
whether the image file must be provided, you can simply run:
     $ ./ovm `ovm-config get-string image-argument` HelloWorld

