<HTML>
<HEAD>
   <TITLE>Release notes for the javadt debugger</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<H1>Release notes for the javadt debugger</H1>

<P>
As a demonstration of the 
<A HREF="http://java.sun.com/j2se/1.4/docs/guide/jpda/architecture.html">
Java<sup><font size=-2>TM</font></sup> Platform Debugger Architecture</A>
we are providing source code for
a simple GUI debugging tool - <b>javadt</b>.  
It is included as an example and demonstration of
<A HREF="http://java.sun.com/j2se/1.4/docs/guide/jpda/architecture.html#jdi">
JDI</A>.  It is not a finished or polished debugger and is
missing many features of importance for real debugging work.
<P>

<H2>Invoking javadt</H2>
<P>
<b>javadt</b> can be run by executing:
<PRE>
   java com.sun.tools.example.debug.gui.GUI &lt;options&gt;.. &lt;class-name&gt;
</PRE>
where &lt;class-name&gt; is the name you would normally
place on the <code>java</code> command line. 
Note: the path to the <A HREF="index.html#SETUP">JDI Library</A> and to 
the compiled <b>javadt</b> class files must be on the class path
used to invoke gui.GUI.
<p>
For example, you can invoke the javadt debugger as follows:
<PRE>
   java com.sun.tools.example.debug.gui.GUI -classpath . Hello
</PRE>
Note: this <code>-classpath</code> option controls the
class path for the <code>Hello</code> application.
Once the window appears, you can issue the 'run' command to begin
execution immediately.  It is also
possible to give the class name in the 'run' command, in
which case it may be omitted when invoking the debugger from the
shell.
<P>
The classpath may also be set from within the debugger, using the
'classpath' command.  Currently, other arguments to the VM must be
given on the shell command line when the debugger is initially
invoked.  The most recently mentioned classpath, VM arguments, main
class name, and program arguments are retained as defaults for later
'run' and 'load' commands.  (Unfortunately, at present, the debugger
will likely crash if you attempt to begin another debugging session
with another debuggee process from within the same invocation of the
debugger.  You should exit to the shell and start a new debugger
process.)
<P>

<H2>Using javadt</H2>
The javadt normally displays context related to the "current thread",
that is, the thread that most recently encountered a breakpoint, threw
an uncaught exception, or was single-stepped by the user.  When
program execution is suspended on account of one of these events, a
current thread exists, and the javadt displays the following information
about it:
<P>
<UL>
<LI>  A stack backtrace.	

<LI>  The source code surrounding the line corresponding to the
      instruction counter for the thread, if the source code is
      available.
</UL>
<P>
In addition, a tabbed pane allows the user to view one of three
additional views:
<P>
<UL>
<LI>  A tree of all source files available on the source path.

<LI>  A tree of all loaded class files, organized hierarchically
      by package.

<LI>  A tree of all active threads, organized hierarchically
      by thread group.
</UL>
<P>
By clicking on the name of a source file, the source view can be
directed to display it.  Likewise, clicking on a thread will make that
thread the current thread.  These features are normally used while the
program is suspended, e.g, at a breakpoint.  Upon resumption and
encountering another breakpoint, for example, the current thread will
be automatically reset and the views will be updated.  The views tile
the javadt display, and are adjustable in size.
<P>
The javadt functionality is rather basic, thus a command-line interaction
window is also provided that allows access to functions that are not
yet exposed in the javadt.  In particular, it is necessary to use the
command line in order to set breakpoints and examine variables. The
javadt debugger command interpreter implements roughly a subset of the
<a href="jdb.html">jdb</a>
 functionality, but adds a few commands of its own.  The
'help' command lists the complete set of commands and their function.
Shortcuts for a set of the most common commands is provided on a
button-bar at the top of the display.
<P>
The program to be debugged may be started either as a child of the
debugger, or the debugger can be attached to an existing process,
provided that its VM is prepared to accept the connection.  If the
debuggee is started by the debugger as a child, a line-oriented
interface to its standard input, output, and error streams is provided
in an application interaction pane.
<P>
The debugger expects to find the program source code on its
sourcepath, set with the 'use' or 'sourcepath' command.  If you find
that sources are not being displayed because the sourcepath is
incorrect, you may change it at that time, and the source view will be
immediately updated.
<P>
The message "No current thread" is often encountered when stepping
through a program.  This message does not mean that the thread or
the VM has died, merely that a current thread is undefined.  This
situation can easily occur unexpectedly when the program being
stepped is waiting, eg., for input.  The VM appears to be stopped,
as it would be after the successful completion of a step, but it
is considered to be "running", not "interrupted".  The prompt
in the command interaction pane indicates the state by changing
to a thread name and frame number when the VM is interrupted.
When it is running, the prompt "Command:" is displayed.
<P>
<H2>Source for javadt</H2>
Full source code for <b>javadt</b> is included under the
<code>debug</code> directory of <code>examples.jar</code>. 
Note: these directories also include the
source for <a href="jdb.html"><code>jdb</code></a>.
Source code for these example applications is included to provide concrete
examples for debugger developers.  Example code may be used, modified
and redistributed by debugger developers providing they adhere to the
terms in the COPYRIGHT notice.
<P>
<b>javadt</b> uses the following packages (found under the
<code>debug</code> directory): 
<DL>
<DT><code>gui</code>
<DD>User interface code
<DT><code>bdi</code>
<DD>Debugger core code
<DT><code>events</code>
<DD>Event Set code
<DT><code>expr</code>
<DD>Expression processing code
</DL>
<P>
<H2>Building javadt</H2>
To build the <b>javadt</b> classes from the 
provided source files under the <code>debug</code> directory, 
you need only to compile them. No special
options are required, aside from those which set your classpath to 
include the <A HREF="index.html#SETUP">JDI Library</A>.
</P>
<P>
However, if you want to modify the expression parser in the file
<code>Expr.jj</code>, you will need the 
<a href="http://www.metamata.com/javacc/">
JavaCC parser generator</a>. 
It is available free from 
<a
href="http://www.webgain.com/products/metamata/java_doc.html">Metamata
(now part of WebGain)</a>.
<P>
    <hr>
    <address><a href="mailto:java-debugger@java.sun.com">java-debugger@java.sun.com</a></address>
    </P>
<P>
</P>
</BODY>
</HTML>