%% -*- mode: LaTeX -*-
%%
%% Copyright (c) 2002 University of Utah and the Flux Group.
%% All rights reserved.
%% This file is part of the JanosVM documentation.
%% 
%% Permission to use, copy, modify, distribute, and sell this
%% documentation for any purpose is hereby granted without fee,
%% provided that the above copyright notice(s) appear in all copies.
%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{Compiling and Installing \JanosVMplain{}}
\label{cha:Compiling and Installing JanosVM}

\emph{The \file{INSTALL} file in the topmost directory of the \JanosVM{} source
tree contains an abbreviated version of these instructions.}
\par\hspace{0pt}\par\noindent

\JanosVM{} consists of the following programs:

\begin{commandlist}
  \item[\janosvm{}]
  %
  A script that starts up the \JanosVM{} Virtual Machine and executes the Java
  \OS{}'s main class file.

  \item[\java{}]
  %
  Another script that starts up the \JanosVM{} in a mode that emulates a
  typical Java Virtual Machine.

  \item[\kaffeh{}]
  %
  A tool for generating C header files from Java class files.

  \item[\jsihey{}]
  %
  A command line tool that can send and receive \JanosVM{} Scripting Interface
  (\JSI{}) messages.  This is used to communicate with concurrently executing
  virtual machines.

  \item[\jsiregister{}]
  %
  A simple script used in conjunction with \jsihey{} to register a mapping
  between a property for a \JVM{} instance and a value.

  \item[\jsiunregister{}]
  %
  A simple script to unregister an instance or a property mapping.
\end{commandlist}
  

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Acquiring \JanosVMplain{}}
\label{sec:Acquiring JanosVM}

\JanosVM{} is available on the World Wide Web under \jvmurl{}.  Currently,
\JanosVM{} is distributed only as source code.

% XXX Mention other distribution types?

% XXX mention the platforms it works on?



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Building the \JanosVMplain{} Programs}
\label{sec:Building the JanosVM Programs}

In order to build \JanosVM{} from source, you will need:

\begin{commandlist}
  \item[x86 FreeBSD or Linux]
  %
  \Kaffe{} works on a number of platforms, however, we have only concentrated
  on getting \JanosVM{} functioning on x86 based FreeBSD and Linux.  We use
  FreeBSD 4.3 on a Pentium III.

  \item[\gcc{}]
  %
  \Kaffe{} and some of the \JanosVM{} additions make use of \gcc{} language
  extensions so you'll need a recent version to successfully compile
  everything.  We use \gcc{} version 2.95.3.

  \item[\awk{}]
  %
  Some \awk{} scripts are used to automatically generate code.  We use GNU
  \awk{} 3.0.6.

  \item[\textrm{GNU} make]
  %
  We make use of some \gmake{} extensions so regular versions won't work.  We
  use GNU make 3.79.1.

  \item[\textrm{Disk Space}]
  
  The \JanosVM{} source will consume approximately 20\,MB of disk space and a
  typical build tree will consume an additional 30\,MB of space.
\end{commandlist}

% XXX note that cross-compiling, or compiling to use OSKit/Moab is
% much more complicated and is detailed... elsewhere.

Once you have the above-listed tools, you will need to
%
\begin{inparaenum}[(1)]
  \item unpack the \JanosVM{} source distribution \program{tar} file and
  \item create a build tree to contain the object files.
\end{inparaenum}
%
Assuming that you did these things in your home directory, your directory setup
would look something like this:

\begin{filelist}
  \item[\~{}/janosvm-\jvmversion{}/] The \JanosVM{} source tree, unpacked from
  \filefont{janosvm-\jvmversion{}.src.tar.gz}.

  \item[\~{}/obj/] The directory you create to be the root of your \JanosVM{}
  object tree.  (Of course, you can call this directory anything you like.  It
  does not have to be called \file{obj}.)
\end{filelist}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Configuring \JanosVMplain{}}
\label{subsec:Configuring JanosVM}

Given the directory setup described in \autoref{sec:Building the JanosVM
Programs}, you would type the following commands to configure \JanosVM{} for
your operating system:

\begin{transcript}[commandchars=\\\{\}]
cd ~/obj
../janosvm-\jvmversion{}/configure
\end{transcript}

The \program{configure} script in the root of the \JanosVM{} source tree is an
ordinary \program{configure} script, generated by \GNU{} \program{autoconf}.
Type ``\texttt{configure~--help}'' to see all of the script's command line
options.  In addition to all of the standard options accepted by
\program{autoconf}-generated scripts, \JanosVM{}'s \program{configure} script
accepts the following \Kaffe{} and \JanosVM{}-specific options:

\begin{optionlist}
  \item[--with-staticlib]
  %
  Causes all of the \Kaffe{}/\JanosVM{} libraries to be statically linked,
  which includes the libraries that make up the \JVM{} and the native
  implementations of some Java classes.

  \item[--with-staticbin]
  %
  Same as the above, but also statically links system libraries.

  \item[--with-staticvm]
  %
  Causes all of the libraries which make up the \JVM{} to be statically linked,
  but the native implementation of some Java classes are still dynamic.

  \item[--enable-debug]
  %
  Enable run-time debugging machinery.

  \item[--disable-debug]
  %
  Disable assertion checking (but not -g).

  \item[--enable-xprofiling]
  %
  Enable profiling for jitted code.  You can also specify --with-profiling to
  generate a profile that covers both types of code.

  \item[--enable-xdebugging]
  %
  Enable debugging symbol generation for jitted code.  This is useful when
  debugging programs through \gdb{} since you can get proper line number
  information when doing a back trace.

  \item[--with-profiling]
  %
  Compile with gprof(1) profiling support.
\end{optionlist}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Compiling \JanosVMplain{}}
\label{subsec:Compiling JanosVM}

Finally, you are ready to compile the \JanosVM{}!  Simply type the following
commands to build \JanosVM{} and its auxiliary programs:

\begin{transcript}
cd ~/obj
make all
\end{transcript}

Assuming all goes well, these commands should produce all of the \JanosVM{}
programs that need to be compiled.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Checking and Installing \JanosVMplain{}}
\label{subsec:Checking and Installing JanosVM}

Once the system has been compiled you'll want to run the test suite to make
sure everything is working properly:

\begin{transcript}
cd ~/obj
make check
\end{transcript}

There are actually two series of tests that will be run.  The first is the
standard kaffe test suite which verifies the ability to execute Java bytecodes
and the second suite will verify the \JanosVM{} specific extensions.  Of
course, if one of the tests does fail, we'd appreciate it if you'd send the
\file{.fail}(s) file located in the \file{test/regression} or
\file{test/janosvm} directories of the build tree, along with the usual system
information.

Finally, if everything is working well enough you can install the system by
executing:

\begin{transcript}
cd ~/obj
make install
\end{transcript}

Now, you'll probably want to try out the tutorial in the following sections.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Related Software}
\label{sec:Related Software}

If you're interested in running the \JanosVM{} on a bare machine there are a
few of software packages that can be used in conjunction with the \JVM{}.
First, the \OSKit{} package provides much of the infrastructure needed to
initialize and interact with a x86 based PC.  A tarball and build instructions
can be obtained from \oskiturl{}.  Second, our NodeOS implementation, \Moab{},
maps the \OSKit{}'s interfaces to an interface that \JanosVM{} can be
configured to use.  Next, the \jnodeos{} makes the NodeOS interfaces available
to regular Java programs.  And finally, there are a collection of
``meta-makefiles'' and instructions for automating the process of combining all
the components together into a single system.  These last packages can be
obtained from \janosurl{}.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%% End of file.

