@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} into @file{$HOME/bin}. 

   The value of @option{--prefix} is the @var{OVM-INSTALL-DIR}.

@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:
@example
$ javac -target 1.1                                      \
        -bootclasspath @var{OVM-JAR-DIR}/ovm_rt_user.jar \
        HelloWorld.java
@end example
The @var{OVM-JAR-DIR} depends on where you built ovm and where you
installed it.

@strong{NOTE:} if you build a real-time application then add
ovm_rt_user_realtime.jar to the bootclasspath.

@itemize @bullet
@item If you built, but did not install ovm then @var{OVM-JAR-DIR} is:
          @file{@var{OVM-BIN-DIR}/src/syslib/user}.
@item If you installed ovm, using @code{make install} then @var{OVM-JAR-DIR} is:
      @file{@var{OVM-INSTALL-DIR}/ovm/classes}.
@end itemize

@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.1} option. Failure to do this may result in runtime
exceptions, or crashes, due to missing fields or methods.

@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}
$ @var{OVM-BIN-DIR}/bin/gen-ovm -main=HelloWorld \
                -classpath=@var{CLASSPATH TO @file{HelloWorld.class}}
@end example
If you installed ovm then you could use @var{OVM-INSTALL-DIR}/bin/gen-ovm

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.
