While eclipse cannot be used to debug programs running inside Ovm, it
can be used very effectively to develop ovm code, and debug the Ovm
bootstrapping process.  This chapter describes the best way to set up
Ovm and eclipse to peacefully coexists, a tool
(@command{record-eclipse-launch}) that we provide to automatically add
programs to Eclipses @code{Debug...} and @code{Run...} dialog boxes,
and how this tool can be used to subject Ovm's regression test suite
to debugging.

@menu
* Setup::       Setting up the Eclipse project
* Debugging::   Adding eclipse launch targets for debugging
* Regress::     Debugging the regression test suite
@end menu

@node Setup
@subsection Setting up the Eclipse project

Ovm's makefiles support a number of external tools, including Emacs'
TAG facility, Emacs' JDE extended java mode, and, of course, Eclipse.
Makefile targets are by far the easiest way to create an Eclipse
project.  When @code{make eclipse-dotfiles} is run from the 
@file{src} directory, it creates the required @file{.xml} files in the
toplevel source directory (@file{OpenVM/}).  So, the fastest way to
get up and running with Eclipse is as follows.
@example
./configure && make && make -C src eclipse-dotfiles
@end example

The above command creates @file{.project} and @file{.classpath} files in
the current directory, makes the current directory ready for import.
Once Eclipse's project files have been created, the project can be
imported into your eclipse workspace using 
@code{Import->General->Existing Projects into Workspace}.

If you are doing ovm development, you must also convince Eclipse to
indent your code sanely.  By default, Eclipse places tab stops 4
characters apart, rather than the standard 8, and throws an extra tab
at the front of each line to indent an extra level.  If this is not
corrected, eclipse will not display existing code properly, and will
format lines that you add incorrectly.

The exact steps involved in fixing Eclipse's tab handling seem to vary
from one release to the next, and some releases don't seem completely
fixable.  However, the following works for 3.2.

@enumerate
@item Go to the preference dialog box.
@item In @code{General->Editors->Text Editors}, set 
      @code{Displayed tab width} to 8.
@item Also, check @code{Show print margin} and make sure that the
      margin is 80.
@item In @code{Java->Code Style->Formatter}, hit the edit button.
@item Select the @code{Indentation} tab of the new dialog box.
@item Set @code{Tab policy} to mixed and @code{Indentation size} to
      4.  @code{Tab size} should still be set to 8, and should be
      impossible to change from this tab.
@end enumerate

Note: it may be possible to generate some of these settings from the
makefile.  Someone should do some experimenting here.

@node Debugging
@subsection Debugging

We provide a tool, @command{record-eclipse-launch}, that eases
debugging of Java programs that are started from shell scripts and
take rather complicated argument lists.  By conincidence,
@command{gen-ovm} is a shell script that invokes Java with a rather
complicated argument list.  The following snippet of code defines an
Eclipse configuration for building a hello world program in Ovm.
@example
mkdir ovm-hello; cd ovm-hello
env JAVA=record-eclipse-launch gen-ovm -classpath=.. -main=Hello
@end example

After the above command is run, a configuration called
@samp{ovm-hello} is availble from Eclipse's @code{Run->Debug...}
dialog box.  This configuration captures the current directory and
command line arguments given to record-eclipse-launch.

If Eclipse is able to run Ovm's Java code to completion, you are 90\%
of the way to producing a working hello world executable.  One last
state is needed: @code{make -f OVMMakefile}.

The behavior of record-eclipse-launch is controled by three
environment variables:

@itemize
@item @code{WORKSPACE} is Eclipse's toplevel workspace directory, and is
 defaulted as in eclipse.
@item @code{PROJECT} is the base name of the project being debugged, and
 defaults to the OpenVM source directory name.
@item @code{LAUNCH_NAME} is the name of the configuration in the debug dialog
  box, and defaults to the current directory name
@end itemize

@node Regress
@subsection Debugging the regression test suite

Eclipse can also be used to debug compilation of Ovm's regression test
suite.  For example, the following command can be used to debug
builds using j2c with accurate stack walking enabled:
@example
cd test/
make THREADS=JVM MODEL=AllCopyingThunk-B_Mf_F_H launch
@end example

If that is not enough, @code{make launches} defines an Eclipse
launch configuration for every Ovm configuration that is tested by
@code{make regression-test}.
