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