@c This document? This chapter?  
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 @code{HelloWorld}).  In the rest of this example, we
will refer to the Ovm's toplevel directory (@file{OpenVM/}) as
@var{OVM-DIR}.  An executable version of this example is available in
@file{@var{OVM-DIR}/examples/Makefile}.

@iftex
The remainder of this chapter describes how to compile and install the
Ovm distribution, compile Realtime Java code for use with Ovm, generate an
Ovm virtual machine, and run the @code{HelloWorld} VM executable.
@end iftex

@menu
* install::     Compiling and installing the Ovm distribution
* compile::     Compiling Realtime Java code for use with Ovm
* build::       Generating a virtual machine
* run::         Executing @code{HelloWorld}
@end menu

@node install
@section Compiling and installing the Ovm distribution

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

@example
$ cd @var{OVM-BIN-DIR}
$ @var{OVM-DIR}/configure && make
@end example
   You can also install the runtime files by specifying the @dfn{install}
   target to make. By default this will install @command{gen-ovm} and the runtime 
   files in @file{/usr/local/ovm}. To change the install location use the 
   @option{--prefix} option when running @command{configure}, eg:
@example
$ cd @var{OVM-BIN_DIR}
$ @var{OVM-DIR}/configure --prefix=$HOME && make all install
@end example
   will install @command{gen-ovm} and @command{ovm-config} into
   @file{$HOME/bin}. 

   The value of @option{--prefix} is the @var{OVM-INSTALL-DIR}, and
   the remainder of this example assumes that
   @file{@var{OVM-INSTALL-DIR}/bin} is on your search path.

@node compile
@section Compiling Realtime Java code for use with Ovm

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


Compile HelloWorld.java against the OVM runtime libraries.  With Ovm's
@file{bin} directory on your @samp{$PATH}, do the following:
@example
$ rt=`ovm-config -threads=RealtimeJVM get-string bootclasspath`
$ javac -source 1.4 -target 1.4 -bootclasspath $rt HelloWorld.java
@end example

@strong{NOTE:} It is a current limitation with ovm that all .class
files are generated with the format defined by the @command{javac}
@option{-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.

@node build
@section 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 @var{OVM-EXE-DIR}. Again @var{OVM-EXE-DIR} could
be @var{OVM-DIR}.
@example
$ cd @var{OVM-EXE-DIR}
$ gen-ovm -threads=RealtimeJVM -main=HelloWorld \
          -classpath=@var{CLASSPATH TO @file{HelloWorld.class}}
@end example

Have a cup of coffee while the image is built.

@node run
@section Run the executable
@example
$ cd @var{OVM-EXE-DIR}
@end example

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:

@example
$ ./ovm HelloWorld
@end example
 
Otherwise you pass the ovm executable the name of the image file:
@example
$ ./ovm img HelloWorld
@end example

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:
@example
$ ./ovm `ovm-config get-string image-argument` HelloWorld
@end example

