\documentclass{acm-article}

% Begin title and author information (Come up with a better title :)
\title{A Quick Guide to Compiling and Running Ovm}
\author{The Ovm Development Team}
% End title and author information

\begin{document}
\toappear{}
\maketitle

\section*{Requirements for compiling and running Ovm}
Much of the software required to run Ovm is included in the Ovm source.
However, there are some additional hardware and software requirements
to run Ovm, as detailed below.

\subsection*{Hardware} Mac, PPC, or Intel compatible processor systems.
\newline 
\newline {\em N.B.: The JIT is currently only available on Intel systems.}

\subsection*{Software}
\begin{itemize}
  \item Linux or OS/X operating system
  \item Java 1.4 or higher
  \item gcc 3.3
\end{itemize}

All other necessary software should be included with the Ovm source.

\section*{Getting the source}
This section describes how to get the Ovm source via CVS. If you
already obtained the source files via some other means, skip to the next
section ({\em Compiling, Building, and Running Ovm}).

This section does not necessarily assume you have much 
familiarity with CVS, but if you are going to be working on or with OVM, 
it is suggested that you familiarize yourself with  CVS by looking at the 
online documentation at {\em http://www.cvshome.org}.

\subsection*{Anonymous CVS}
To obtain the source via anonymous CVS, enter the following on the command 
line in the directory you want to place your local copy of the source tree:

{\small \texttt{cvs -d :pserver:anonymous@ovmj.org:/var/cvs/OpenVM checkout 
OpenVM}}

\subsection*{CVS access via Purdue (for internal developers)}
For internal developers with CVS access via Purdue CS machines, the Ovm
source is located in the \texttt{/p/sss/cvs/} directory. Assuming your machine
mounts \texttt{/p/sss/cvs/}, the command to check out the source is as follows:

{\small \begin{verbatim}cvs -d /p/sss/cvs checkout OpenVM\end{verbatim}}

If for some reason the machine you're on does not mount /p/sss/cvs, you need
to do the following:

\begin{enumerate}
\item {\small \begin{verbatim}set CVS_RSH=ssh\end{verbatim}}      
\item {\small \begin{verbatim}cvs -d :ext:yourname@xxx.cs.purdue.edu:/p/sss/cvs checkout OpenVM\end{verbatim}}
where {\em xxx} is any machine you can ssh into and that can find 
CVS on your default path.
\end{enumerate}

Regardless of the means used to check out the source, CVS should create a 
directory called \texttt{OpenVM} in the current directory which will contain
all of the current source code. \newline

\section*{Compiling, Building, and Running Ovm}

\subsection*{Setting up the build environment}

Now that you have the Ovm source, you should go into the \texttt{OpenVM} 
directory. In the \texttt{OpenVM} directory, there is a directory called
\texttt{bin} which contains a pair of scripts called \texttt{prepare.csh}
and \texttt{prepare.sh}. The \texttt{.sh} file is for shells that use
Bourne-derived syntax (sh, ksh, bash, etc.). Regardless of which of these
you end up using, you will need to source the script in order to set up all
of the environment variables for the build environment. So, for example, if 
you're using the \texttt{prepare.csh} variant, you should enter the following
from the \texttt{OpenVM} directory:
{\small \begin{verbatim} source bin/prepare.csh\end{verbatim}}

Note that if dependencies are missing or not found, you will get complaints 
either now or during compilation. Additionally, if
you need to use a different version of some piece of software mentioned in
the script than the current defaults in your environment, you may need to
change the script itself. 

{\em Note for those with internal (non-anonymous) access to CVS}: 
It is recommended that you copy the script you need to modify to another file 
named \texttt{myprepare.sh} or \texttt{myprepare.csh} and modify and use that 
file instead of the original, as these are currently ignored by CVS and will 
keep you from accidentally checking in your local modifications to the
original scripts.

The build environment should now be in place.

\subsection*{Preparing applications for the build process}
Because Ovm does not yet have dynamic loading support, applications that will
be run using Ovm must currently be built along with Ovm. This section
describes the steps necessary to prepare applications for later execution with
Ovm. 

% FIXME: Since David mentions that we may be shipping with a set of defaul
%        applications, the next two subsections should perhaps be modified
%        to deal with default apps that we were put into src/apps and
%        automatically include in -udappclasses.

\subsubsection*{Compilation of application code}
Application code should be placed in \texttt{src/apps} in the \texttt{OpenVM}
directory. This code can be compiled using the ant build.xml that is in 
src/apps. The code must be compiled against our runtime libraries in 
ovm\_rt\_user.jar, which is what the build file does. 
The local exclude.xml file can be used to control which application classes 
are built.

\subsubsection*{Location of application classes}
Application ``main'' classes need to be added to the \texttt{-udappclasses} 
list in \texttt{config/s3common}. This can be done either by editing the file, 
or setting the parameter externally (via \texttt{build.parameters}). This step 
tells the image builder to include the named classes as roots in the type 
system.

% FIXME: Is this via build.parameters after all? David wasn't sure in his
%        mail, so check this out.

% BEGIN SCIFI - reflective stuff still isn't possible.

If the application uses any classes only via Reflection 
then that class must also be added to \texttt{-udappclasses}.

Also, if the application invokes any methods only via reflection and 
\texttt{j2c} is to be used, these methods must be listed in
\texttt{-udtargets} in \texttt{config/engine/j2c} using the Ovm selector 
format to name the method.

% END SCIFI

\subsubsection*{Compiling and Building Ovm}

Ovm uses \texttt{ant} for its build process. For documentation on \texttt{ant},
please see {\em http://jakarta.apache.org/ant/manual}.

\texttt{ant} takes a number of different targets, depending on what the user
needs to do. To use \texttt{ant} with a target, simply type 
``\texttt{ant} {\em target}'' on the command line, with {\em target} to be 
replaced by one of the targets listed below (more targets are available by
examining the \texttt{build.xml} file in the \texttt{OpenVM} 
directory).\newline

% BEGIN SCIFI - we don't get build the application jar file, but
% David is working on that.

Running \texttt{ant ovm.all} in the \texttt{OpenVM} directory will build the 
entire system including the application jar file. \footnote{See Appendix A
for other target information}. What gets built depends on two 
things: 

\begin{itemize}
\item the configuration of the build
\item which execution engine to use
\end{itemize}

The default build configuration is for Real-Time JVM applications, and the
default execution engine is \texttt{j2c}. Changes can be made in the defaults
by editing the configuration files. {\em FIXME: Which config files need to be
editted?}

% END SCIFI

\subsubsection*{Running Ovm}

% BEGIN SCIFI - relies on the command-line arg passing being set up. David is
% working on that too - at least a temporary solution.

\begin{verbatim}
   cd <engine-dir>
   ./<ovm_executable> [ovm-options] <image_file_name> \
     <application_class> [application_options]
\end{verbatim}

The engine-dir, ovm-executable and image\_file\_name all depend on which
engine was built.

% END SCIFI

\appendix

\section*{Appendix A: Additional build targets} \label{targets}

The available targets are as follows:

\begin{description}
\item[ovm.build] - compiles Java and AspectJ code for the Ovm kernel.
\item[ovm.syslib] - compiles the kernel and user versions of the Java runtime
library when the property \texttt{ovm.syslib.autobuild} is set. To actually
build the user-level class library, check out the gnu-classpath project, set
the environment variable \texttt{CLASSPATH\_HOME} to its base working
directory, and run ant in \texttt{src/syslib/usr}.
\item[ovm.makeimage] -  depends on both of the above. This target runs 
\texttt{bin/makeImage.sh} to create an initial heap image, along with support 
files needed by the execution engine (either the interpreter or simplejit). 
{\em N.B.: \texttt{ovm.makeimage} is driven out of date each time aspect files 
are compiled, and aspect files are compiled each time \texttt{ovm.build} is
run.}
\item[ovm.all] - depends on \texttt{ovm.makeimage} and performs any necessary
steps to finish building the execution engine. Currently, this target only
performs actions when the interpreter is enabled. The actions in this target
first ensure that files in \texttt{src/native/intepreter} such as 
\texttt{Makefile}, \texttt{configure}, and \texttt{Makefile.in} are up-to-date,
and then \texttt{make} is invoked.
% FIXME: The next one, as listed in the Compiling OVM docs, seems a little
%        uncertain. Fix and uncomment as necessary.
% \item[ovm.run] - er... FIXME. runs the Ovm. To run the Ovm manually, go to the
% \texttt{src/native.interpreter} directory and run the \texttt{.\/interpreter} 
% image.
\item[ovm.test] - tries to use \texttt{JUnit} to run all of the tests in the
\texttt{src/test} directory (and subdirectory). It runs these hosted under
the JDK. To run the OVM in a self-hosted configuration, cd to 
\texttt{src/native/interpreter}, and execute \texttt{interpreter img}. 
\newline \newline
When you execute \texttt{interpreter img} you execute whatever code was 
defined in \texttt{s3.core.S3Executive.startup}. Whether or not this includes 
any tests depends, of course, on what that method contains.
\item[doc] - builds the javadoc documentation for Ovm. This documentation
is placed in the \texttt{doc/javadoc} directory.
\end{description}

Consult the default \texttt{build.parameters} file in the \texttt{OpenVM} 
directory for more information.

\end{document}