| <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 <options>.. <class-name> |
| </PRE> |
| where <class-name> 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> |