Release notes for the javadt debugger

This release of Java^TM Platform Debugger Architecture includes a simple GUI debugging tool - javadt. It is included as an example and demonstration of JDI. It is not a finished or polished debugger and is missing many features of importance for real debugging work.

Invoking javadt

javadt can be run by executing:

   javadt <options>.. <class-name>

where <class-name> is the name you would normally place on the java command line.

For example, you can invoke the javadt debugger as follows:

   javadt -classpath . Hello

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.

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.)

On Windows platforms the executable bin/javadt.exe finds the Java Runtime Environment through the Windows registry. If you installed the 1.2 J2SDK or JRE with the standard installation program, this value should be set correctly for you. If not, you'll need to create/edit the registry entry at HKEY_LOCAL_MACHINE/SOFTWARE/JavaSoft/Java Runtime Environment/1.2/JavaHome containing the name of your JRE directory.

On Solaris platforms the executable bin/javadt finds the Java Runtime Environment through the PATH. The JRE corresponding to the first instance of "java" on the path is the one used.

In addition, javadt can be started by running the 1.2 java VM interpreter of your choice with the class com.sun.tools.example.debug.gui.GUI. Make sure that the jpda.jar file is on the classpath.

Using javadt

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:

A stack backtrace.
The source code surrounding the line corresponding to the instruction counter for the thread, if the source code is available.

In addition, a tabbed pane allows the user to view one of three additional views:

A tree of all source files available on the source path.
A tree of all loaded class files, organized hierarchically by package.
A tree of all active threads, organized hierarchically by thread group.

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.

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 jdb 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.

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.

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.

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.

Source for javadt

Full source code for javadt is included in examples/examples.jar. Note: this also includes the source for jdb. Source code of these example application 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.

Code for javadt is in the directories:

User interface code: src/share/classes/com/sun/tools/example/debug/gui
Debugger core code: src/share/classes/com/sun/tools/example/debug/bdi
Event Set code: src/share/classes/com/sun/tools/example/debug/events
Expression processing code: src/share/classes/com/sun/tools/example/debug/expr

Building javadt

To completely rebuild the javadt classes from the provided source files in examples/examples.jar, you need only to compile them. No special options are required, aside from those which set your classpath to include the com.sun.jdi library found in lib/jpda.jar. However, if want to modify the expression parser in the file Expr.jj, you will need the JavaCC parser generator version 0.7.1. It is available free from SunTest.