aboutsummaryrefslogtreecommitdiff
path: root/gdb/doc/gdbgui.texinfo
blob: 0ea150ba884281e4b0e5c9fc3cbc248fc06690d5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
\input texinfo      @c -*-texinfo-*-
@c Copyright 1994, 1995, 2001 Free Software Foundation, Inc.
@c
@c %**start of header
@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
@c of @set vars.  However, you can override filename with makeinfo -o.
@setfilename gdb.info
@c
@include gdb-cfg.texi
@c
@ifset GENERIC
@settitle Using the Graphical Interface to @value{GDBN}
@end ifset
@ifclear GENERIC
@settitle Using the Graphical Interface to @value{GDBN} (@value{TARGET})
@end ifclear
@setchapternewpage odd
@c %**end of header

@c Since this interface is so new, there is much missing still.
@c Desired but unimplemented features are commented out.

@iftex
@c @smallbook
@c @cropmarks
@end iftex

@finalout
@syncodeindex ky cp

@c readline appendices use @vindex
@syncodeindex vr cp

@c !!set GDB manual's edition---not the same as GDB version!
@set EDITION 4.14

@c !!set GDB manual's revision date
@set DATE April 2001

@c THIS MANUAL REQUIRES TEXINFO-2 macros and info-makers to format properly.

@dircategory Programming & development tools
@direntry
START-INFO-DIR-ENTRY
* Gdb: (gdb).                     The GNU debugger.
END-INFO-DIR-ENTRY
@end direntry
@c
@c
@ifinfo
This file documents the graphical interface to the GNU debugger @value{GDBN}.


This is Edition @value{EDITION}, @value{DATE},
of @cite{Using the Graphical Interface to @value{GDBN}}
for GDB Version @value{GDBVN}.

Copyright (C) 1994, 1995, 2001 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``Using the Graphical Interface to ``GDB'' and
``Starting up GUI GDB'', with the Front-Cover texts being ``A GNU
Manual,'' and with the Back-Cover Texts as in (a) below.

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''
@end ifinfo

@titlepage
@title Using the Graphical Interface to @value{GDBN}
@subtitle The GNU Source-Level Debugger
@ifclear GENERIC
@subtitle (@value{TARGET})
@end ifclear
@sp 1
@subtitle Edition @value{EDITION}, for @value{GDBN} version @value{GDBVN}
@subtitle @value{DATE}
@author Stanley T.@: Shebs
@page
@tex
{\parskip=0pt
\hfill (Send bugs and comments on @value{GDBN} to bug-gdb\@gnu.org.)\par
\hfill {\it Debugging with @value{GDBN}}\par
\hfill \TeX{}info \texinfoversion\par
\hfill doc\@cygnus.com\par
}
@end tex

@vskip 0pt plus 1filll
Copyright @copyright{} 1994, 1995, 2001 Free Software Foundation, Inc.
@sp 2

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``Using the Graphical Interface to ``GDB'' and
``Starting up GUI GDB'', with the Front-Cover texts being ``A GNU
Manual,'' and with the Back-Cover Texts as in (a) below.

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''
@end titlepage
@page

@ifinfo
@node Top
@top Using the Graphical Interface to @value{GDBN}
@end ifinfo

This file describes a graphical interface to @value{GDBN},
the GNU symbolic debugger.

@node Invocation
@chapter Starting up GUI @value{GDBN}

If @value{GDBN} has been configured to use the graphical interface,
then you will get the interface automatically upon startup.

When running as a Unix program and using the X11-based interface,
you must of course be using an X server and/or workstation,
and your @code{DISPLAY} environment variable must be set correctly.
If either of these is not true, then @value{GDBN} will still start up,
zbut will use only the traditional command interface.

The exact layout and appearance of the windows will depend on the host
system type.  For instance, @value{GDBN} on MS-Windows will display
its windows inside a larger window, while on X on a GNU/Linux or a
Unix machine, each window is a separate toplevel window.  However,
general behavior and layout is consistent across all platforms;
omissions or restrictions on particular platforms, if not documented
as unavoidable, should be considered bugs and reported.

All @value{GDBN} windows have a common structure.  Each window has an
associated menu bar, which may be at the top of the window or perhaps
elsewhere.  Some of the menus and menu items in the menu bar are
common to all @value{GDBN} windows, while others are specific to
particular types of windows.  Below the menu bar is the working data
area of the window.  If the data is too large to display all at once,
the data area will have scroll bars on its right and bottom sides.
Below the data area are two optional features; a status/data line, and
a button box.

@section Menus

@subsection File Menu

The standard file menu provides operations that affect the overall state
of @value{GDBN}, mainly file operations, but other things as well.

@table @code
@item About @value{GDBN}...
Displays the startup window for @value{GDBN}.

@item File...
Lets you set the combined executable and symbol file that @value{GDBN}
will use.  (Like the @samp{file} command in the command-line version
of @value{GDBN}.)

@item Target...
Brings up a dialog that you can use to connect @value{GDBN} to a
target program.  The dialog is described in more depth later.  (Like
the @samp{target} command.)

@item Edit...
Starts up an editor to modify the source file being displayed.

@item Exec File...
Lets you set the executable file that @value{GDBN} will use.
(Like the @samp{exec-file} command.)

@item Symbol File...
Lets you set the symbol file that @value{GDBN} will use.
(Like the @samp{symbol-file} command.)

@item Add Symbol File...
Lets you add additional symbol files.
(Like the @samp{add-symbol-file} command.)

@item Core File...
Lets you set the core file that @value{GDBN} will use.
(Like the @samp{core-file} command.)

@item Shared Libraries...
(Like the @samp{sharedlibrary} command.)

@item Quit
Quits @value{GDBN}.
(Like the @samp{quit} command.)
@end table


@c @subsection Commands Menu

@c The commands menu consists of items that let you run and control the program being
@c debugged.
@c 
@c @table @code
@c @item Run
@c 
@c @item Step
@c 
@c @item Next
@c 
@c @item Finish
@c 
@c @item Stepi
@c 
@c @item Nexti

@subsection Windows Menu

The @samp{Windows} menu allows access to all the windows available in
@value{GDBN}.  The first part of the menu lists all of the predefined
individual windows.  If the window exists already, its item will be
marked as such; selecting the item will cause the window to be put in
front if it is obscured.  If it does not exist, then it will be
created.

The second part of the menu lists additional windows that you may have
created, such as source windows or variable displays.

@display
Command
---
Source
Assembly
---
Registers
Variables
---
Files
@c ---
@c <extra windows>
@end display

@subsection View Menu

All windows have a @samp{view} menu, but its contents are highly
specific to window type.  For instance, a source window will have a
view menu item to control the display of line numbers, but a register
window will instead have an option to choose the radix in which to
display register contents.  You can find the full description of view
options with each window type.

@subsection Help Menu

The @samp{Help} menu includes access to @value{GDBN}'s online help.

@section Windows

@subsection Command Window

The @samp{Command} window provides access to the standard @value{GDBN}
command interpreter.  In nearly all cases, commands typed into this
window will behave exactly as for a non-windowing @value{GDBN}.

Note that not all changes to @value{GDBN} will be reflected in this
window.  For instance, if you were to type a @samp{step} command, then
click on the @samp{step} menu item in the source window, then go back,
and type another @samp{step} command, the command buffer will only
show two steps, when you have actually done three.  @value{GDBN} will
put a ``@dots'' into the command buffer when operations in other
windows are done, as a reminder that the command buffer is incomplete.

@c Also note that as a side effect of having the interface and possibly an
@c associated scripting language built in, additional commands may be
@c available.  For instance, if tcl is in @value{GDBN}, the command 
@c ``tcl <tcl code>'' will be available.

The command window has no status line or button box.

@subsection Files Window

The @samp{Files} window lists all of the files that were used to build the
executable.

Clicking on the @samp{xxx} in the left margin expands/contracts the
display of included files and symbols defined by the file.

The @samp{View} menu for this window includes the following items:

@table @code
@item Name/Full Pathname
@c @item Sort by Name
@c @item Sort by Section&Offset
@c @item Show All Included Files
@c @item Included File Indentation...
@end table

@subsection Source Window

A @samp{Source} window displays a single file of source code.

The left margin includes an indicator for the current PC, breakpoints
and potential breakpoints, and (optionally) line numbers.

The @samp{View} menu for this window includes the following items:

@table @code
@item Show Line Numbers
@item Show Breakdots
@c @item Jump to PC (if pc changes, scroll back so PC is centered)
@c @item Tab... (set tabbing)
@end table

@section Extensions

[description of gdbtk details]

@c 
@c GDBTK Interface Design
@c 
@c This is the working document describing the design of the GDBTK
@c interface.  Note that overall layout applies only to the default setup;
@c it is expected that debugger users will be able to customize extensively.
@c 
@c Default Startup
@c 
@c One source window, shows source as in "list main", does *not* set a
@c break at main or run or anything.  No current PC indicator, only put
@c in when something runs.
@c 
@c Source Window
@c 
@c For native, "run" button is always the same, for cross, it's actually
@c a "target" button that pops up appropriate dialog to get connected.
@c Once remote target is active, change button to "run".
@c 
@c Be able to toggle assembly interleaved between source.
@c 
@c Command Window
@c 
@c Is an *optional* window.
@c 
@c Behavior mimics command-line @value{GDBN} running in an Emacs buffer as much
@c as possible.
@c 
@c Assembly Window
@c 
@c Be able to toggle source interleaved between assembly.
@c 
@c Target Info Window
@c 
@c Contents similar to "info target".
@c 
@c Should expand into process and thread info also.
@c 
@c File Info Window
@c 
@c Contents similar to "info files".
@c 
@c Include data shown in "info sources" as well as "info files".
@c 
@c Register Info Window
@c 
@c Contents similar to "info registers".
@c 
@c Add view option(s) for classes of registers.
@c 
@c Stack Info Window
@c 
@c Combines backtrace, frame, and local var displays.
@c 
@c Signals Dialog
@c 
@c Includes all signals whose handling may be controlled, plus
@c checkboxes for what to do with each.
@c 
@c Settings Dialog(s)
@c 
@c Include all variables that can be "set" and "show"n.
@c 
@c General Principles
@c 
@c All windows should have a menu that allows access to other windows.
@c Selection of item either brings up for first time or brings to front.
@c 
@c All windows should have a "view" menu that controls formatting
@c options for that window.
@c 
@c Windows should usually be scrollable.  Windows that display largish
@c horizontal things should be horizontal and vertical scrollbars.
@c 
@c To do standard modification, add commands or tcl code to .gdbtkinit.
@c 
@c Be able to record window positions so they come up in the same way
@c the next time.  Could scribble on .gdbtkinit perhaps, or else an
@c aux file that can be sourced by .gdbtkinit.

@section How to Build

If @value{GDBN} is configured with @samp{--enable-gdbtk}, then upon
startup, it will open windows.

@node Index
@unnumbered Index

@printindex cp

@contents
@bye