Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / libcore / 319a3b994703aac84df7bcde272adfcb3cdbbbf0 / . / jdk / src / share / classes / com / sun / tools / example / doc / javadt.html
blob: f9d28a166bba1cd6311e907f8f5765b19700a5d4 [file] [log] [blame]
J. Duke319a3b92007-12-01 00:00:00 +0000[diff] [blame^]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>
9As a demonstration of the
10<A HREF="http://java.sun.com/j2se/1.4/docs/guide/jpda/architecture.html">
11Java<sup><font size=-2>TM</font></sup> Platform Debugger Architecture</A>
12we are providing source code for
13a simple GUI debugging tool - <b>javadt</b>.
14It is included as an example and demonstration of
15<A HREF="http://java.sun.com/j2se/1.4/docs/guide/jpda/architecture.html#jdi">
16JDI</A>. It is not a finished or polished debugger and is
17missing 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>
26where &lt;class-name&gt; is the name you would normally
27place on the <code>java</code> command line.
28Note: the path to the <A HREF="index.html#SETUP">JDI Library</A> and to
29the compiled <b>javadt</b> class files must be on the class path
30used to invoke gui.GUI.
31<p>
32For example, you can invoke the javadt debugger as follows:
33<PRE>
34 java com.sun.tools.example.debug.gui.GUI -classpath . Hello
35</PRE>
36Note: this <code>-classpath</code> option controls the
37class path for the <code>Hello</code> application.
38Once the window appears, you can issue the 'run' command to begin
39execution immediately. It is also
40possible to give the class name in the 'run' command, in
41which case it may be omitted when invoking the debugger from the
42shell.
43<P>
44The classpath may also be set from within the debugger, using the
45'classpath' command. Currently, other arguments to the VM must be
46given on the shell command line when the debugger is initially
47invoked. The most recently mentioned classpath, VM arguments, main
48class name, and program arguments are retained as defaults for later
49'run' and 'load' commands. (Unfortunately, at present, the debugger
50will likely crash if you attempt to begin another debugging session
51with another debuggee process from within the same invocation of the
52debugger. You should exit to the shell and start a new debugger
53process.)
54<P>
55
56<H2>Using javadt</H2>
57The javadt normally displays context related to the "current thread",
58that is, the thread that most recently encountered a breakpoint, threw
59an uncaught exception, or was single-stepped by the user. When
60program execution is suspended on account of one of these events, a
61current thread exists, and the javadt displays the following information
62about 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>
72In addition, a tabbed pane allows the user to view one of three
73additional 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>
85By clicking on the name of a source file, the source view can be
86directed to display it. Likewise, clicking on a thread will make that
87thread the current thread. These features are normally used while the
88program is suspended, e.g, at a breakpoint. Upon resumption and
89encountering another breakpoint, for example, the current thread will
90be automatically reset and the views will be updated. The views tile
91the javadt display, and are adjustable in size.
92<P>
93The javadt functionality is rather basic, thus a command-line interaction
94window is also provided that allows access to functions that are not
95yet exposed in the javadt. In particular, it is necessary to use the
96command line in order to set breakpoints and examine variables. The
97javadt 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.
101Shortcuts for a set of the most common commands is provided on a
102button-bar at the top of the display.
103<P>
104The program to be debugged may be started either as a child of the
105debugger, or the debugger can be attached to an existing process,
106provided that its VM is prepared to accept the connection. If the
107debuggee is started by the debugger as a child, a line-oriented
108interface to its standard input, output, and error streams is provided
109in an application interaction pane.
110<P>
111The debugger expects to find the program source code on its
112sourcepath, set with the 'use' or 'sourcepath' command. If you find
113that sources are not being displayed because the sourcepath is
114incorrect, you may change it at that time, and the source view will be
115immediately updated.
116<P>
117The message "No current thread" is often encountered when stepping
118through a program. This message does not mean that the thread or
119the VM has died, merely that a current thread is undefined. This
120situation can easily occur unexpectedly when the program being
121stepped is waiting, eg., for input. The VM appears to be stopped,
122as it would be after the successful completion of a step, but it
123is considered to be "running", not "interrupted". The prompt
124in the command interaction pane indicates the state by changing
125to a thread name and frame number when the VM is interrupted.
126When it is running, the prompt "Command:" is displayed.
127<P>
128<H2>Source for javadt</H2>
129Full source code for <b>javadt</b> is included under the
130<code>debug</code> directory of <code>examples.jar</code>.
131Note: these directories also include the
132source for <a href="jdb.html"><code>jdb</code></a>.
133Source code for these example applications is included to provide concrete
134examples for debugger developers. Example code may be used, modified
135and redistributed by debugger developers providing they adhere to the
136terms 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>
152To build the <b>javadt</b> classes from the
153provided source files under the <code>debug</code> directory,
154you need only to compile them. No special
155options are required, aside from those which set your classpath to
156include the <A HREF="index.html#SETUP">JDI Library</A>.
157</P>
158<P>
159However, 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/">
162JavaCC parser generator</a>.
163It is available free from
164<a
165href="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>