%% -*- 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{Using \JanosVMplain{}}
\label{cha:Using JanosVM}

\JanosVM{} executes Java bytecodes in one of two environments:

\begin{itemize}
  \item The Java Operating System substrate mode which causes the \JVM{} to
  enable many of the internal features that make it possible to implement a
  high level Java \OS{}.  This is activated by running the \janosvm{} script
  which uses the \file{JanosVM.jar} file.

  \item The Java Virtual Machine emulation mode which causes the \JVM{} to
  behave like a version of \Kaffe{}.  This is activated when running the
  \java{} script which uses the \file{Klasses.jar} file.
\end{itemize}

We'll concentrate on the substrate mode in this document, since that is what
you will be using most of the time, however, the emulation mode can be useful
for testing purposes.

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

\section{The \textnormal{\texttt{janosvm}} Virtual Machine}
\label{sec:The janosvm Virtual Machine}

Starting up a \JanosVM{} instance using the \janosvm{} script requires either a
Java class file and/or the \option{-jsiprovider} and \option{-noexit} options.
The first method depends on the class to initialize the kernel of the Java
\OS{} and construct some communication path for the user to interact with the
\JVM{}.  While the second method starts the \JVM{} as a daemon and uses the
built in \JanosVM{} Scripting Interface (\JSI{}) to facilitate communication
with the user.  The rest of the command line options are described in the next
section.

% XXX is there any inherent reason why the JSI provider couldn't be a
% pure Java applicaton?  Can JSIHey do anything that an app can't do?

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

\subsection{Command Line Options}
\label{subsec:Command Line Options}

The command line options to \java{} and \janosvm{} are as follows:

\begin{optionlist}
  \item[-help]
  %
  Give a short usage message.

  \item[-version]
  %
  Print the version number.

  \item[-fullversion]
  %
  Print verbose version info.

  \item[-ss size]
  %
  Set the maximum stack size to \emph{size}.

  \item[-ms size]
  %
  Set the initial heap size to \emph{size}.

  \item[-mx size]
  %
  Set the maximum heap size to \emph{size}.

  \item[-as size]
  %
  Set the heap increment to \emph{size}.

  \item[-classpath path]
  %
  Override the default search path for class files with \emph{path}.

  \item[-addclasspath path]
  %
  Appends the given \emph{path} to the current classpath setting. Multiple
  instances of this flag may be given.

  \item[-D\emph{property}=\emph{value}]
  %
  Set \emph{property} to the given \emph{value}.  Some properties are used by
  the \JVM{} at startup.  All can be fetched at runtime through the method
  \javaid{System.getProperty()}.

  \item[-noverify]
  %
  Do not verify any bytecode.

  \item[-noclassgc]
  %
  Disable garbage collection of classes.

  \item[-jar]
  %
  Indicates that the main class file name is a \JAR{} file.

  \item[-v]
  %
  Enable verbose output.

  \item[-verbosegc]
  %
  Print messages during garbage collection.

  \item[-verbosejit]
  %
  Print messages during JIT code generation.

  \item[-verbosemem]
  %
  Print detailed memory allocation statistics.

  \item[-vmstats flag\{,flag\}]
  %
  Turn on VM statistcs. Use \option{-vmstats list} for a list of available
  flags.

  \item[-name name]
  %
  Register this \JVM{} instance as \emph{name}.  This is useful when the \JVM{}
  is going to be the target of \JSI{} messages since you can just use the
  registered name instead of a whole protocol and address specification.

  \item[-jsiprovider name]
  %
  Specify where the \JSI{} provider should listen.  The format of \emph{name}
  is a protocol name followed by a colon and then some implementation dependent
  address data.  For example, to listen on \TCP{} port 10000 of the current
  machine (sloane.sd6.gov), you would use \option{-jsiprovider
  tcp:sloane.sd6.gov/10000}.  Currently, only one provider is allowed at a
  time.

  \item[-jsitcpport port]
  %
  Specify a \TCP{} based \JSI{} provider that should listen on \emph{port}.
  Basically, a fast alternative to the above.

  \item[-jsifile file]
  %
  Setup a \JSI{} link through files with \emph{name} as their basename.  This
  option can be used multiple times.

  \item[-config file]
  %
  Use \emph{file} for initial configuration of the \JanosVM{}.

  \item[-noexit]
  %
  The \JanosVM{} continues even if only non-dameon threads are running.  Useful
  for \JSI{}-controlled \JVM{}s that would otherwise exit.

  \item[-vmdebug flag\{,flag\}]
  %
  Enable VM debugging. Use \option{-vmdebug list} to get a list of available
  flags.

  \item[-nodeadlock]
  %
  Disable deadlock detection.

  \item[-Xxprof]
  %
  Enable cross language profiling.  See \file{FAQ/FAQ.xprofiler} for details.

  \item[-Xxprof\_syms file]
  %
  Name of the profiling symbols file.  Defaults to \emph{kaffe-jit-symbols.s}.

  \item[-Xxprof\_gmon file]
  %
  Base name for gmon files. Defaults to \emph{xgmon.out}.

  \item[-Xxdebug]
  %
  Generate a debugging symbols file usable by \gdb{}.  See
  \file{FAQ/FAQ.xdebugging} for details.

  \item[-Xxdebug\_file file]
  %
  Name of the debugging symbols file.  Defaults to \emph{xdb.as}.

  \item[-Xfeedback]
  %
  The file name to write feedback data to.

\end{optionlist}

Besides the command line options, the \JVM{} will read a few environment
variables:

\begin{optionlist}
  \item[CLASSPATH]
  %
  The path used when searching for classes.  In a UNIX system this is a colon
  separated list of paths.

  \item[KAFFE\_DEBUG]
  %
  This indicates that the startup script should execute the \JVM{} in a
  debugger, typically, this is set to \gdb{}.
\end{optionlist}

Once the \JVM{} has been started the user is expected to start and stop
programs using the communication path implemented by the Java \OS{} kernel or
the \JSI{} tools, like \jsihey{}.

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

%% End of file.

