1 <html><link rel="StyleSheet" href="../css/jde_style.css" TYPE="text/css"><head>
2 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
3 <title>Debugging with jdb</title><meta name="generator" content="DocBook XSL Stylesheets V1.67.0"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="d51e2"></a>Debugging with jdb</h1></div><div><p class="releaseinfo">
4 <em><span class="remark">
5 Revised for JDEE <span class="productnumber">2.3.3</span>
7 </p></div><div><p class="copyright">Copyright © 1997-2003 Paul Kinnucan</p></div></div><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d51e31"></a><a name="Intro"></a>Debugger Setup</h2></div></div></div><p>You should perform the following steps before attempting to use jdb.</p><div class="itemizedlist"><ul type="disc"><li><p>Set the configuration variable
8 <code class="varname">jde-debugger</code> to <code class="option">jdb</code> if
9 you are using version 1.3 (or later) of the Windows or
10 Solaris versions of the JDK or version 1.2.2 (or later) of
11 the Linux version of the JDK. Set
12 <code class="varname">jde-debugger</code> to <code class="option">oldjdb</code>
13 if you are using older versions of the JDK.</p></li><li><p>
14 Use <code class="varname">jde-sourcepath</code> to specify the paths
15 of any source code that you expect to visit while
16 debugging your application (see <a href="#SettingSourcePath">
17 Setting the Source Path</a>). If you suspect that a
18 problem is occurring in the Java API, you should include
19 the API source files in your source path.
21 Set <code class="varname">jde-compile-option-debug</code> on
23 <a href="../jde-ug/jde-ug-content.html#CompilingJavaPrograms">Compiling
24 Java Programs</a>). This causes the compiler to insert
25 information needed by the debugger into your
26 application's class files.
27 </p></li><li><p>Specify the app's main class either by setting the
28 <code class="varname">jde-run-application-class</code> variable or by starting the
29 debugger from the buffer that contains the source file for
31 </p></li></ul></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d51e77"></a><a name="RunningDebugger"></a>Running the Debugger</h2></div></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e81"></a><a name="StartingDebugger"></a>Starting the Debugger</h4></div></div></div><p>To debug a program with <code class="filename">jdb</code>,
32 first select a buffer containing the source of the program you
33 want to debug (or a source buffer containing the program's
34 main class if you have not set
35 <code class="varname">jde-run-application-class</code>). Then execute
36 the JDEE's <code class="command">jde-debug</code> command. You can execute
38 </p><div class="itemizedlist"><ul type="disc"><li><p>Selecting
39 <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guimenuitem">Debug App</strong></span>
41 Entering the key combination
42 <span><strong class="keycap">C</strong></span>-<span><strong class="keycap">c</strong></span> <span><strong class="keycap">C</strong></span>-<span><strong class="keycap">v</strong></span> <span><strong class="keycap">C</strong></span>-<span><strong class="keycap">d</strong></span>
43 </p></li><li><p>Entering <span><strong class="keycap">M</strong></span>-<span><strong class="keycap">x</strong></span> <code class="command">jde-debug</code></p></li></ul></div><p>The JDEE launches jdb, passing to it the name of the main
44 class of the program in the current source buffer and any
45 debug options that you have specified via the JDEE's debugger
46 option variables (see <a href="#SettingDebugOptions">Setting Debug Options</a>.
47 jdb in turn launches a virtual machine to run the debuggee
48 program and stops the virtual machine before the main method
49 of the program's main class. Meanwhile the JDEE splits the
50 source window into two windows.
51 </p><div class="screenshot"><div class="mediaobject"><img src="images/debug1.gif"></div></div><p>
52 The upper window shows the source buffer. The menu bar
53 of the source buffer displays a menu (<span><strong class="guimenu">Jdb</strong></span>)
54 of debug commands. The lower window shows the debugger
56 </p><p>At this point, you can set breakpoints, run to a breakpoint that
57 you set before you started the debugger, or step into the main method
58 of your program.</p><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e154"></a><a name="SettingDebugOptions"></a>Setting Debug Options</h5></div></div></div><p>The <code class="command">jde-jdb</code> command (selected by
59 <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guimenuitem">Debug App</strong></span> when jdb
60 is the debugger for the current project) can optionally pass
61 command-line arguments that specify various debug options to
62 jdb when starting jdb. The JDEE provides two ways to specify
63 these options: via customization variables or in the
64 minibuffer when you run the <code class="command">jde-jdb</code>
65 command.</p><p>The <code class="command">jde-jdb</code> command passes any
66 options that you specify via customization variables to jdb.
67 In addition, if you set the customization variable
68 <code class="varname">jde-db-read-vm-args</code> to a non-nil value,
69 the <code class="command">jde-jdb</code> command prompts you to enter
70 debugger options in the minibuffer. It appends the options
71 that you enter to the options specified via customization
72 variables. The JDEE saves the arguments that you enter in a
73 minibuffer history list. You can recall previously entered
74 options by pressing the up or down arrows on your keyboard.
75 </p></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e183"></a><a name="SettingAppArguments"></a>Setting App Arguments</h5></div></div></div><p>You can use the customization variable
76 <code class="varname">jde-db-option-application-args</code> to specify
77 arguments to be passed to the application launched by jdb.
78 The <code class="command">jde-jdb</code> command inserts the specified
79 arguments on the command-line that it constructs to run
80 jdb.</p><p>In addition, if you set the customization variable
81 <code class="varname">jde-db-read-app-args</code> to a
82 non-<code class="option">nil</code> value, the
83 <code class="command">jde-jdb</code> command prompts you to enter the
84 application arguments in the minibuffer. It appends the
85 options that you enter to the arguments specified via
86 <code class="varname">jde-db-option-application-args</code>. The JDEE
87 saves the arguments that you enter in a minibuffer history
88 list. You can recall previously entered options by pressing
89 the up or down arrows on your keyboard. </p></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e209"></a><a name="EnteringCommands"></a>Entering Debug Commands</h4></div></div></div><p>The JDE lets you enter commands from either the current source
90 buffer or from the debugger command-line interaction buffer.
91 You can enter all debugger commands from the debugger
92 buffer. You can enter only a subset of debugger commands
93 from the current source buffer. </p><p> To enter a debugger command
94 from the current source buffer, select the command from the
95 jdb menu or type the shortcut key for the command. The <span><strong class="guimenu">Jdb</strong></span>
96 menu lists the shortcut keys
97 for debugger commands. </p><p>To enter a command in the debugger interaction window, type the
98 command at the debugger prompt and press the <span><strong class="keycap">Enter</strong></span>
99 key. To see a list of debugger commands, enter the command
100 <code class="command">help</code>.
101 </p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e228"></a><a name="SteppingProgram"></a>Stepping Through a Program</h4></div></div></div><p>
102 Jdb provides a set of command-line commands that advance a
103 program to the next line or the next breakpoint. The JDEE's
104 jdb interface provides Emacs commands that invoke the jdb's
105 step commands from a source buffer and move a debug cursor to
106 the next line to be executed in the source buffer. If you
107 prefer, you can enter jdb's step commands directly in the jdb
109 </p><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e234"></a><a name="StepCommands"></a>Step Commands</h5></div></div></div><p> The following table lists the jdb step commands
110 supported by the JDEE.
111 </p><div class="table"><a name="d51e240"></a><p class="title"><b>Table 1. Step Commands</b></p><table summary="Step Commands" border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th>Jdb Menu Item</th><th>Emacs Command</th><th>jdb Command</th><th>Description</th></tr></thead><tbody><tr><td>Step Over</td><td>jde-bug-step-over</td><td>next</td><td><p>Advance to the next line in the current
112 method, stepping over any lines that invoke other
113 methods.</p></td></tr><tr><td>Step Into</td><td>jde-debug-step-into</td><td>step</td><td><p>Advance to the next line in the
114 program.</p></td></tr><tr><td>Step Out</td><td>jde-debug-step-out</td><td>step up</td><td><p>Advance to the next line in the method
115 that invoked the current method.</p></td></tr><tr><td>Continue</td><td>jde-debug-cont</td><td>cont</td><td><p>Advance to the next breakpoint or to the
116 end of the program, whichever comes
117 first.</p></td></tr></tbody></table></div></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e295"></a><a name="DebugCursor"></a>Debug Cursor</h5></div></div></div><p>The JDEE uses an arrow, called the debug cursor, to
118 indicate the next line to be executed as the result of a
119 step or continue command. The debug cursor appears in the
120 left gutter of the source window containing the next line to
121 be executed.</p><div class="screenshot"><div class="mediaobject"><img src="images/debug_cursor.gif"></div></div><p>If the step or continue command advances the
122 program to a line that is not displayed in the current
123 source window, the JDEE opens the source file containing the
124 line, if necessary, and displays the source buffer in the
125 current source window, with the window scrolled to show the
126 line at which the program has halted.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>A blank source buffer indicates that the debugger
127 cannot find the source file into which you have stepped.
128 You should check your source path setting (see <a href="#SettingSourcePath">Setting the Source
129 Path</a>) to ensure that it includes all source
130 files in the execution path of your program.
131 </p></div></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d51e313"></a><a name="SettingBreakpoints"></a>Setting Breakpoints</h2></div></div></div><p>To set a breakpoint on any executable line in the current
132 source buffer, click on the line and select <span><strong class="guimenu">Jdb</strong></span>-><span><strong class="guimenuitem">Set Breakpoint</strong></span>
133 (<span><strong class="keycap">C</strong></span>-<span><strong class="keycap">c</strong></span><span><strong class="keycap">C</strong></span>-<span><strong class="keycap">a</strong></span>
134 <span><strong class="keycap">C</strong></span>-<span><strong class="keycap">b</strong></span>). The JDEE highlights the
135 current line to indicate that a breakpoint is to be set at that
136 line. </p><div class="screenshot"><div class="mediaobject"><img src="images/breakpoint.gif"></div></div><p>
138 running, the JDEE issues a command to the debugger to set a
139 breakpoint at the highlighted line. If not, the JDEE issues the
140 breakpoint command as soon as you start the debugger. If the
141 class in which the breakpoint is to be set is currently in memory
142 and the breakpoint is valid, the debugger sets the breakpoint.
143 If the class in which the breakpoint is set is not in memory,
144 the debugger puts it on a list of pending breakpoints. If the
145 class is subsequently loades, the debugger sets the breakpoint
147 </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e348"></a><a name="BreakpointColors"></a>Breakpoint Colors</h4></div></div></div><p>
148 The color of a breakpoint highlight indicates the status of the breakpoint
150 </p><div class="table"><a name="d51e354"></a><p class="title"><b>Table 1. Breakpoint Colors</b></p><table summary="Breakpoint Colors" border="1"><colgroup><col><col></colgroup><thead><tr><th>Color</th><th>Description</th></tr></thead><tbody><tr><td>Green</td><td>The JDEE has not yet issued a command to the
151 debugger to set the breakpoint.</td></tr><tr><td>Yellow</td><td>The breakpoint is pending loading of the class in which it
152 is to be set.</td></tr><tr><td>Red</td><td>The breakpoint has been set.</td></tr></tbody></table></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e380"></a><a name="ClearingBreakpoints"></a>Clearing
153 Breakpoints</h4></div></div></div><p>
154 To clear a breakpoint from a line in the current buffer, click
155 on the line and select <span><strong class="guimenu">Jdb</strong></span>-><span><strong class="guimenuitem">Toggle Breakpoint</strong></span>
156 (<span><strong class="keycap">C</strong></span>-<span><strong class="keycap">c</strong></span>
157 <span><strong class="keycap">C</strong></span>-<span><strong class="keycap">a</strong></span>
158 <span><strong class="keycap">C</strong></span>-<span><strong class="keycap">b</strong></span>).
159 </p><p>To clear all breakpoints set in the current session,
160 select <span><strong class="guimenu">Jdb</strong></span>-><span><strong class="guimenuitem">Clear
161 Breakpoints</strong></span>.
162 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>You can also set and clear breakpoints by entering jdb
163 breakpoint commands in the jdb interaction buffer. See the
164 jdb documentation for information on using the jdb
165 breakpoint commands.</p></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d51e421"></a><a name="SettingSourcePath"></a>Setting the Source Path</h2></div></div></div><p>The <code class="varname">jde-sourcepath</code> variable specifies the
166 directories the JDEE should search for source for classes
167 visited by the debugger as you step through your program.
168 </p><p>To set this variable, enter <code class="command">M-x customize-variable jde-sourcepath</code>.
169 The customization buffer for jde-sourcepath appears. The buffer shows the current
170 source path as a list of paths.</p><div class="screenshot"><div class="mediaobject"><img src="images/debug2.gif"></div></div><p>To add a path, click the <span class="guibutton">INS</span> button
171 corresponding to the position in the list and enter the path in
172 the resulting edit field. To delete a path, click the <span class="guibutton">DEL</span> button
173 corresponding to the path. You can use environment variables in paths and
174 use dot notation to specify paths relative to the project file for the
175 project to which this sourcepath applies. When you are done editing the buffer,
176 press the <span class="guibutton">State</span> button to set the
177 variable.</p><p>To avoid having to specify the sourcepath every time you
178 start a session, save the setting of
179 <code class="varname">jde-db-sourcepath</code> in your
180 <code class="filename">prj.el</code> file (see <a href="../jde-ug/jde-ug-content.html#SavingProjSettings">Saving
181 Project Settings</a>) To save the setting in your project
183 <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guimenuitem">Project</strong></span>-><span><strong class="guimenuitem">Project File</strong></span>-><span><strong class="guimenuitem">Save</strong></span> (<span><strong class="keycap">C</strong></span>-<span><strong class="keycap">c</strong></span>
184 <span><strong class="keycap">C</strong></span>-<span><strong class="keycap">v</strong></span>
185 <span><strong class="keycap">C</strong></span>-<span><strong class="keycap">p</strong></span>
187 You must specify the paths of the top-level directories of any
188 source code that you might visit while debugging your
189 application. The source code directory structure must mirror
190 your application's package structure. For example, suppose that your
191 application includes a set of classes packaged in the
192 <code class="filename">myapp</code> directory. Then, the source for those classes
193 must be reside in a directory named <code class="filename">myapp</code> and you must
194 specify the path of <code class="filename">myapp</code>'s parent directory.
195 </p><p>If you want to step through the JDK source code,
196 select the source code install option when you install the JDK
197 and set the <code class="varname">jde-sourcepath</code> variable
198 to the top-level directory containing the source code.
199 The JDE will use the JDK's package structure to find the
200 source code in the subdirectories. </p></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d51e505"></a><a name="DisplayingVariables"></a>Displaying Variables</h2></div></div></div><p>This section shows you how to display the values of variables
201 (or expressions).</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e511"></a><a name="DisplayingExpressions"></a>Displaying
202 Expressions</h4></div></div></div><p>When the debuggee program is stopped, the debugger lets
203 you display the value of any valid Java expression composed of
204 variables currently in scope. For example, to display the
205 value of a local, in-scope variable whose source is displayed
206 in a Java source buffer, put the point on the variable and
208 <span><strong class="guimenu">Jdb</strong></span>-><span><strong class="guimenuitem">Display</strong></span>-><span><strong class="guimenuitem">Expression</strong></span>. The JDEE prompts you to enter an expression to be
209 evaluated and displayed in the minibuffer.</p><div class="screenshot"><div class="mediaobject"><img src="images/display_var1.gif"></div></div><p> The default expression is the variable at point in the
210 source buffer. Edit the displayed expression and press
211 <span><strong class="keycap">Enter</strong></span>. The JDEE issues a command to the
212 debugger to display the variable in the jdb buffer.</p><div class="screenshot"><div class="mediaobject"><img src="images/display_var2.gif"></div></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e538"></a><a name="DisplayingObjects"></a>Displaying
213 Objects</h4></div></div></div><p>To display the values of the fields of an object
214 referenced by an in-scope variable in the current source
216 <span><strong class="guimenu">Jdb</strong></span>-><span><strong class="guimenuitem">Display</strong></span>-><span><strong class="guimenuitem">Object</strong></span>. The JDEE prompts you to enter the name of the
217 variable in the minibuffer. The default is the variable at
218 point in the source buffer. Press <span><strong class="keycap">Enter</strong></span>. The
219 JDEE issues a <code class="command">dump</code> command to the debugger
220 to display the field values of the object referenced by the
221 variable you entered.</p><div class="screenshot"><div class="mediaobject"><img src="images/display_obj.gif"></div></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e562"></a><a name="DisplayingLocals"></a>Displaying Locals
222 </h4></div></div></div><p>To display the values of all in-scope local variables,
223 including the values of the arguments of the method in which
224 the program is halted, select
225 <span><strong class="guimenu">Jdb</strong></span>-><span><strong class="guimenuitem">Display</strong></span>-><span><strong class="guimenuitem">Locals</strong></span>. The JDEE issues a <code class="command">locals</code>
226 command to the debugger to display the local variable
227 values.</p><div class="screenshot"><div class="mediaobject"><img src="images/display_locals.gif"></div></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d51e583"></a><a name="SettingVariables"></a>Setting Variables</h2></div></div></div><p>Jdb allows you to change the values of variables that are
228 in scope. To change the value of a variable via the JDEE's jdb
229 interface:</p><div class="orderedlist"><ol type="1"><li><p>Position point on the variable you want to change.</p></li><li><p>Select <span><strong class="guimenu">Jdb</strong></span>-><span><strong class="guimenuitem">Set Variable</strong></span>.
230 </p><p>The JDEE prompts you to enter a left expression that
231 represents the variable whose value you want to change. The
232 default is the variable at point in the source buffer.
233 </p><div class="screenshot"><div class="mediaobject"><img src="images/set_var1.gif"></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Edit the expression if necessary. For example, to set
234 the value of an array element at point, edit the
235 expression to include the index of the element.</p></div></li><li><p>Press <span><strong class="keycap">Enter</strong></span>.</p><p>The JDEE prompts you to enter the new value of the
236 variable.</p><div class="screenshot"><div class="mediaobject"><img src="images/set_var2.gif"></div></div></li><li><p>Enter the new value at the prompt in the minibuffer.</p><div class="screenshot"><div class="mediaobject"><img src="images/set_var3.gif"></div></div></li><li><p>Press <span><strong class="keycap">Enter</strong></span>.</p><p>The JDEE issues a <code class="command">set</code> command to the
237 debugger to set the specified variable to the new
238 value.</p><div class="screenshot"><div class="mediaobject"><img src="images/set_var4.gif"></div></div></li></ol></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d51e645"></a><a name="DebugExternalProcesses"></a>Debugging External Processes</h2></div></div></div><p>Normally jdb launches the application that it debugs.
239 However, you can use jdb to debug processes that are not
240 launched by jdb itself. This is useful, for example, if you need
241 to debug a process running on a remote computer or a Java
242 process launched by a nonJava process.</p><p>Jdb provides two
243 modes for debugging external processes: attach mode and listen
244 mode. When started in attach mode, jdb connects itself to the
245 external process. When started in listen mode, jdb waits for an
246 external process to connect itself to jdb. Each mode has
247 advantages. Attach mode allows you to debug an external process
248 anytime after it has started. Listen mode allows you to debug
249 the startup of a Java process launched by a nonJava process.</p><p>
250 The following sections explain how to use the JDEE's jdb
251 interface to run jdb in attach and listen mode.</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e655"></a><a name="AttachingProcesses"></a>Attaching Processes</h4></div></div></div><p>To attach jdb to an external process, you must ensure that the
252 external process is started in debug server mode. You must then
253 start jdb in attach mode.</p><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e661"></a><a name="DebugServerMode"></a>Starting the External
254 Process in Debug Server Mode</h5></div></div></div><p>To start an external process in debug server mode, you
255 must start the vm that runs the process with the following
256 command-line options:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">-Xdebug</code></p></li><li><p>
257 <code class="literal">-Xrunjdwp:transport=<span><strong class="keycap">TRANSPORT</strong></span>,address=<span><strong class="keycap">ADDRESS</strong></span>,server=y,suspend=<span><strong class="keycap">SUSPEND</strong></span></code>
258 </p><p>where</p><div class="itemizedlist"><ul type="circle"><li><p><code class="literal"><span><strong class="keycap">TRANSPORT</strong></span></code> is
259 the type of communications channel between jdb and
260 the debuggee process, either
261 <code class="literal">dt_socket</code> (socket) or
262 <code class="literal">dt_shmem</code> (shared memory, valid
263 only for Windows systems)</p></li><li><p><code class="literal"><span><strong class="keycap">ADDRESS</strong></span></code> is
264 the address of the socket port or shared memory area
265 used by the debuggee process to listen for a jdb
266 connection.</p></li><li><p><code class="literal"><span><strong class="keycap">SUSPEND</strong></span></code> is
267 either <code class="literal">y</code> (suspend the debuggee
268 process at startup, i.e., to wait for jdb to start,
269 a useful option when you need to debug an
270 application's startup code) or <code class="literal">n</code>
271 (do not suspend the debuggee process)</p></li></ul></div></li></ul></div><div class="example"><a name="d51e719"></a><p class="title"><b>Example 1. Specifying Socket Transport</b></p><p><code class="literal">-Xdebug
272 -Xrunjdwp:transport=dt_socket,address=4444,server=y,suspend=n</code></p></div><div class="example"><a name="d51e725"></a><p class="title"><b>Example 2. Specifying Shared Memory Transport (MS Windows only)</b></p><p><code class="literal">-Xdebug
273 -Xrunjdwp:transport=dt_shmem,address=javadebug,server=y,suspend=n</code></p></div><p>The JDEE customization variable, <code class="varname">jde-run-option-debug</code>, causes
274 the JDEE to generate these arguments automatically when launching a vm to run a Java
275 application. Thus, if you plan to launch the debuggee process from the JDEE, you
276 should set this variable to the desired options.</p></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e736"></a><a name="AttachMode"></a>Starting jdb in Attach
277 Mode</h5></div></div></div><p>To attach jdb to an existing process via a socket,
278 select <span><strong class="guimenu">Jdb</strong></span>-><span><strong class="guimenuitem">External Process</strong></span>-><span><strong class="guimenuitem">Attach Via Socket</strong></span> from the Emacs menu bar. By default,
279 the JDEE uses the socket address specified by
280 the customization variable <code class="varname">jde-db-option-connect-socket</code>.
281 If you set this variable to Prompt (nil), the JDEE
282 prompts you to enter a socket address in the minibuffer.
283 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The default socket address specified by
284 <code class="varname">jde-db-option-connect-socket</code>
285 is the same as the default socket address specified
286 by <code class="varname">jde-run-option-debug</code>. Thus, if you
287 want to attach jdb to a process started by the JDEE, the
288 only variable you have to set is
289 <code class="varname">jde-run-option-debug</code> (to run
290 the debuggee process in socket attach mode).</p></div><p>To attach jdb to an existing process via a shared memory
291 connection (Windows platforms only),
292 select <span><strong class="guimenu">Jdb</strong></span>-><span><strong class="guimenuitem">External Process</strong></span>-><span><strong class="guimenuitem">Attach Via Shared Memory</strong></span> from the Emacs menu bar. By default,
293 the JDEE uses the shared memory transport name specified by
294 the customization variable
295 <code class="varname">jde-db-option-connect-shared-memory-name</code>.
296 If you set this variable to Prompt (nil), the JDEE
297 prompts you to enter a shared-memory name in the minibuffer.
298 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The default shared memory name specified by
299 <code class="varname">jde-db-option-connect-shared-memory-name</code>
300 is the same as the default shared memory name specified
301 by <code class="varname">jde-run-option-debug</code>. Thus, if you
302 want to attach jdb to a process started by the JDEE, the
303 only variable you have to set is
304 <code class="varname">jde-run-option-debug</code> (to run
305 the debuggee process in shared memory attach mode).</p></div></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e790"></a><a name="ListeningForProcesses"></a>Listening for Processes</h4></div></div></div><p>To connect an external process to a jdb instance running in listener
306 mode:</p><div class="orderedlist"><ol type="1"><li><p>Start jdb in listener mode (see <a href="#ListenMode">Starting
307 jdb in Listen Mode</a>)</p></li><li><p>Start the debuggee process in debug client
308 mode(see <a href="#DebugClientMode">Starting
309 the External Process in Debug Client Mode</a>)</p></li></ol></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e809"></a><a name="ListenMode"></a>Starting jdb in Listen Mode</h5></div></div></div><p>To start jdb in listen mode, select <span><strong class="guimenu">Jdb</strong></span>-><span><strong class="guimenuitem">External Process</strong></span>-><span><strong class="guimenuitem">Listen For</strong></span> from the Emacs menu bar. By default, the
310 JDEE prompts you to enter the address of the process to
311 be debugged in the minibuffer. The JDEE customization variable
312 jde-db-option-listen-address allows you to specify a default
313 debuggee address. If you set this variable, the JDEE does not
314 prompt you to enter an address.
315 </p><p>To start jdb listening for existing process via a socket,
316 select <span><strong class="guimenu">Jdb</strong></span>-><span><strong class="guimenuitem">External Process</strong></span>-><span><strong class="guimenuitem">Listen Via Socket</strong></span> from the Emacs menu bar. By default,
317 the JDEE uses the socket address specified by
318 the customization variable <code class="varname">jde-db-option-connect-socket</code>.
319 If you set this variable to Prompt (nil), the JDEE
320 prompts you to enter a socket address in the minibuffer.
321 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The default socket address specified by
322 <code class="varname">jde-db-option-connect-socket</code>
323 is the same as the default socket address specified
324 by <code class="varname">jde-run-option-debug</code>. Thus, if you
325 want jdb to listen for a process started by the JDEE, the
326 only variable you have to set is
327 <code class="varname">jde-run-option-debug</code>, i.e., to run
328 the debuggee process in socket listen (client) mode.</p></div><p>To start jdb listening for a process via a shared memory
329 connection (Windows platforms only),
330 select <span><strong class="guimenu">Jdb</strong></span>-><span><strong class="guimenuitem">External Process</strong></span>-><span><strong class="guimenuitem">Listen Via Shared Memory</strong></span> from the Emacs menu bar. By default,
331 the JDEE uses the shared memory transport name specified by
332 the customization variable
333 <code class="varname">jde-db-option-connect-shared-memory-name</code>.
334 If you set this variable to Prompt (nil), the JDEE
335 prompts you to enter a shared-memory name in the minibuffer.
336 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The default shared memory name specified by
337 <code class="varname">jde-db-option-connect-shared-memory-name</code>
338 is the same as the default shared memory name specified
339 by <code class="varname">jde-run-option-debug</code>. Thus, if you
340 want jdb to listen for a process started by the JDEE, the
341 only variable you have to set is
342 <code class="varname">jde-run-option-debug</code>, i.e., to run
343 the debuggee process in shared memory listen (client) mode.</p></div></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e873"></a><a name="DebugClientMode"></a>Starting the External
344 Process in Debug Client Mode</h5></div></div></div><p>To start an external process in debug client mode, you
345 must start the vm that runs the process with the following
346 command-line options:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">-Xdebug</code></p></li><li><p>
347 <code class="literal">-Xrunjdwp:transport=<span><strong class="keycap">TRANSPORT</strong></span>,address=<span><strong class="keycap">ADDRESS</strong></span>,server=n,suspend=<span><strong class="keycap">SUSPEND</strong></span></code>
348 </p><p>where</p><div class="itemizedlist"><ul type="circle"><li><p><code class="literal"><span><strong class="keycap">TRANSPORT</strong></span></code> is
349 the type of communications channel between jdb and
350 the debuggee process, either
351 <code class="literal">dt_socket</code> (socket) or
352 <code class="literal">dt_shmem</code> (shared memory, valid
353 only for Windows systems)</p></li><li><p><code class="literal"><span><strong class="keycap">ADDRESS</strong></span></code> is
354 the address of the socket port or shared memory area
355 used by jdb to listen for a debuggee process
356 connection.</p></li><li><p><code class="literal"><span><strong class="keycap">SUSPEND</strong></span></code> is
357 either <code class="literal">y</code> (suspend the debuggee
358 process when the connection occurs,
359 a useful option when you need to debug an
360 application's startup code) or <code class="literal">n</code>
361 (do not suspend the debuggee process)</p></li></ul></div></li></ul></div><div class="example"><a name="d51e931"></a><p class="title"><b>Example 3. Specifying Socket Transport</b></p><p><code class="literal">-Xdebug
362 -Xrunjdwp:transport=dt_socket,address=4444,server=n,suspend=n</code></p></div><div class="example"><a name="d51e937"></a><p class="title"><b>Example 4. Specifying Shared Memory Transport (MS Windows only)</b></p><p><code class="literal">-Xdebug
363 -Xrunjdwp:transport=dt_shmem,address=javadebug,server=n,suspend=n</code></p></div><p>The JDEE customization variable, <code class="varname">jde-run-option-debug</code>, causes
364 the JDEE to generate these arguments automatically when launching a vm to run a Java
365 application. Thus, if you plan to launch the debuggee process from the JDEE, you
366 should set this variable to the desired options.</p></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d51e948"></a><a name="DebugOptions"></a>Debug Options</h2></div></div></div><p>The JDEE allows you to specify debug options by setting JDEE
367 configuration variables. You can use the Emacs customization
368 feature to set debug variables interactively. To use the
369 customization feature, select <span><strong class="guimenu">Project</strong></span>-><span><strong class="guimenuitem">Options</strong></span>-><span><strong class="guimenuitem">Debug</strong></span> from the
370 <span><strong class="guimenu">JDE</strong></span> menu. (See <a href="../jde-ug/jde-ug-content.html#ConfiguringJDE">Configuring
371 the JDEE</a> for more information on using the
372 customization feature). To save the compilation settings in the
373 project file (see <a href="../jde-ug/jde-ug-content.html#UsingProjectFiles">Using
374 Project Files</a> for the current source buffer, select
375 <span><strong class="guimenu">Project</strong></span>-><span><strong class="guimenuitem">Project File</strong></span>-><span><strong class="guimenuitem">Save</strong></span> from the
376 <span><strong class="guimenu">JDE</strong></span> menu.</p><p>The following table lists the jdb customization variables.</p><div class="table"><a name="d51e984"></a><p class="title"><b>Table 1. Jdb Customization Variables</b></p><table summary="Jdb Customization Variables" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Variable</th><th>Group</th><th>Usage</th></tr></thead><tbody><tr><td valign="top"><code class="varname">jde-debugger</code></td><td valign="top">Project</td><td valign="top">Specify which debugger to use to debug the current project.</td></tr><tr><td valign="top"><code class="varname">jde-sourcepath</code></td><td valign="top">Project</td><td valign="top">Specify location(s) of source files that
377 can be visited while stepping through a program.</td></tr><tr><td valign="top"><code class="varname">jde-db-mode-hook</code></td><td valign="top">Project</td><td valign="top">Customization hook for jde-db inferior
378 mode.</td></tr><tr><td valign="top"><code class="varname">jde-global-classpath</code></td><td valign="top">Project</td><td valign="top">Specify class paths for compile, run,
379 and debug commands.</td></tr><tr><td valign="top"><code class="varname">jde-db-read-vm-args</code></td><td valign="top">Project</td><td>Specifies whether to read debugger VM arguments from
380 the minibuffer.</td></tr><tr><td valign="top"><code class="varname">jde-db-read-app-args</code></td><td valign="top">Project</td><td>Specifies whether to read command-line application
381 arguments from the minibuffer.</td></tr><tr><td valign="top"><code class="varname">jde-db-option-classpath</code></td><td valign="top">Debug</td><td valign="top">Specifies the classpath for the
382 Java interpreter. This option overrides the
383 jde-global-classpath option.</td></tr><tr><td valign="top"><code class="varname">jde-db-option-verbose</code></td><td valign="top">Debug</td><td valign="top">Print messages about the running
384 process.</td></tr><tr><td valign="top"><code class="varname">jde-db-option-properties</code></td><td valign="top">Debug</td><td valign="top">Specify property values.</td></tr><tr><td valign="top"><code class="varname">jde-db-option-heap-size</code></td><td valign="top">Debug</td><td valign="top">Specify the initial and maximum size of
385 the interpreter heap.</td></tr><tr><td valign="top"><code class="varname">jde-db-option-stack-size</code></td><td valign="top">Debug</td><td valign="top">Specify size of the C and Java stacks.</td></tr><tr><td valign="top"><code class="varname">jde-db-option-garbage-</code>
386 <code class="varname">collection</code></td><td valign="top">Debug</td><td valign="top">Specify garbage collection
387 options.</td></tr><tr><td valign="top"><code class="varname">jde-db-option-java-profile</code></td><td valign="top">Debug</td><td valign="top">Enable Java profiling.</td></tr><tr><td valign="top"><code class="varname">jde-db-option-heap-profile</code></td><td valign="top">Debug</td><td valign="top">Output heap profiling data.</td></tr><tr><td valign="top"><code class="varname">jde-db-option-verify</code></td><td valign="top">Debug</td><td valign="top">Verify classes.</td></tr><tr><td valign="top"><code class="varname">jde-db-option-vm-args</code></td><td valign="top">Debug</td><td valign="top">Specify command-line arguments to be
388 passed to the Java VM.</td></tr><tr><td valign="top"><code class="varname">jde-db-option-application-args</code></td><td valign="top">Debug</td><td valign="top">Specify command-line arguments to pass
389 to the application.</td></tr><tr><td valign="top"><code class="varname">jde-db-option-connect-socket</code></td><td valign="top">Debug</td><td valign="top">Specify socket address of a running process
390 to which you want to connect the debugger, using a
391 debugger attach or listen command.</td></tr><tr><td valign="top"><code class="varname">jde-db-option-connect-shared-memory-name</code></td><td valign="top">Debug</td><td valign="top">Specify shared memory name used by the debugger
392 to attach or listen for debuggee processes to debug.</td></tr><tr><td valign="top"><code class="varname">jde-db-option-host</code></td><td valign="top">Debug</td><td valign="top">Host of a remote process to which you
393 wish to attach the debugger. This option is invalid for JDK verions
394 greater than JDK 1.1.x.</td></tr></tbody></table></div></div></div></body></html>
projects / packages / blob