@menu
* User FAQ::            Questions frequently asked by Ovm users.
* Developer FAQ::       Questions frequently asked by Ovm developers.
@end menu

@node User FAQ
@section Questions frequently asked by Ovm users

@menu
@c No frequently asked questions about configure/make yet.
* Config err::  Why does @command{gen-ovm} die with @code{Configuration Error...}?
* Abs meth::    Why does @command{ovm} die with an assertion failure
                complaining about abstract methods? 
* Bin compat::  Why does @command{gen-ovm} report that methods are not found? 
* Unreachable:: Why does @command{ovm} die with an assertion failure
                complaining about a @code{reflective call to
                `unreachable' method}? 
* Clinit::      Why doesn't the above work for a method
                named @code{@var{class}__0003cclinit_0003e_@var{n}}, and
                what is this method anyway?
* NoClassDef::  Why am I getting @code{NoClassDefFoundError} for a class
                that is clearly defined? 
* Strip::       How can I run @command{strip} under Darwin?
* Timers::      How do I enable fine-grained timers under RTLinux?
* librk-rt.a::  OK, how do I link with RTLinux's magic library?
@end menu

@node Config err
@subheading Why does @command{gen-ovm} die with @code{Configuration Error...}?

Image building sometimes fails with the error, @code{Configuration
Error: in @var{calling-class}: invalid configuration of 
@var{base-type}: @var{selected-type} is not a subtype of 
@var{needed-type}.}  This happens when trying to use an incompatible set
build options.  Code in the OVM (@var{calling-class} in particular) needs
additional features from the implemenation of @var{base-type}, but these
features are not provided by the configured implemenation
(@var{selected-type}).  

Common sources of this error include:
@itemize @bullet
@item Using an RTSJ aware GC without RTSJ threads.  This can be fixed
by replacing @code{-model=MostlyCopyingRegions-B_Mf_F_H} with 
@code{-model=MostlyCopyingWB-B_Mf_F_H} or another non-realtime
allocator.
@item Using RTSJ threads with a non-RTSJ aware GC.  This can be fixed by
invoking @command{gen-ovm} with @code{-model=MostlyCopyingRegions-B_Mf_F_H}
or any other realtime allocator.
@item Using a precise GC with a compiler that doesn't support it.  This
can be fixed by selecting an @option{-engine} that supports precise GC
(such as @code{intepreter} or @code{j2c}, or by selecting a
@option{-model} that does not require stack maps (such as
@code{minimalMM-B_Mf}, or one of the @code{MostlyCopying} allocators).
@end itemize

If none of the above apply, your best bet is to grep for @var{base-type}
in the ovm config files.  (By default, these files are installed at 
@file{/usr/local/ovm/config}.)

@node Abs meth
@subheading Why does @command{ovm} die with an assertion failure complaining about abstract methods?

If such an error occurs at runtime, @command{gen-ovm} printed a warning at
at compile time describing the problem in greater detail.  These errors
typically occur in application bytecode due to bugs in Ovm's method
resolution code (see @ref{Bin compat}).

Ovm developers encounter these errors more frequently.  These errors
occur on a call to a VM-internal method that itself calls a method that
only exists at image-build time (inside the @command{gen-ovm} process).
Warnings from @command{gen-ovm} indicate which methods it treats as build
time, and the line number of the method's first build-time call.

@node Bin compat
@subheading Why does @command{gen-ovm} report that methods are not found?

Ovm currently supports Java 1.2 method resolution.  Method resolution
rules have changed in Java 1.5, and this can lead to problems.  
Incompatible versions of the @code{javax.realtime} package can also be
an issue.  Both these problems can be avoided by invoking
@command{javac} more carefully.  @command{javac} should always be
invoked as follows:
@example
javac                        \
  -bootclasspath             \
    /usr/local/ovm/classes/ovm_rt_user_realtime.jar:/usr/local/ovm/classes/ovm_rt_user.jar \
  -source 1.3 -target 1.2    \
  @var{java-files}
@end example
(You may need to change the paths to @file{ovm_rt_user_realtime.jar}
and @file{ovm_rt_user.jar} depending on where, or whether, you chose
to install Ovm.)  No other definitions of @code{javax.realtime} should
be present in @command{javac}'s @option{-classpath} or
@option{-bootclasspath} lists.

Setting the appropriate @option{-bootclasspath} ensures that your code is
compiled against the Ovm's @option{javax.realtime} implemenation, rather
than code that implements another version of the RTSJ, or no version
of the RTSJ at all.

Setting @option{-target} ensures that @command{javac} will generate class
files that Ovm can understand.

@node Unreachable
@subheading Why does @command{ovm} dies with an assertion failure complaining about a @code{reflective call to `unreachable' method}?

The current version of J2c requires complete knowledge of reflection at
image-build time.  Every method that is invoked reflectively must be
listed in the @option{-ud-reflective-methods} switch.

   Building up this list can be extremely tedious, so we provide two
alternatives:
@itemize @bullet
@item The build-time option @option{-reflective-method-trace=@file{file}}
   can be used with the interpreter or simplejit to dump a list all methods
   invoked reflectively in the named file.  When collecting these
   traces, you should be careful to excersize all code paths that may
   lead to a reflective all.  Once a complete list of reflective method
   invocations is built, it can be fed back into ovm with
   @code{gen-ovm -engine=j2c -ud-reflective-methods=@@@file{file}}.

   A method will only be listed once on each JVM run, but since the OVM
   appends to this file, one can accumulate a list of methods invoked
   across multiple runs.  When collecting traces across multiple runs,
   it may be a good idea to run @code{sort -u}.

@item @option{-app-methods-live} forces j2c to treat all methods defined
   by the application classloader as possible targets of reflective
   invocation.  Since this option increases build time, bloats the
   boot image, and inhibits optimization, it should be used with
   caution. @strong{NOTE:} @option{-app-methods-live} has no effect in
   combination with @option{-opt=run}.
@end itemize

@node Clinit
@subheading Why doesn't the above work for a method named @code{@var{class}__0003cclinit_0003e_@var{n}}, and what is this method anyway?

The latter question is the key one: @code{_0003cclinit_0003e_}
corresponds to a @code{<clinit>} method in Java bytecode, and this
method contains @var{class}'s static initializers.@footnote{Note the sequence
of two @samp{c}s.  These methods should not be confused with
constructors named @code{@var{class}__0003cinit_0003e_@var{n}}.
@xref{gdb Tutorial}, in the manual for a more complete description of j2c's naming
conventions.}  Static initializers are not explicitly invoked through
Java reflection, but may be implicitly invoked through
@code{Class.forName()}.  See @ref{NoClassDef} for ways to ensure that a
class, and its static initializers are included in an Ovm image.

@node NoClassDef
@subheading Why am I getting @code{NoClassDefFoundError} for a class that is clearly defined?

Typically, this error occurs when a class @var{C} is only referenced
through @code{Class.forName()} calls or @code{@var{C}.class}
expressions, but this error may also come up if the standard library
uses @code{Class.forName()} incorrectly.  If @code{u1_@var{C}} does not
appear in @file{structs.hh}, gen-ovm must be explicitly told to include
@var{C} with the @option{-ud-reflective-classes} option.

As with @option{-ud-reflective-methods}, Ovm provides a couple ways to
build this list automatically.
@itemize @bullet
@item @option{-app-classes-live} forces the OVM to treat all classes
   defined by the application classloader as possible targets of
   @code{forName()} calls.  Since this option increases build time,
   bloats the boot image, and inhibits optimization, it should be used
   with caution.  @strong{NOTE:} @option{-app-classes-live} has little
   effect in combination with @option{-opt=run}.

@item @option{-reflective-class-trace=@file{file}}
   can be used in combination with @option{-app-classes-live} to
   collect a list of class names that are passed to @code{forName()} at
   runtime.  The complete list can be fed back to @command{gen-ovm} with
   @option{-ud-reflective-classes=@@@file{file}}.

   A class will only be listed once on each JVM run, but
   since the OVM appends to this file, one can accumulate a list of
   classes invoked across multiple runs.  When collecting traces
   across multiple runs, it may be a good idea to run @code{sort -u}.
@end itemize

@node Strip
@subheading How can I run @command{strip} under Darwin?

  In some configurations, ovm generates absolute symbols that point
  into the initial heap image.  For some reason, MacOS's ld does not
  relocate references to these symbols.  `strip -ruA' will strip all
  symbols that are not needed at runtime.

@node Timers
@subheading How do I enable fine-grained timers under RTLinux?

OVM uses a default timer interrupt rate of 10ms. This affects all timed
operations, such as sleeps, waits, RTSJ periodic thread release, and
RTSJ timers. The timer interrupt rate can be set at runtime using the
@option{-period} runtime argument:
@example
./ovm -period=@var{nnn} @var{<main class name> <args>}
@end example
where @var{nnn} is a value in microseconds. The requested value will be
rounded up to a multiple of the supported underlying timer resolution. A
warning is printed if you ask for a timer interrupt rate that is shorter
than the supported timer resolution, but no warning is printed if the
rate needs to be rounded up.  OVM reports the actual timer interrupt
rate being used at start-up time.

On the majority of Linux systems the supported timer resolution is
10ms. This cannot be changed. Apparently in 2.6 kernel Linux systems
this will reduce to 1ms. When running on the licensed Timesys Linux RT
system a high resolution implementation of the POSIX real-time timers is
available, with a resolution of 1us. To use these timers you must ensure
that the Timesys library, @file{librk-rt.a}, is available by setting the
@env{LIBRARY_PATH} environment variable when running configure, and when
building the OVM and an OVM image.

@node librk-rt.a
@subheading OK, how do I link with RTLinux's magic library?

First you must have the licensed version of Timesys Linux RT, not the
GPL version. If you can find @file{librk-rt.a} then you have the licensed
version.

Second, @file{librk-rt.a} must be locatable by @command{ld} when the
@command{configure} script runs and when building the OVM and any image. To
do this either @file{librk-rt.a} must be in the default location looked
in by @command{ld} (which is @file{/usr/lib} normally) or you must set the
@env{LIBRARY_PATH} environment variable to point to the directory where
@file{lbrk-rt.a} is located. Check the @file{config.log} file to see if
@command{ld} was able to find the library when @command{configure} ran. Check
the build output to see if @option{-lrk-rt} is being passed as a link
option.

You might be tempted to edit @file{ld.so.conf} instead of setting
@env{LIBRARY_PATH}.  This is a bad idea.  @file{ld.so.conf} tells
@command{ld.so} where to find dynamically loaded libraries at runtime.  You
need to tell @command{ld} where to find the statically linked
@file{librk-rt.a} library at link time - the only way to do this (apart
from recompiling @command{ld}) is to set the @env{LIBRARY_PATH} environment
variables (@strong{NOTE}: this is not @env{LD_LIBRARY_PATH} which is
again telling @command{ld.so} how to dynamically load libraries at
runtime.)

@node Developer FAQ
@section Questions frequently asked by Ovm developers

@menu
* Eclipse::         How can I use Eclipse on Ovm source code?
* JDE::             How can I use JDE on Ovm source code
* Quick Test::      How can I run tests manually?
* Regression Test:: How are tests run automatically?
* Benchmarks::      How are benchmarks run automatically?
* Anonymous CVS::   How is the anonymous CVS repository updated?
* Web Docs::        How is documentation on @uref{http://www.ovmj.org} updated?
@end menu

@node Eclipse
@subheading How can I use Eclipse on Ovm source code?

@xref{Eclipse Support}, in the manual for details.

@node JDE
@subheading How can I use JDE on Ovm source code?

@xref{JDE Support}, in the manual for details.

@node Quick Test
@subheading How can I run tests manually?

By running @command{make} in the test directory, of course.
@itemize @bullet
@item @code{make} will compile and run the standard tests in the default
configuration
@item @code{make ENGINE=@var{e} MODEL=@var{m} THREADS=@var{t}} will
compile and run the configuration defined by @var{e}, @var{m}, and
@var{t}.
@item @code{make regression-test} will run through the entire test suite
(which currently includes 19 configurartions).
@end itemize

@node Regression Test
@subheading How are tests run automatically?

They are run on @code{aardvark.cs.purdue.edu} as the @code{ovm}
psuedo-user.  If all tests pass, I delete the entire OpenVM tree.  Otherwise, I
delete the VM-gen directories of all passing configurations.  (These
img files really eat up space.)  If you are Fil and you are lucky (an
unlikely combination), some impossible-to-reproduce bug has resulting
in a j2c core dump during automated testing.  You can now:
@example
me@@here> ssh aardvark
me@@aardvark> sudo -u ovm bash
password: @var{your own password}
ovm@@aardvark> cd /scrach/ovm/OpenVM-@var{YYYYMMDDHH}00/test/build-@var{failed-test}
ovm@@aardvark> gdb ovm core.@var{NNNN}
@end example

@node Benchmarks
@subheading How are benchmarks run automatically?

Benchmarks are run on @code{cordelia} by @code{RTJUnit}.  To get a
better idea of what's going on, check out a copy of @code{RTJUnit} from
@file{/p/sss/cvs}, and take a look at @file{RTJUnit/scripts/}.
RTJUnit's cron jobs updated themselves from CVS, so any changes that are
committed to the cvs tree will become part of the benchmark run within a
day or two.

@node Anonymous CVS
@subheading How is the anonymous CVS repository updated?

The anonymous CVS repository available at @code{ovmj.org} is a mirror of
the live repository at @file{/p/sss/cvs}.  The mirror is updated nightly
in a cron job run by @code{ovm@@aardvark}.

@node Web Docs
@subheading How is the documentation on @code{ovmj.org} updated?

Manually, through the makefiles.  On a Purdue machine:
@example
make weball && sudo -u ovm make webinstall
@end example
will update the javadoc, the manual, and this FAQ.

If you want to update other parts of @url{http://www.ovmj.org}, you can
commit changes to the @code{OpenVMDoc} cvs repository, and wait for a
cron job to propagate the changes to @code{ovmj.org}

@ignore
The following appeared in FAQ.txt, but may no longer be needed:
* Who should read this document?

  This document is useful primarily to core Ovm developers, and anyone
  else who wants to develop code for Ovm.  If you are more
  interested in actually using Ovm, you are more likely to find
  the answers your are looking for by running gen-ovm -help, or
  reading doc/texdoc/debug/debug_ovm.pdf. (Assuming that you've
  already run make -C doc/texdoc/debug.) 

* What versions of tools do I need?

  You need a Java 1.4 compiler (javac) and JVM to build the image. We have
  used Sun's JDK's for Linux, and the supplied JDK on Mac OSX.

  You need gcc 3.x

  You need a binutils version >= 2.14.90.0.6-4 (There is a G++ bug that can 
  occur with static linking that results in the G++ exception processing code 
  seg-faulting.)


* configure, make, gen-ovm, and you:

  In  order to  build Ovm  you should  make sure  to understand  a  few things.
  Firstly, the build to four kinds of locations:

   	- the source directory is where the CVS checkout lives
	- the build directory is where compilation happens
	- the install directory contains a compiled verion of Ovm
	- the directory in which gen-ovm runs is where a VM is built

  When developing Ovm, one is tempted to think of it as a collection
  of tests that can be run in various environments.  However, Ovm
  is being used to create Virtual Machines for more-or-less real
  applications.  Our build system no longer generates a VM after
  compiling all the Ovm source code, because these are really two
  different activities.  We also provide a mechanism to install
  gen-ovm (along with Ovm's various libraries and jar files) to
  completely seperate VM generation from compilation of the Ovm
  itself. 

  Like other UNIX software, Ovm can be compiled outside of it's source
  directory.  This is done by choosing a build directory, switching to it,
  and running Ovm's configure script.  Configure will generate a number of
  makefiles in this directory that can be used to compile Ovm.

  A seperate build directory comes in handy when interacting with tools such
  as CVS.  And, in systems that support a number of build-time options,
  maintaining several build directories can be useful.  Ovm, however, is  not such a system.  Ovm is a tool for configuring and generating
  virtual machines.  As such, it delays configuration choices until the time
  when a virtual machine machine is generated.

  Ovm can be installed in a permanent home.  After you've run `make
  install', you can delete the source and build directories, yet continue to
  generate virtual machines by running /usr/local/bin/gen-ovm (or
  /somewhere/bin/gen-ovm if you install Ovm to /somewhere).

  Finally, whether you have decided to install Ovm or not, you can use
  it to generate virtual machines.  This is done through the gen-ovm
  command, which is strikingly similar to the last version of
  makeImage.sh, but not tied to the Ovm source directory.  Like
  `configure && make', gen-ovm will configure and build a peice of
  software (a virtual machine based on the Ovm), and dump the results
  in the curent directory.

  I'd like to say that a virtual machine generated by Ovm is not a part
  of Ovm itself, but this leads to copyright questions that I'd rather
  not think about.  If you worry about copyright questions, stare at the file
  COPYING for a while.

  Intellectual property questions aside, it is fair to say that Ovm can
  be used to generate Java Virtual Machines with a variety of
  characteristics, and that some (by which I mean all) of these JVMs are
  specialized to a particular application.


* The new build system

  There are references to a new build system in the documentation and in the
  mail archive, what is it? You are looking at it. There used to be an "old"
  build system but it is no more.

* I get a "install: mkdir /usr/local/ovm: Permission denied" after typing
  "make all install"

     You forgot to give a --prefix=$DIR option when configuring the ovm and
     your /usr/local directory is not writeable. Specifying a different
     install directory will work. This can be done, for example, with
     "configure --prefix=/tmp/ovminstall".

	   
* Where does the prefix value end up being stored?

     Funny you should ask. But if you really want to know in
     compile/build/Vars.mk



* Do I need to install?

  No. Not if you need to ask.



* How do I build a plain Java VM?

  After having compiled everything, type:

	bin/gen-ovm  -threads=JVM \
		     -model=SimpleSemiSpace-B_M_F_H \
	             -classpath=PATH \
                     -main=MAIN

  Where PATH is the path from the current directory of you MAIN.class 
  file.


* How do I build a RTJVM?

  Here is one way:

       bin/gen-ovm  -threads=RealtimeJVM                     \
                    -model=MostlyCopyingRegions-B_M_F_H      \
	            -classpath=PATH \
                    -main=MAIN

  Where PATH is the path from the current directory of you MAIN.class 
  file.

* Where do I control the exclude list for the core packages in GNU Classpath
  that get put into ovm_rt_user.jar?

  OpenVM/src/syslib/user/Makefile.mk

  Note that classes in excluded packages will still be dragged into the
  image is referenced directly from an included class.


* There are no Objects in my Domain!

  The Ovm image build process prints the following:

      # Log:  Found 647460 objects in domain ExecutiveDomain
      # Log: Done computing Object Graph
      # Log: second domain ...
      # Log:  Found 0 objects in domain UserDomain_1

  Does that mean anything? The ExecutiveDomain is the kernel of the virtual
  machine, it contains all the types, byte code, and other internal data
  structures and has thus the unfortunate tendency to bloat. The UserDomain
  represent the portion of the VM where user code will run (here "_1" says
  that this is the first user domain, we plan to allow for multiple domains
  to coexist). The reason that there are no objects in it is simple -- user
  objects are only created when the VM machine is run.

**Developping in Ovm**

* How do I create a new Type.Array type?

 Type.Array is implemented by S3Type.Array in the current Ovm library. (There
 may  be other implementations  but this  is future  work).  Array  types are
 singletons  in the  sense  that we  ensure  that there  is  only one  object
 representing a logical array type. Thus you should not create an instance of
 Array type yourself.  For a given TypeName.Array there can  be only one Type
 object per Context.

 Given  some innermost  type (which  should  not be  an array  type), and  an
 instance of Context do:

   TypeName tn = TypeName.Array.make( innermost.getUnrefinedName(), i);
   Type arr    = context.typeFor( tn);

* Why is there a configuration error for SimpleJIT at LocalReferenceIterator?

  I get the following error message in the log:

    Configuration Error: in s3.core.services.memory.S3VMInterface: \
    no implemenation defined for s3.core.services.memory.LocalRefer\
    enceIterator$Factory

  What is happening here is that the InvisibleStitcher is reflectively
  looking for a class that implements the Factory and there is none for
  SimpleJIT. This occurs when using a SimpleSemiSpace collector as in:

    bin/gen-ovm -engine=simplejit -threads=JVM -model=SimpleSemiSpace-B_M_F_H\
                -classpath=. -main=HW

  Use:  "-model=MostlyCopying-B_M_F_H" and all will be well.

* Why can't I create type during image geeneration?

  I was building a j2c image and got the following error message, what does
  it mean?

     ovm.util.OVMError: Could not create type [Ljava/lang/Comparable;

  The image build process freezes the Repository after all types have been
  instantiated. The j2c compiler called a method that required an array type
  which was not present when the Repository was frozen, one of the side
  effects of the method is to try to create the missing type. 
@end ignore
