1 <HTML>
   2 <HEAD>
   3    <TITLE>Release notes for the javadt debugger</TITLE>
   4 </HEAD>
   5 <BODY BGCOLOR="#FFFFFF">
   6 <H1>Release notes for the javadt debugger</H1>
   7 
   8 <P>
   9 As a demonstration of the 
  10 <A HREF="http://java.sun.com/j2se/1.4/docs/guide/jpda/architecture.html">
  11 Java<sup><font size=-2>TM</font></sup> Platform Debugger Architecture</A>
  12 we are providing source code for
  13 a simple GUI debugging tool - <b>javadt</b>.  
  14 It is included as an example and demonstration of
  15 <A HREF="http://java.sun.com/j2se/1.4/docs/guide/jpda/architecture.html#jdi">
  16 JDI</A>.  It is not a finished or polished debugger and is
  17 missing many features of importance for real debugging work.
  18 <P>
  19 
  20 <H2>Invoking javadt</H2>
  21 <P>
  22 <b>javadt</b> can be run by executing:
  23 <PRE>
  24    java com.sun.tools.example.debug.gui.GUI &lt;options&gt;.. &lt;class-name&gt;
  25 </PRE>
  26 where &lt;class-name&gt; is the name you would normally
  27 place on the <code>java</code> command line. 
  28 Note: the path to the <A HREF="index.html#SETUP">JDI Library</A> and to 
  29 the compiled <b>javadt</b> class files must be on the class path
  30 used to invoke gui.GUI.
  31 <p>
  32 For example, you can invoke the javadt debugger as follows:
  33 <PRE>
  34    java com.sun.tools.example.debug.gui.GUI -classpath . Hello
  35 </PRE>
  36 Note: this <code>-classpath</code> option controls the
  37 class path for the <code>Hello</code> application.
  38 Once the window appears, you can issue the 'run' command to begin
  39 execution immediately.  It is also
  40 possible to give the class name in the 'run' command, in
  41 which case it may be omitted when invoking the debugger from the
  42 shell.
  43 <P>
  44 The classpath may also be set from within the debugger, using the
  45 'classpath' command.  Currently, other arguments to the VM must be
  46 given on the shell command line when the debugger is initially
  47 invoked.  The most recently mentioned classpath, VM arguments, main
  48 class name, and program arguments are retained as defaults for later
  49 'run' and 'load' commands.  (Unfortunately, at present, the debugger
  50 will likely crash if you attempt to begin another debugging session
  51 with another debuggee process from within the same invocation of the
  52 debugger.  You should exit to the shell and start a new debugger
  53 process.)
  54 <P>
  55 
  56 <H2>Using javadt</H2>
  57 The javadt normally displays context related to the "current thread",
  58 that is, the thread that most recently encountered a breakpoint, threw
  59 an uncaught exception, or was single-stepped by the user.  When
  60 program execution is suspended on account of one of these events, a
  61 current thread exists, and the javadt displays the following information
  62 about it:
  63 <P>
  64 <UL>
  65 <LI>  A stack backtrace.  
  66 
  67 <LI>  The source code surrounding the line corresponding to the
  68       instruction counter for the thread, if the source code is
  69       available.
  70 </UL>
  71 <P>
  72 In addition, a tabbed pane allows the user to view one of three
  73 additional views:
  74 <P>
  75 <UL>
  76 <LI>  A tree of all source files available on the source path.
  77 
  78 <LI>  A tree of all loaded class files, organized hierarchically
  79       by package.
  80 
  81 <LI>  A tree of all active threads, organized hierarchically
  82       by thread group.
  83 </UL>
  84 <P>
  85 By clicking on the name of a source file, the source view can be
  86 directed to display it.  Likewise, clicking on a thread will make that
  87 thread the current thread.  These features are normally used while the
  88 program is suspended, e.g, at a breakpoint.  Upon resumption and
  89 encountering another breakpoint, for example, the current thread will
  90 be automatically reset and the views will be updated.  The views tile
  91 the javadt display, and are adjustable in size.
  92 <P>
  93 The javadt functionality is rather basic, thus a command-line interaction
  94 window is also provided that allows access to functions that are not
  95 yet exposed in the javadt.  In particular, it is necessary to use the
  96 command line in order to set breakpoints and examine variables. The
  97 javadt debugger command interpreter implements roughly a subset of the
  98 <a href="jdb.html">jdb</a>
  99  functionality, but adds a few commands of its own.  The
 100 'help' command lists the complete set of commands and their function.
 101 Shortcuts for a set of the most common commands is provided on a
 102 button-bar at the top of the display.
 103 <P>
 104 The program to be debugged may be started either as a child of the
 105 debugger, or the debugger can be attached to an existing process,
 106 provided that its VM is prepared to accept the connection.  If the
 107 debuggee is started by the debugger as a child, a line-oriented
 108 interface to its standard input, output, and error streams is provided
 109 in an application interaction pane.
 110 <P>
 111 The debugger expects to find the program source code on its
 112 sourcepath, set with the 'use' or 'sourcepath' command.  If you find
 113 that sources are not being displayed because the sourcepath is
 114 incorrect, you may change it at that time, and the source view will be
 115 immediately updated.
 116 <P>
 117 The message "No current thread" is often encountered when stepping
 118 through a program.  This message does not mean that the thread or
 119 the VM has died, merely that a current thread is undefined.  This
 120 situation can easily occur unexpectedly when the program being
 121 stepped is waiting, eg., for input.  The VM appears to be stopped,
 122 as it would be after the successful completion of a step, but it
 123 is considered to be "running", not "interrupted".  The prompt
 124 in the command interaction pane indicates the state by changing
 125 to a thread name and frame number when the VM is interrupted.
 126 When it is running, the prompt "Command:" is displayed.
 127 <P>
 128 <H2>Source for javadt</H2>
 129 Full source code for <b>javadt</b> is included under the
 130 <code>debug</code> directory of <code>examples.jar</code>. 
 131 Note: these directories also include the
 132 source for <a href="jdb.html"><code>jdb</code></a>.
 133 Source code for these example applications is included to provide concrete
 134 examples for debugger developers.  Example code may be used, modified
 135 and redistributed by debugger developers providing they adhere to the
 136 terms in the COPYRIGHT notice.
 137 <P>
 138 <b>javadt</b> uses the following packages (found under the
 139 <code>debug</code> directory): 
 140 <DL>
 141 <DT><code>gui</code>
 142 <DD>User interface code
 143 <DT><code>bdi</code>
 144 <DD>Debugger core code
 145 <DT><code>events</code>
 146 <DD>Event Set code
 147 <DT><code>expr</code>
 148 <DD>Expression processing code
 149 </DL>
 150 <P>
 151 <H2>Building javadt</H2>
 152 To build the <b>javadt</b> classes from the 
 153 provided source files under the <code>debug</code> directory, 
 154 you need only to compile them. No special
 155 options are required, aside from those which set your classpath to 
 156 include the <A HREF="index.html#SETUP">JDI Library</A>.
 157 </P>
 158 <P>
 159 However, if you want to modify the expression parser in the file
 160 <code>Expr.jj</code>, you will need the 
 161 <a href="http://www.metamata.com/javacc/">
 162 JavaCC parser generator</a>. 
 163 It is available free from 
 164 <a
 165 href="http://www.webgain.com/products/metamata/java_doc.html">Metamata
 166 (now part of WebGain)</a>.
 167 <P>
 168     <hr>
 169     <address><a href="mailto:java-debugger@java.sun.com">java-debugger@java.sun.com</a></address>
 170     </P>
 171 <P>
 172 </P>
 173 </BODY>
 174 </HTML>