building.texi 68.6 KB
Newer Older
Glenn Morris's avatar
Glenn Morris committed
1
@c This is part of the Emacs manual.
Paul Eggert's avatar
Paul Eggert committed
2
@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2018 Free Software
3
@c Foundation, Inc.
Glenn Morris's avatar
Glenn Morris committed
4
@c See file emacs.texi for copying conditions.
5
@node Building
Glenn Morris's avatar
Glenn Morris committed
6 7 8 9 10
@chapter Compiling and Testing Programs
@cindex building programs
@cindex program building
@cindex running Lisp functions

11 12 13
  The previous chapter discusses the Emacs commands that are useful
for making changes in programs.  This chapter deals with commands that
assist in the process of compiling and testing programs.
Glenn Morris's avatar
Glenn Morris committed
14 15 16 17 18 19 20 21 22

@menu
* Compilation::         Compiling programs in languages other
                          than Lisp (C, Pascal, etc.).
* Compilation Mode::    The mode for visiting compiler errors.
* Compilation Shell::   Customizing your shell properly
                          for use in the compilation buffer.
* Grep Searching::      Searching with grep.
* Flymake::             Finding syntax errors on the fly.
23
* Debuggers::           Running symbolic debuggers for non-Lisp programs.
Glenn Morris's avatar
Glenn Morris committed
24 25 26
* Executing Lisp::      Various modes for editing Lisp programs,
                          with different facilities for running
                          the Lisp programs.
27 28 29
* Libraries: Lisp Libraries.      How Lisp programs are loaded into Emacs.
* Eval: Lisp Eval.      Executing a single Lisp expression in Emacs.
* Interaction: Lisp Interaction.  Executing Lisp in an Emacs buffer.
30
* External Lisp::       Communicating through Emacs with a separate Lisp.
Glenn Morris's avatar
Glenn Morris committed
31 32 33 34 35 36 37 38 39
@end menu

@node Compilation
@section Running Compilations under Emacs
@cindex inferior process
@cindex make
@cindex compilation errors
@cindex error log

40 41 42
  Emacs can run compilers for languages such as C and Fortran, feeding
the compilation log into an Emacs buffer.  It can also parse the error
messages and show you where the errors occurred.
Glenn Morris's avatar
Glenn Morris committed
43 44 45 46

@table @kbd
@item M-x compile
Run a compiler asynchronously under Emacs, with error messages going to
47
the @file{*compilation*} buffer.
48

Glenn Morris's avatar
Glenn Morris committed
49
@item M-x recompile
50
@itemx g@r{ (Compilation mode)}
Glenn Morris's avatar
Glenn Morris committed
51 52
Invoke a compiler with the same command as in the last invocation of
@kbd{M-x compile}.
53

Glenn Morris's avatar
Glenn Morris committed
54 55 56 57 58
@item M-x kill-compilation
Kill the running compilation subprocess.
@end table

@findex compile
59 60
  To run @code{make} or another compilation command, type @kbd{M-x
compile}.  This reads a shell command line using the minibuffer, and
61 62
then executes the command by running a shell as a subprocess (or
@dfn{inferior process}) of Emacs.  The output is inserted in a buffer
63
named @file{*compilation*}.  The current buffer's default directory is
64 65
used as the working directory for the execution of the command, so by
default compilation takes place in that directory.
Glenn Morris's avatar
Glenn Morris committed
66 67

@vindex compile-command
68 69 70 71 72 73 74 75 76 77
  The default compilation command is @samp{make -k}, which is usually
correct for programs compiled using the @command{make} utility (the
@samp{-k} flag tells @command{make} to continue compiling as much as
possible after an error).  @xref{Top,, Make, make, GNU Make Manual}.
If you have done @kbd{M-x compile} before, the command that you
specified is automatically stored in the variable
@code{compile-command}; this is used as the default the next time you
type @kbd{M-x compile}.  A file can also specify a file-local value
for @code{compile-command} (@pxref{File Variables}).

78
  Starting a compilation displays the @file{*compilation*} buffer in
79 80
another window but does not select it.  While the compilation is
running, the word @samp{run} is shown in the major mode indicator for
81 82
the @file{*compilation*} buffer, and the word @samp{Compiling} appears
in all mode lines.  You do not have to keep the @file{*compilation*}
83 84
buffer visible while compilation is running; it continues in any case.
When the compilation ends, for whatever reason, the mode line of the
85
@file{*compilation*} buffer changes to say @samp{exit} (followed by
86 87 88 89
the exit code: @samp{[0]} for a normal exit), or @samp{signal} (if a
signal terminated the process).

  If you want to watch the compilation transcript as it appears,
90
switch to the @file{*compilation*} buffer and move point to the end of
91 92 93 94
the buffer.  When point is at the end, new compilation output is
inserted above point, which remains at the end.  Otherwise, point
remains fixed while compilation output is added at the end of the
buffer.
Glenn Morris's avatar
Glenn Morris committed
95

96 97 98
  While compilation proceeds, the mode line shows the number of
errors, warnings, and informational messages emitted by the compiler
so far.
99

Glenn Morris's avatar
Glenn Morris committed
100 101
@cindex compilation buffer, keeping point at end
@vindex compilation-scroll-output
102
  If you change the variable @code{compilation-scroll-output} to a
103
non-@code{nil} value, the @file{*compilation*} buffer scrolls
104 105 106 107
automatically to follow the output.  If the value is
@code{first-error}, scrolling stops when the first error appears,
leaving point at that error.  For any other non-@code{nil} value,
scrolling continues until there is no more output.
Glenn Morris's avatar
Glenn Morris committed
108 109 110

@findex recompile
  To rerun the last compilation with the same command, type @kbd{M-x
111 112
recompile}.  This reuses the compilation command from the last
invocation of @kbd{M-x compile}.  It also reuses the
113
@file{*compilation*} buffer and starts the compilation in its default
Glenn Morris's avatar
Glenn Morris committed
114
directory, which is the directory in which the previous compilation
115 116
was started.  In @file{*compilation*} buffers this command is bound to
@kbd{g}.
Glenn Morris's avatar
Glenn Morris committed
117 118

@findex kill-compilation
119
@vindex compilation-always-kill
Glenn Morris's avatar
Glenn Morris committed
120
  Starting a new compilation also kills any compilation already
121
running in @file{*compilation*}, as the buffer can only handle one
122 123 124 125 126 127
compilation at any time.  However, @kbd{M-x compile} and @kbd{M-x
recompile} ask for confirmation before actually killing a compilation
that is running; to always automatically kill the compilation without
asking, change the variable @code{compilation-always-kill} to
@code{t}.  You can also kill a compilation process with the command
@kbd{M-x kill-compilation}.
Glenn Morris's avatar
Glenn Morris committed
128

129
  To run two compilations at once, start the first one, then rename
130
the @file{*compilation*} buffer (perhaps using @code{rename-uniquely};
131
@pxref{Misc Buffer}), then switch buffers and start the other
132
compilation.  This will create a new @file{*compilation*} buffer.
Glenn Morris's avatar
Glenn Morris committed
133 134 135 136 137 138 139 140 141 142 143 144 145

@vindex compilation-environment
  You can control the environment passed to the compilation command
with the variable @code{compilation-environment}.  Its value is a list
of environment variable settings; each element should be a string of
the form @code{"@var{envvarname}=@var{value}"}.  These environment
variable settings override the usual ones.

@node Compilation Mode
@section Compilation Mode

@cindex Compilation mode
@cindex mode, Compilation
146
@cindex locus
147
  The @file{*compilation*} buffer uses a major mode called Compilation
148 149 150 151 152 153 154 155 156 157 158
mode.  Compilation mode turns each error message in the buffer into a
hyperlink; you can move point to it and type @key{RET}, or click on it
with the mouse (@pxref{Mouse References}), to visit the @dfn{locus} of
the error message in a separate window.  The locus is the specific
position in a file where that error occurred.

@findex compile-goto-error
@vindex compilation-auto-jump-to-first-error
  If you change the variable
@code{compilation-auto-jump-to-first-error} to a non-@code{nil} value,
Emacs automatically visits the locus of the first error message that
159
appears in the @file{*compilation*} buffer.
160 161

  Compilation mode provides the following additional commands.  These
162
commands can also be used in @file{*grep*} buffers, where the
163 164
hyperlinks are search matches rather than error messages (@pxref{Grep
Searching}).
Glenn Morris's avatar
Glenn Morris committed
165 166 167 168 169

@table @kbd
@item M-g M-n
@itemx M-g n
@itemx C-x `
170
Visit the locus of the next error message or match (@code{next-error}).
Glenn Morris's avatar
Glenn Morris committed
171 172
@item M-g M-p
@itemx M-g p
173 174
Visit the locus of the previous error message or match
(@code{previous-error}).
Glenn Morris's avatar
Glenn Morris committed
175
@item M-n
176 177
Move point to the next error message or match, without visiting its
locus (@code{compilation-next-error}).
Glenn Morris's avatar
Glenn Morris committed
178
@item M-p
179 180
Move point to the previous error message or match, without visiting
its locus (@code{compilation-previous-error}).
Glenn Morris's avatar
Glenn Morris committed
181
@item M-@}
182 183
Move point to the next error message or match occurring in a different
file (@code{compilation-next-file}).
Glenn Morris's avatar
Glenn Morris committed
184
@item M-@{
185 186
Move point to the previous error message or match occurring in a
different file (@code{compilation-previous-file}).
Glenn Morris's avatar
Glenn Morris committed
187 188 189
@item C-c C-f
Toggle Next Error Follow minor mode, which makes cursor motion in the
compilation buffer produce automatic source display.
190 191 192
@item g
Re-run the last command whose output is shown in the
@file{*compilation*} buffer.
Glenn Morris's avatar
Glenn Morris committed
193 194 195 196 197 198 199
@end table

@kindex M-g M-n
@kindex M-g n
@kindex C-x `
@findex next-error
@vindex next-error-highlight
200 201 202 203 204 205 206
  To visit errors sequentially, type @w{@kbd{C-x `}}
(@code{next-error}), or equivalently @kbd{M-g M-n} or @kbd{M-g n}.
This command can be invoked from any buffer, not just a Compilation
mode buffer.  The first time you invoke it after a compilation, it
visits the locus of the first error message.  Each subsequent
@w{@kbd{C-x `}} visits the next error, in a similar fashion.  If you
visit a specific error with @key{RET} or a mouse click in the
207
@file{*compilation*} buffer, subsequent @w{@kbd{C-x `}} commands
208 209 210 211 212 213 214 215
advance from there.  When @w{@kbd{C-x `}} finds no more error messages
to visit, it signals an error.  @w{@kbd{C-u C-x `}} starts again from
the beginning of the compilation buffer, and visits the first locus.

  @kbd{M-g M-p} or @kbd{M-g p} (@code{previous-error}) iterates
through errors in the opposite direction.

  The @code{next-error} and @code{previous-error} commands don't just
216 217
act on the errors or matches listed in @file{*compilation*} and
@file{*grep*} buffers; they also know how to iterate through error or
218
match lists produced by other commands, such as @kbd{M-x occur}
Eli Zaretskii's avatar
Eli Zaretskii committed
219 220 221 222 223 224 225
(@pxref{Other Repeating Search}).  If the current buffer contains
error messages or matches, these commands will iterate through them;
otherwise, Emacs looks for a buffer containing error messages or
matches amongst the windows of the selected frame, then for any buffer
that @code{next-error} or @code{previous-error} previously visited,
and finally all other buffers.  Any buffer these commands iterate
through that is not currently displayed in a window will be displayed.
Glenn Morris's avatar
Glenn Morris committed
226 227

@vindex compilation-skip-threshold
228 229 230 231 232 233 234 235 236 237 238 239
  By default, the @code{next-error} and @code{previous-error} commands
skip less important messages.  The variable
@code{compilation-skip-threshold} controls this.  The default value,
1, means to skip anything less important than a warning.  A value of 2
means to skip anything less important than an error, while 0 means not
to skip any messages.

  When Emacs visits the locus of an error message, it momentarily
highlights the relevant source line.  The duration of this highlight
is determined by the variable @code{next-error-highlight}.

@vindex compilation-context-lines
240
  If the @file{*compilation*} buffer is shown in a window with a left
241 242
fringe (@pxref{Fringes}), the locus-visiting commands put an arrow in
the fringe, pointing to the current error message.  If the window has
243 244 245 246 247 248 249
no left fringe, such as on a text terminal, these commands scroll the
window so that the current message is at the top of the window.  If
you change the variable @code{compilation-context-lines} to an integer
value @var{n}, these commands scroll the window so that the current
error message is @var{n} lines from the top, whether or not there is a
fringe; the default value, @code{nil}, gives the behavior described
above.
Glenn Morris's avatar
Glenn Morris committed
250 251 252 253 254

@vindex compilation-error-regexp-alist
@vindex grep-regexp-alist
  To parse messages from the compiler, Compilation mode uses the
variable @code{compilation-error-regexp-alist} which lists various
255 256 257
error message formats and tells Emacs how to extract the locus from
each.  A similar variable, @code{grep-regexp-alist}, tells Emacs how
to parse output from a @code{grep} command (@pxref{Grep Searching}).
Glenn Morris's avatar
Glenn Morris committed
258 259 260 261 262

@findex compilation-next-error
@findex compilation-previous-error
@findex compilation-next-file
@findex compilation-previous-file
263 264 265 266 267 268
  Compilation mode also defines the keys @key{SPC} and @key{DEL} to
scroll by screenfuls; @kbd{M-n} (@code{compilation-next-error}) and
@kbd{M-p} (@code{compilation-previous-error}) to move to the next or
previous error message; and @kbd{M-@{} (@code{compilation-next-file})
and @kbd{M-@}} (@code{compilation-previous-file}) to move to the next
or previous error message for a different source file.
Glenn Morris's avatar
Glenn Morris committed
269 270 271 272 273

@cindex Next Error Follow mode
@findex next-error-follow-minor-mode
  You can type @kbd{C-c C-f} to toggle Next Error Follow mode.  In
this minor mode, ordinary cursor motion in the compilation buffer
274
automatically updates the source buffer, i.e., moving the cursor over
275
an error message causes the locus of that error to be displayed.
Glenn Morris's avatar
Glenn Morris committed
276 277 278

  The features of Compilation mode are also available in a minor mode
called Compilation Minor mode.  This lets you parse error messages in
279 280 281 282 283
any buffer, not just a normal compilation output buffer.  Type
@kbd{M-x compilation-minor-mode} to enable the minor mode.  For
instance, in an Rlogin buffer (@pxref{Remote Host}), Compilation minor
mode automatically accesses remote source files by FTP (@pxref{File
Names}).
Glenn Morris's avatar
Glenn Morris committed
284 285 286 287

@node Compilation Shell
@section Subshells for Compilation

288 289 290 291 292 293
  This section includes various techniques and advice for using a
shell and its features in compilation buffers.  This material is
specific to local compilations, and will most probably not work in (or
be irrelevant to) compilation buffers whose default directory is on
remote hosts.

294 295 296 297
  The @kbd{M-x compile} command uses a shell to run the compilation
command, but specifies the option for a noninteractive shell.  This
means, in particular, that the shell should start with no prompt.  If
you find your usual shell prompt making an unsightly appearance in the
298
@file{*compilation*} buffer, it means you have made a mistake in your
299 300 301
shell's init file by setting the prompt unconditionally.  (This init
file may be named @file{.bashrc}, @file{.profile}, @file{.cshrc},
@file{.shrc}, etc., depending on what shell you use.)  The shell init
Glenn Morris's avatar
Glenn Morris committed
302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317
file should set the prompt only if there already is a prompt.  Here's
how to do it in bash:

@example
if [ "$@{PS1+set@}" = set ]
then PS1=@dots{}
fi
@end example

@noindent
And here's how to do it in csh:

@example
if ($?prompt) set prompt = @dots{}
@end example

318
@vindex TERM@r{, environment variable, in compilation mode}
319 320 321 322
  If you want to customize the value of the @env{TERM} environment
variable passed to the compilation subshell, customize the variable
@code{comint-terminfo-terminal} (@pxref{Shell Options}).

323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343
  Emacs does not expect a compiler process to launch asynchronous
subprocesses; if it does, and they keep running after the main
compiler process has terminated, Emacs may kill them or their output
may not arrive in Emacs.  To avoid this problem, make the main
compilation process wait for its subprocesses to finish.  In a shell
script, you can do this using @samp{$!} and @samp{wait}, like this:

@example
(sleep 10; echo 2nd)& pid=$!  # @r{Record pid of subprocess}
echo first message
wait $pid                     # @r{Wait for subprocess}
@end example

@noindent
If the background process does not output to the compilation buffer,
so you only need to prevent it from being killed when the main
compilation process terminates, this is sufficient:

@example
nohup @var{command}; sleep 1
@end example
Glenn Morris's avatar
Glenn Morris committed
344 345

@ifnottex
Paul Eggert's avatar
Paul Eggert committed
346
  On MS-DOS, asynchronous subprocesses are
347
not supported, so @kbd{M-x compile} runs the compilation command
348
synchronously (i.e., you must wait until the command finishes before
349
you can do anything else in Emacs).  @xref{MS-DOS}.
Glenn Morris's avatar
Glenn Morris committed
350 351 352 353 354 355
@end ifnottex

@node Grep Searching
@section Searching with Grep under Emacs

  Just as you can run a compiler from Emacs and then visit the lines
356 357
with compilation errors, you can also run @command{grep} and then
visit the lines on which matches were found.  This works by treating
Paul Eggert's avatar
Paul Eggert committed
358
the matches reported by @command{grep} as if they were errors.
359
The output buffer uses Grep mode, which is a variant of Compilation
Glenn Morris's avatar
Glenn Morris committed
360 361 362 363
mode (@pxref{Compilation Mode}).

@table @kbd
@item M-x grep
364
@itemx M-x lgrep
365
Run @command{grep} asynchronously under Emacs, listing matching lines in
366
the buffer named @file{*grep*}.
Glenn Morris's avatar
Glenn Morris committed
367 368 369
@item M-x grep-find
@itemx M-x find-grep
@itemx M-x rgrep
370
Run @command{grep} via @code{find}, and collect output in the
371
@file{*grep*} buffer.
372
@item M-x zrgrep
373
Run @code{zgrep} and collect output in the @file{*grep*} buffer.
Glenn Morris's avatar
Glenn Morris committed
374
@item M-x kill-grep
375
Kill the running @command{grep} subprocess.
Glenn Morris's avatar
Glenn Morris committed
376 377 378
@end table

@findex grep
379 380 381
  To run @command{grep}, type @kbd{M-x grep}, then enter a command line
that specifies how to run @command{grep}.  Use the same arguments you
would give @command{grep} when running it normally: a @command{grep}-style
Glenn Morris's avatar
Glenn Morris committed
382 383
regexp (usually in single-quotes to quote the shell's special
characters) followed by file names, which may use wildcards.  If you
384 385
specify a prefix argument for @kbd{M-x grep}, it finds the identifier
(@pxref{Xref}) in the buffer around point, and puts that into the
386
default @command{grep} command.
Glenn Morris's avatar
Glenn Morris committed
387

388
  Your command need not simply run @command{grep}; you can use any shell
Glenn Morris's avatar
Glenn Morris committed
389
command that produces output in the same format.  For instance, you
390
can chain @command{grep} commands, like this:
Glenn Morris's avatar
Glenn Morris committed
391 392 393 394 395

@example
grep -nH -e foo *.el | grep bar | grep toto
@end example

396
  The output from @command{grep} goes in the @file{*grep*} buffer.  You
Glenn Morris's avatar
Glenn Morris committed
397 398
can find the corresponding lines in the original files using @w{@kbd{C-x
`}}, @key{RET}, and so forth, just like compilation errors.
399 400
@xref{Compilation Mode}, for detailed description of commands and key
bindings available in the @file{*grep*} buffer.
Glenn Morris's avatar
Glenn Morris committed
401 402 403 404 405 406 407

  Some grep programs accept a @samp{--color} option to output special
markers around matches for the purpose of highlighting.  You can make
use of this feature by setting @code{grep-highlight-matches} to
@code{t}.  When displaying a match in the source buffer, the exact
match will be highlighted, instead of the entire source line.

408 409 410 411
  As with compilation commands (@pxref{Compilation}), while the grep
command runs, the mode line shows the running number of matches found
and highlighted so far.

412 413 414
  The @command{grep} commands will offer to save buffers before
running.  This is controlled by the @code{grep-save-buffers} variable.
The possible values are either @code{nil} (don't save), @code{ask}
415 416 417 418
(ask before saving), or a function which will be used as a predicate
(and is called with the file name as the parameter and should return
non-@code{nil} if the buffer is to be saved).  Any other
non-@code{nil} value means that all buffers should be saved without
419
asking.  The default is @code{ask}.
420

Glenn Morris's avatar
Glenn Morris committed
421 422 423 424 425
@findex grep-find
@findex find-grep
  The command @kbd{M-x grep-find} (also available as @kbd{M-x
find-grep}) is similar to @kbd{M-x grep}, but it supplies a different
initial default for the command---one that runs both @code{find} and
426
@command{grep}, so as to search every file in a directory tree.  See also
Glenn Morris's avatar
Glenn Morris committed
427 428 429 430
the @code{find-grep-dired} command, in @ref{Dired and Find}.

@findex lgrep
@findex rgrep
431
@findex zrgrep
Glenn Morris's avatar
Glenn Morris committed
432
  The commands @kbd{M-x lgrep} (local grep) and @kbd{M-x rgrep}
433
(recursive grep) are more user-friendly versions of @command{grep} and
Glenn Morris's avatar
Glenn Morris committed
434 435
@code{grep-find}, which prompt separately for the regular expression
to match, the files to search, and the base directory for the search.
436 437
Case sensitivity of the search is controlled by the current value of
@code{case-fold-search}.  The command @kbd{M-x zrgrep} is similar to
438 439
@kbd{M-x rgrep}, but it calls @command{zgrep} instead of
@command{grep} to search the contents of gzipped files.
Glenn Morris's avatar
Glenn Morris committed
440

441
  These commands build the shell commands based on the variables
Glenn Morris's avatar
Glenn Morris committed
442
@code{grep-template} (for @code{lgrep}) and @code{grep-find-template}
443 444
(for @code{rgrep}).  The files to search can use aliases defined in
the variable @code{grep-files-aliases}.
Glenn Morris's avatar
Glenn Morris committed
445

446 447 448 449 450
@vindex grep-find-ignored-directories
  Directories listed in the variable
@code{grep-find-ignored-directories} are automatically skipped by
@kbd{M-x rgrep}.  The default value includes the data directories used
by various version control systems.
Glenn Morris's avatar
Glenn Morris committed
451 452 453 454 455 456 457

@node Flymake
@section Finding Syntax Errors On The Fly
@cindex checking syntax

  Flymake mode is a minor mode that performs on-the-fly syntax
checking for many programming and markup languages, including C, C++,
458
Perl, HTML, and @TeX{}/@LaTeX{}.  It is somewhat analogous to Flyspell
Glenn Morris's avatar
Glenn Morris committed
459 460 461 462 463 464 465 466 467
mode, which performs spell checking for ordinary human languages in a
similar fashion (@pxref{Spelling}).  As you edit a file, Flymake mode
runs an appropriate syntax checking tool in the background, using a
temporary copy of the buffer.  It then parses the error and warning
messages, and highlights the erroneous lines in the buffer.  The
syntax checking tool used depends on the language; for example, for
C/C++ files this is usually the C compiler.  Flymake can also use
build tools such as @code{make} for checking complicated projects.

468 469 470 471 472
  To enable Flymake mode, type @kbd{M-x flymake-mode}.  You can jump
to the errors that it finds by using @kbd{M-x flymake-goto-next-error}
and @kbd{M-x flymake-goto-prev-error}.  To display any error messages
associated with the current line, type @kbd{M-x
flymake-display-err-menu-for-current-line}.
Glenn Morris's avatar
Glenn Morris committed
473

474 475 476 477 478 479 480
  For more details about using Flymake,
@ifnottex
see @ref{Top, Flymake, Flymake, flymake, The Flymake Manual}.
@end ifnottex
@iftex
see the Flymake Info manual, which is distributed with Emacs.
@end iftex
Glenn Morris's avatar
Glenn Morris committed
481 482 483 484 485 486 487 488 489 490 491 492 493

@node Debuggers
@section Running Debuggers Under Emacs
@cindex debuggers
@cindex GUD library
@cindex GDB
@cindex DBX
@cindex SDB
@cindex XDB
@cindex Perldb
@cindex JDB
@cindex PDB

Chong Yidong's avatar
Chong Yidong committed
494
The GUD (Grand Unified Debugger) library provides an Emacs interface
495
to a wide variety of symbolic debuggers.  It can run the GNU Debugger
496 497
(GDB), as well as DBX, SDB, XDB, Guile REPL debug commands, Perl's
debugging mode, the Python debugger PDB, and the Java Debugger JDB.
Glenn Morris's avatar
Glenn Morris committed
498

499 500 501 502 503 504 505
  Emacs provides a special interface to GDB, which uses extra Emacs
windows to display the state of the debugged program.  @xref{GDB
Graphical Interface}.

  Emacs also has a built-in debugger for Emacs Lisp programs.
@xref{Debugging,, The Lisp Debugger, elisp, the Emacs Lisp Reference
Manual}.
506

Glenn Morris's avatar
Glenn Morris committed
507
@menu
508 509 510 511
* Starting GUD::        How to start a debugger subprocess.
* Debugger Operation::  Connection between the debugger and source buffers.
* Commands of GUD::     Key bindings for common commands.
* GUD Customization::   Defining your own commands for GUD.
512
* GDB Graphical Interface::  An enhanced mode that uses GDB features to
Glenn Morris's avatar
Glenn Morris committed
513
                        implement a graphical debugging environment.
Glenn Morris's avatar
Glenn Morris committed
514 515 516
@end menu

@node Starting GUD
517
@subsection Starting GUD
Glenn Morris's avatar
Glenn Morris committed
518

519
  There are several commands for starting a debugger subprocess, each
Chong Yidong's avatar
Chong Yidong committed
520
corresponding to a particular debugger program.
Glenn Morris's avatar
Glenn Morris committed
521 522

@table @kbd
523
@item M-x gdb
524
@findex gdb
525 526 527
Run GDB as a subprocess, and interact with it via an IDE-like Emacs
interface.  @xref{GDB Graphical Interface}, for more information about
this command.
528

529
@item M-x gud-gdb
530
@findex gud-gdb
531 532 533
Run GDB, using a GUD interaction buffer for input and output to the
GDB subprocess (@pxref{Debugger Operation}).  If such a buffer already
exists, switch to it; otherwise, create the buffer and switch to it.
Glenn Morris's avatar
Glenn Morris committed
534

535 536
The other commands in this list do the same, for other debugger
programs.
Glenn Morris's avatar
Glenn Morris committed
537

538
@item M-x perldb
Glenn Morris's avatar
Glenn Morris committed
539
@findex perldb
540
Run the Perl interpreter in debug mode.
Glenn Morris's avatar
Glenn Morris committed
541

542
@item M-x jdb
Glenn Morris's avatar
Glenn Morris committed
543
@findex jdb
544
Run the Java debugger.
Glenn Morris's avatar
Glenn Morris committed
545

546
@item M-x pdb
Glenn Morris's avatar
Glenn Morris committed
547
@findex pdb
548 549
Run the Python debugger.

550 551 552 553
@item M-x guiler
@findex guiler
Run Guile REPL for debugging Guile Scheme programs.

554 555 556 557 558 559 560 561 562 563 564 565
@item M-x dbx
@findex dbx
Run the DBX debugger.

@item M-x xdb
@findex xdb
@vindex gud-xdb-directories
Run the XDB debugger.

@item M-x sdb
@findex sdb
Run the SDB debugger.
Glenn Morris's avatar
Glenn Morris committed
566 567
@end table

568 569 570 571 572 573 574
  Each of these commands reads a command line to invoke the debugger,
using the minibuffer.  The minibuffer's initial contents contain the
standard executable name and options for the debugger, and sometimes
also a guess for the name of the executable file you want to debug.
Shell wildcards and variables are not allowed in this command line.
Emacs assumes that the first command argument which does not start
with a @samp{-} is the executable file name.
Glenn Morris's avatar
Glenn Morris committed
575

Chong Yidong's avatar
Chong Yidong committed
576
@cindex remote host, debugging on
577 578 579 580 581 582 583
  Tramp provides a facility for remote debugging, whereby both the
debugger and the program being debugged are on the same remote host.
@xref{Running a debugger on a remote host,,, tramp, The Tramp Manual},
for details.  This is separate from GDB's remote debugging feature,
where the program and the debugger run on different machines
(@pxref{Remote Debugging,, Debugging Remote Programs, gdb, The GNU
debugger}).
Glenn Morris's avatar
Glenn Morris committed
584 585

@node Debugger Operation
586
@subsection Debugger Operation
587
@cindex GUD interaction buffer
Glenn Morris's avatar
Glenn Morris committed
588

589 590 591 592 593 594
  The @dfn{GUD interaction buffer} is an Emacs buffer which is used to
send text commands to a debugger subprocess, and record its output.
This is the basic interface for interacting with a debugger, used by
@kbd{M-x gud-gdb} and other commands listed in
@iftex
the preceding section.
595
@end iftex
596 597 598 599 600 601 602 603 604 605 606 607 608 609
@ifnottex
@ref{Starting GUD}.
@end ifnottex
The @kbd{M-x gdb} command extends this interface with additional
specialized buffers for controlling breakpoints, stack frames, and
other aspects of the debugger state (@pxref{GDB Graphical Interface}).

  The GUD interaction buffer uses a variant of Shell mode, so the
Emacs commands defined by Shell mode are available (@pxref{Shell
Mode}).  Completion is available for most debugger commands
(@pxref{Completion}), and you can use the usual Shell mode history
commands to repeat them.
@iftex
See the next section
610
@end iftex
611 612 613 614 615 616 617
@ifnottex
@xref{Commands of GUD},
@end ifnottex
for special commands that can be used in the GUD interaction buffer.

  As you debug a program, Emacs displays the relevant source files by
visiting them in Emacs buffers, with an arrow in the left fringe
618 619 620 621 622 623
indicating the current execution line.  (On a text terminal, the arrow
appears as @samp{=>}, overlaid on the first two text columns.)  Moving
point in such a buffer does not move the arrow.  You are free to edit
these source files, but note that inserting or deleting lines will
throw off the arrow's positioning, as Emacs has no way to figure out
which edited source line corresponds to the line reported by the
624 625 626 627 628 629
debugger subprocess.  To update this information, you typically have
to recompile and restart the program.

@cindex GUD Tooltip mode
@cindex mode, GUD Tooltip
@findex gud-tooltip-mode
Glenn Morris's avatar
Glenn Morris committed
630
@vindex gud-tooltip-echo-area
631
  GUD Tooltip mode is a global minor mode that adds tooltip support to
632
GUD@.  To toggle this mode, type @kbd{M-x gud-tooltip-mode}.  It is
633
disabled by default.  If enabled, you can move the mouse pointer over a
634 635
variable, a function, or a macro (collectively called
@dfn{identifiers}) to show their values in tooltips
636 637 638 639 640 641 642
(@pxref{Tooltips}).  If just placing the mouse pointer over an
expression doesn't show the value of the expression you had in mind,
you can tell Emacs more explicitly what expression to evaluate by
dragging the mouse over the expression, then leaving the mouse inside
the marked area.  The GUD Tooltip mode takes effect in the GUD
interaction buffer, and in all source buffers with major modes listed
in the variable @code{gud-tooltip-modes}.  If the variable
643 644 645 646 647 648 649 650 651 652 653
@code{gud-tooltip-echo-area} is non-@code{nil}, or if you turned off
the tooltip mode, values are shown in the echo area instead of a
tooltip.

  When using GUD Tooltip mode with @kbd{M-x gud-gdb}, displaying an
expression's value in GDB can sometimes expand a macro, potentially
causing side effects in the debugged program.  For that reason, using
tooltips in @code{gud-gdb} is disabled.  If you use the @kbd{M-x gdb}
interface, this problem does not occur, as there is special code to
avoid side-effects; furthermore, you can display macro definitions
associated with an identifier when the program is not executing.
Glenn Morris's avatar
Glenn Morris committed
654 655

@node Commands of GUD
656
@subsection Commands of GUD
Glenn Morris's avatar
Glenn Morris committed
657

658 659
  GUD provides commands for setting and clearing breakpoints,
selecting stack frames, and stepping through the program.
Glenn Morris's avatar
Glenn Morris committed
660 661

@table @kbd
662 663
@item C-x C-a C-b
@kindex C-x C-a C-b
Glenn Morris's avatar
Glenn Morris committed
664 665 666
Set a breakpoint on the source line that point is on.
@end table

667
  @kbd{C-x C-a C-b} (@code{gud-break}), when called in a source
668
buffer, sets a debugger breakpoint on the current source line.  This
669
command is available only after starting GUD@.  If you call it in a
670
buffer that is not associated with any debugger subprocess, it signals
671
an error.
672

Glenn Morris's avatar
Glenn Morris committed
673
@kindex C-x C-a @r{(GUD)}
674 675
  The following commands are available both in the GUD interaction
buffer and globally, but with different key bindings.  The keys
Glenn Morris's avatar
Glenn Morris committed
676
starting with @kbd{C-c} are available only in the GUD interaction
677 678 679
buffer, while those starting with @kbd{C-x C-a} are available
globally.  Some of these commands are also available via the tool bar;
some are not supported by certain debuggers.
Glenn Morris's avatar
Glenn Morris committed
680 681 682 683 684 685

@table @kbd
@item C-c C-l
@kindex C-c C-l @r{(GUD)}
@itemx C-x C-a C-l
@findex gud-refresh
686 687
Display, in another window, the last source line referred to in the
GUD interaction buffer (@code{gud-refresh}).
Glenn Morris's avatar
Glenn Morris committed
688 689 690 691 692

@item C-c C-s
@kindex C-c C-s @r{(GUD)}
@itemx C-x C-a C-s
@findex gud-step
693 694 695
Execute the next single line of code (@code{gud-step}).  If the line
contains a function call, execution stops after entering the called
function.
Glenn Morris's avatar
Glenn Morris committed
696 697 698 699 700

@item C-c C-n
@kindex C-c C-n @r{(GUD)}
@itemx C-x C-a C-n
@findex gud-next
701 702
Execute the next single line of code, stepping across function calls
without stopping inside the functions (@code{gud-next}).
Glenn Morris's avatar
Glenn Morris committed
703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789

@item C-c C-i
@kindex C-c C-i @r{(GUD)}
@itemx C-x C-a C-i
@findex gud-stepi
Execute a single machine instruction (@code{gud-stepi}).

@item C-c C-p
@kindex C-c C-p @r{(GUD)}
@itemx C-x C-a C-p
@findex gud-print
Evaluate the expression at point (@code{gud-print}).  If Emacs
does not print the exact expression that you want, mark it as a region
first.

@need 3000
@item C-c C-r
@kindex C-c C-r @r{(GUD)}
@itemx C-x C-a C-r
@findex gud-cont
Continue execution without specifying any stopping point.  The program
will run until it hits a breakpoint, terminates, or gets a signal that
the debugger is checking for (@code{gud-cont}).

@need 1000
@item C-c C-d
@kindex C-c C-d @r{(GUD)}
@itemx C-x C-a C-d
@findex gud-remove
Delete the breakpoint(s) on the current source line, if any
(@code{gud-remove}).  If you use this command in the GUD interaction
buffer, it applies to the line where the program last stopped.

@item C-c C-t
@kindex C-c C-t @r{(GUD)}
@itemx C-x C-a C-t
@findex gud-tbreak
Set a temporary breakpoint on the current source line, if any
(@code{gud-tbreak}).  If you use this command in the GUD interaction
buffer, it applies to the line where the program last stopped.

@item C-c <
@kindex C-c < @r{(GUD)}
@itemx C-x C-a <
@findex gud-up
Select the next enclosing stack frame (@code{gud-up}).  This is
equivalent to the GDB command @samp{up}.

@item C-c >
@kindex C-c > @r{(GUD)}
@itemx C-x C-a >
@findex gud-down
Select the next inner stack frame (@code{gud-down}).  This is
equivalent to the GDB command @samp{down}.

@item C-c C-u
@kindex C-c C-u @r{(GUD)}
@itemx C-x C-a C-u
@findex gud-until
Continue execution to the current line (@code{gud-until}).  The
program will run until it hits a breakpoint, terminates, gets a signal
that the debugger is checking for, or reaches the line on which the
cursor currently sits.

@item C-c C-f
@kindex C-c C-f @r{(GUD)}
@itemx C-x C-a C-f
@findex gud-finish
Run the program until the selected stack frame returns or
stops for some other reason (@code{gud-finish}).
@end table

  If you are using GDB, these additional key bindings are available:

@table @kbd
@item C-x C-a C-j
@kindex C-x C-a C-j @r{(GUD)}
@findex gud-jump
Only useful in a source buffer, @code{gud-jump} transfers the
program's execution point to the current line.  In other words, the
next line that the program executes will be the one where you gave the
command.  If the new execution line is in a different function from
the previously one, GDB prompts for confirmation since the results may
be bizarre.  See the GDB manual entry regarding @code{jump} for
details.

@item @key{TAB}
790
@kindex TAB @r{(GUD)}
Glenn Morris's avatar
Glenn Morris committed
791 792 793 794 795 796 797 798 799
@findex gud-gdb-complete-command
With GDB, complete a symbol name (@code{gud-gdb-complete-command}).
This key is available only in the GUD interaction buffer.
@end table

  These commands interpret a numeric argument as a repeat count, when
that makes sense.

  Because @key{TAB} serves as a completion command, you can't use it to
800
enter a tab as input to the program you are debugging with GDB@.
Glenn Morris's avatar
Glenn Morris committed
801 802 803
Instead, type @kbd{C-q @key{TAB}} to enter a tab.

@node GUD Customization
804
@subsection GUD Customization
Glenn Morris's avatar
Glenn Morris committed
805 806 807 808 809 810 811 812

@vindex gdb-mode-hook
@vindex dbx-mode-hook
@vindex sdb-mode-hook
@vindex xdb-mode-hook
@vindex perldb-mode-hook
@vindex pdb-mode-hook
@vindex jdb-mode-hook
813
@vindex guiler-mode-hook
814 815 816
  On startup, GUD runs one of the following hooks:
@code{gdb-mode-hook}, if you are using GDB; @code{dbx-mode-hook}, if
you are using DBX; @code{sdb-mode-hook}, if you are using SDB;
817 818 819 820
@code{xdb-mode-hook}, if you are using XDB; @code{guiler-mode-hook}
for Guile REPL debugging; @code{perldb-mode-hook}, for Perl debugging
mode; @code{pdb-mode-hook}, for PDB; @code{jdb-mode-hook}, for JDB@.
@xref{Hooks}.
821 822 823 824 825

  The @code{gud-def} Lisp macro (@pxref{Defining Macros,,, elisp, the
Emacs Lisp Reference Manual}) provides a convenient way to define an
Emacs command that sends a particular command string to the debugger,
and set up a key binding for in the GUD interaction buffer:
Glenn Morris's avatar
Glenn Morris committed
826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845

@findex gud-def
@example
(gud-def @var{function} @var{cmdstring} @var{binding} @var{docstring})
@end example

  This defines a command named @var{function} which sends
@var{cmdstring} to the debugger process, and gives it the documentation
string @var{docstring}.  You can then use the command @var{function} in any
buffer.  If @var{binding} is non-@code{nil}, @code{gud-def} also binds
the command to @kbd{C-c @var{binding}} in the GUD buffer's mode and to
@kbd{C-x C-a @var{binding}} generally.

  The command string @var{cmdstring} may contain certain
@samp{%}-sequences that stand for data to be filled in at the time
@var{function} is called:

@table @samp
@item %f
The name of the current source file.  If the current buffer is the GUD
Paul Eggert's avatar
Paul Eggert committed
846
buffer, then the current source file is the file that the program
Glenn Morris's avatar
Glenn Morris committed
847 848 849 850
stopped in.

@item %l
The number of the current source line.  If the current buffer is the GUD
Paul Eggert's avatar
Paul Eggert committed
851
buffer, then the current source line is the line that the program
Glenn Morris's avatar
Glenn Morris committed
852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880
stopped in.

@item %e
In transient-mark-mode the text in the region, if it is active.
Otherwise the text of the C lvalue or function-call expression at or
adjacent to point.

@item %a
The text of the hexadecimal address at or adjacent to point.

@item %p
The numeric argument of the called function, as a decimal number.  If
the command is used without a numeric argument, @samp{%p} stands for the
empty string.

If you don't use @samp{%p} in the command string, the command you define
ignores any numeric argument.

@item %d
The name of the directory of the current source file.

@item %c
Fully qualified class name derived from the expression surrounding point
(jdb only).
@end table

@node GDB Graphical Interface
@subsection GDB Graphical Interface

881 882 883 884 885
  The command @kbd{M-x gdb} starts GDB in an IDE-like interface, with
specialized buffers for controlling breakpoints, stack frames, and
other aspects of the debugger state.  It also provides additional ways
to control the debugging session with the mouse, such as clicking in
the fringe of a source buffer to set a breakpoint there.
Glenn Morris's avatar
Glenn Morris committed
886 887

@vindex gud-gdb-command-name
888 889 890 891 892 893
  To run GDB using just the GUD interaction buffer interface, without
these additional features, use @kbd{M-x gud-gdb} (@pxref{Starting
GUD}).  You must use this if you want to debug multiple programs
within one Emacs session, as that is currently unsupported by @kbd{M-x
gdb}.

Paul Eggert's avatar
Paul Eggert committed
894
  Internally, @kbd{M-x gdb} informs GDB that its screen size is
895 896
unlimited; for correct operation, you must not change GDB's screen
height and width values during the debugging session.
Glenn Morris's avatar
Glenn Morris committed
897 898

@menu
899
* GDB User Interface Layout::   Control the number of displayed buffers.
Glenn Morris's avatar
Glenn Morris committed
900 901 902
* Source Buffers::              Use the mouse in the fringe/margin to
                                control your program.
* Breakpoints Buffer::          A breakpoint control panel.
903
* Threads Buffer::              Displays your threads.
Glenn Morris's avatar
Glenn Morris committed
904
* Stack Buffer::                Select a frame from the call stack.
905
* Other GDB Buffers::           Other buffers for controlling the GDB state.
Glenn Morris's avatar
Glenn Morris committed
906
* Watch Expressions::           Monitor variable values in the speedbar.
907
* Multithreaded Debugging::     Debugging programs with several threads.
Glenn Morris's avatar
Glenn Morris committed
908 909
@end menu

910
@node GDB User Interface Layout
Glenn Morris's avatar
Glenn Morris committed
911 912 913 914
@subsubsection GDB User Interface Layout
@cindex GDB User Interface layout

@vindex gdb-many-windows
915
@vindex gdb-show-main
916 917
  If the variable @code{gdb-many-windows} is @code{nil} (the default),
@kbd{M-x gdb} normally displays only the GUD interaction buffer.
Glenn Morris's avatar
Glenn Morris committed
918
However, if the variable @code{gdb-show-main} is also non-@code{nil},
919 920 921
it starts with two windows: one displaying the GUD interaction buffer,
and the other showing the source for the @code{main} function of the
program you are debugging.
Glenn Morris's avatar
Glenn Morris committed
922 923 924 925 926 927 928

  If @code{gdb-many-windows} is non-@code{nil}, then @kbd{M-x gdb}
displays the following frame layout:

@smallexample
@group
+--------------------------------+--------------------------------+
929
|   GUD interaction buffer       |   Locals/Registers buffer      |
Glenn Morris's avatar
Glenn Morris committed
930 931 932
|--------------------------------+--------------------------------+
|   Primary Source buffer        |   I/O buffer for debugged pgm  |
|--------------------------------+--------------------------------+
933
|   Stack buffer                 |   Breakpoints/Threads buffer   |
Glenn Morris's avatar
Glenn Morris committed
934 935 936 937 938 939
+--------------------------------+--------------------------------+
@end group
@end smallexample

@findex gdb-restore-windows
@findex gdb-many-windows
Paul Eggert's avatar
Paul Eggert committed
940 941
  If you ever change the window layout, you can restore the many-windows
layout by typing @kbd{M-x gdb-restore-windows}.  To toggle
942 943
between the many windows layout and a simple layout with just the GUD
interaction buffer and a source file, type @kbd{M-x gdb-many-windows}.
Glenn Morris's avatar
Glenn Morris committed
944

945 946 947 948 949 950 951 952
  If you have an elaborate window setup, and don't want
@code{gdb-many-windows} to disrupt that, it is better to invoke
@kbd{M-x gdb} in a separate frame to begin with, then the arrangement
of windows on your original frame will not be affected.  A separate
frame for GDB sessions can come in especially handy if you work on a
text-mode terminal, where the screen estate for windows could be at a
premium.

Glenn Morris's avatar
Glenn Morris committed
953 954
  You may also specify additional GDB-related buffers to display,
either in the same frame or a different one.  Select the buffers you
955 956
want by typing @kbd{M-x gdb-display-@var{buffertype}-buffer} or
@kbd{M-x gdb-frame-@var{buffertype}-buffer}, where @var{buffertype}
957 958 959 960 961 962 963 964 965 966 967 968 969
is the relevant buffer type, such as @samp{breakpoints}.  You can do
the same with the menu bar, with the @samp{GDB-Windows} and
@samp{GDB-Frames} sub-menus of the @samp{GUD} menu.

  When you finish debugging, kill the GUD interaction buffer with
@kbd{C-x k}, which will also kill all the buffers associated with the
session.  However you need not do this if, after editing and
re-compiling your source code within Emacs, you wish to continue
debugging.  When you restart execution, GDB automatically finds the
new executable.  Keeping the GUD interaction buffer has the advantage
of keeping the shell history as well as GDB's breakpoints.  You do
need to check that the breakpoints in recently edited source files are
still in the right places.
Glenn Morris's avatar
Glenn Morris committed
970 971 972

@node Source Buffers
@subsubsection Source Buffers
973
@cindex fringes, for debugging
Glenn Morris's avatar
Glenn Morris committed
974

975
@table @asis
976
@item @kbd{mouse-1} (in fringe)
977 978
Set or clear a breakpoint on that line
(@code{gdb-mouse-set-clear-breakpoint}).
Glenn Morris's avatar
Glenn Morris committed
979

980
@item @kbd{C-mouse-1} (in fringe)
981 982
Enable or disable a breakpoint on that line
(@code{gdb-mouse-toggle-breakpoint-margin}).
Glenn Morris's avatar
Glenn Morris committed
983

984
@item @kbd{mouse-3} (in fringe)
985
Continue execution to that line (@code{gdb-mouse-until}).
Glenn Morris's avatar
Glenn Morris committed
986

987
@item @kbd{C-mouse-3} (in fringe)
988
Jump to that line (@code{gdb-mouse-jump}).
Glenn Morris's avatar
Glenn Morris committed
989 990
@end table

991
  On a graphical display, you can click @kbd{mouse-1} in the fringe of
992 993
a source buffer, to set a breakpoint on that line (@pxref{Fringes}).
A red dot appears in the fringe, where you clicked.  If a breakpoint
994
already exists there, the click removes it.  A @kbd{C-mouse-1} click
995 996 997
enables or disables an existing breakpoint; a breakpoint that is
disabled, but not unset, is indicated by a gray dot.

998
  On a text terminal, or when fringes are disabled, enabled
999 1000 1001 1002 1003
breakpoints are indicated with a @samp{B} character in the left margin
of the window.  Disabled breakpoints are indicated with @samp{b}.
(The margin is only displayed if a breakpoint is present.)

  A solid arrow in the left fringe of a source buffer indicates the
1004
line of the innermost frame where the debugged program has stopped.  A
1005
hollow arrow indicates the current execution line of a higher-level
1006
frame.  If you drag the arrow in the fringe with @kbd{mouse-1}, that
1007
causes execution to advance to the line where you release the button.
1008 1009
Alternatively, you can click @kbd{mouse-3} in the fringe to advance to
that line.  You can click @kbd{C-mouse-3} in the fringe to jump to
1010 1011 1012 1013
that line without executing the intermediate lines.  This command
allows you to go backwards, which can be useful for running through
code that has already executed, in order to examine its execution in
more detail.
Glenn Morris's avatar
Glenn Morris committed
1014

1015 1016 1017 1018 1019 1020 1021 1022 1023
@vindex gdb-mi-decode-strings
  If the file names of the source files are shown with octal escapes,
set the variable @code{gdb-mi-decode-strings} to the appropriate
coding-system, most probably @code{utf-8}.  (This is @code{nil} by
default because GDB may emit octal escapes in situations where
decoding is undesirable, and also because the program being debugged
might use an encoding different from the one used to encode non-ASCII
file names on your system.)

Glenn Morris's avatar
Glenn Morris committed
1024 1025 1026
@node Breakpoints Buffer
@subsubsection Breakpoints Buffer

1027 1028 1029 1030
  The GDB Breakpoints buffer shows the breakpoints, watchpoints and
catchpoints in the debugger session.  @xref{Breakpoints,,, gdb, The
GNU debugger}.  It provides the following commands, which mostly apply
to the @dfn{current breakpoint} (the breakpoint which point is on):
Glenn Morris's avatar
Glenn Morris committed
1031 1032 1033

@table @kbd
@item @key{SPC}
1034
@kindex SPC @r{(GDB Breakpoints buffer)}
Glenn Morris's avatar
Glenn Morris committed
1035
@findex gdb-toggle-breakpoint
1036 1037 1038 1039
Enable/disable current breakpoint (@code{gdb-toggle-breakpoint}).  On
a graphical display, this changes the color of the dot in the fringe
of the source buffer at that line.  The dot is red when the breakpoint
is enabled, and gray when it is disabled.
Glenn Morris's avatar
Glenn Morris committed
1040 1041

@item D
1042
@kindex D @r{(GDB Breakpoints buffer)}
Glenn Morris's avatar
Glenn Morris committed
1043 1044 1045 1046
@findex gdb-delete-breakpoint
Delete the current breakpoint (@code{gdb-delete-breakpoint}).

@item @key{RET}
1047
@kindex RET @r{(GDB Breakpoints buffer)}
Glenn Morris's avatar
Glenn Morris committed
1048 1049 1050 1051
@findex gdb-goto-breakpoint
Visit the source line for the current breakpoint
(@code{gdb-goto-breakpoint}).

1052 1053
@item mouse-2
@kindex mouse-2 @r{(GDB Breakpoints buffer)}
1054 1055
Visit the source line for the breakpoint you click on
(@code{gdb-goto-breakpoint}).
Glenn Morris's avatar
Glenn Morris committed
1056 1057
@end table

1058
@vindex gdb-show-threads-by-default
1059 1060
  When @code{gdb-many-windows} is non-@code{nil}, the GDB Breakpoints
buffer shares its window with the GDB Threads buffer.  To switch from
1061
one to the other click with @kbd{mouse-1} on the relevant button in
1062 1063
the header line.  If @code{gdb-show-threads-by-default} is
non-@code{nil}, the GDB Threads buffer is the one shown by default.
1064 1065 1066 1067 1068

@node Threads Buffer
@subsubsection Threads Buffer

@findex gdb-select-thread
1069 1070 1071
  The GDB Threads buffer displays a summary of the threads in the
debugged program.  @xref{Threads, Threads, Debugging programs with
multiple threads, gdb, The GNU debugger}.  To select a thread, move
1072
point there and press @key{RET} (@code{gdb-select-thread}), or click on
1073
it with @kbd{mouse-2}.  This also displays the associated source
1074
buffer, and updates the contents of the other GDB buffers.
1075

1076 1077
  You can customize variables in the @code{gdb-buffers} group to
select fields included in GDB Threads buffer.
1078 1079 1080 1081

@table @code
@item gdb-thread-buffer-verbose-names
@vindex gdb-thread-buffer-verbose-names
1082
Show long thread names like @samp{Thread 0x4e2ab70 (LWP 1983)}.
1083 1084 1085

@item gdb-thread-buffer-arguments
@vindex gdb-thread-buffer-arguments
1086
Show arguments of thread top frames.
1087 1088 1089

@item gdb-thread-buffer-locations
@vindex gdb-thread-buffer-locations
1090
Show file information or library names.
1091 1092 1093 1094 1095 1096

@item gdb-thread-buffer-addresses
@vindex gdb-thread-buffer-addresses
Show addresses for thread frames in threads buffer.
@end table

1097 1098
  To view information for several threads simultaneously, use the
following commands from the GDB Threads buffer.
1099 1100 1101 1102 1103

@table @kbd
@item d
@kindex d @r{(GDB threads buffer)}
@findex gdb-display-disassembly-for-thread
1104 1105
Display disassembly buffer for the thread at current line
(@code{gdb-display-disassembly-for-thread}).
1106 1107 1108 1109

@item f
@kindex f @r{(GDB threads buffer)}
@findex gdb-display-stack-for-thread
1110
Display the GDB Stack buffer for the thread at current line
1111 1112 1113 1114 1115
(@code{gdb-display-stack-for-thread}).

@item l
@kindex l @r{(GDB threads buffer)}
@findex gdb-display-locals-for-thread
1116
Display the GDB Locals buffer for the thread at current line
1117 1118 1119 1120 1121
(@code{gdb-display-locals-for-thread}).

@item r
@kindex r @r{(GDB threads buffer)}
@findex gdb-display-registers-for-thread
1122
Display the GDB Registers buffer for the thread at current line
1123 1124 1125
(@code{gdb-display-registers-for-thread}).
@end table

1126 1127 1128
@noindent
Their upper-case counterparts, @kbd{D}, @kbd{F} ,@kbd{L} and @kbd{R},
display the corresponding buffer in a new frame.
1129 1130 1131

  When you create a buffer showing information about some specific
thread, it becomes bound to that thread and keeps showing actual
1132
information while you debug your program.  The mode indicator for each
1133 1134 1135
GDB buffer shows the number of the thread whose information that
buffer displays.  The thread number is also included in the name of
each bound buffer.
1136

1137 1138 1139
  Further commands are available in the GDB Threads buffer which
depend on the mode of GDB that is used for controlling execution of
your program.  @xref{Multithreaded Debugging}.
1140

Glenn Morris's avatar
Glenn Morris committed
1141 1142 1143
@node Stack Buffer
@subsubsection Stack Buffer

1144 1145 1146 1147
  The GDB Stack buffer displays a @dfn{call stack}, with one line for
each of the nested subroutine calls (@dfn{stack frames}) in the
debugger session.  @xref{Backtrace,, Backtraces, gdb, The GNU
debugger}.
Glenn Morris's avatar
Glenn Morris committed
1148 1149

@findex gdb-frames-select
1150
  On graphical displays, the selected stack frame is indicated by an
1151 1152 1153
arrow in the fringe.  On text terminals, or when fringes are disabled,
the selected stack frame is displayed in reverse contrast.  To select
a stack frame, move point in its line and type @key{RET}
1154
(@code{gdb-frames-select}), or click @kbd{mouse-2} on it.  Doing so
1155 1156 1157 1158 1159 1160 1161
also updates the Locals buffer
@ifnottex
(@pxref{Other GDB Buffers}).
@end ifnottex
@iftex
(described in the next section).
@end iftex
Glenn Morris's avatar
Glenn Morris committed
1162

1163 1164 1165 1166 1167
@vindex gdb-stack-buffer-addresses
  If you want the frame address to be shown each stack frame,
customize the variable @code{gdb-stack-buffer-addresses} to a
non-@code{nil} value.

1168
@node Other GDB Buffers
1169
@subsubsection Other GDB Buffers
Glenn Morris's avatar
Glenn Morris committed
1170 1171 1172

@table @asis
@item Locals Buffer
1173 1174
This buffer displays the values of local variables of the current
frame for simple data types (@pxref{Frame Info, Frame Info,
1175
Information on a frame, gdb, The GNU debugger}).  Press @key{RET} or
Lars Ingebrigtsen's avatar