building.texi 63.8 KB
Newer Older
Glenn Morris's avatar
Glenn Morris committed
1
@c This is part of the Emacs manual.
2
@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011
3
@c   Free Software Foundation, Inc.
Glenn Morris's avatar
Glenn Morris committed
4 5 6 7 8 9 10
@c See file emacs.texi for copying conditions.
@node Building, Maintaining, Programs, Top
@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 47 48 49 50 51 52 53 54 55

@table @kbd
@item M-x compile
Run a compiler asynchronously under Emacs, with error messages going to
the @samp{*compilation*} buffer.
@item M-x recompile
Invoke a compiler with the same command as in the last invocation of
@kbd{M-x compile}.
@item M-x kill-compilation
Kill the running compilation subprocess.
@end table

@findex compile
56 57
  To run @code{make} or another compilation command, type @kbd{M-x
compile}.  This reads a shell command line using the minibuffer, and
58 59 60 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
named @samp{*compilation*}.  The current buffer's default directory is
used as the working directory for the execution of the command;
normally, therefore, compilation takes place in this directory.
Glenn Morris's avatar
Glenn Morris committed
63 64

@vindex compile-command
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
  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}).

  Starting a compilation displays the @samp{*compilation*} buffer in
another window but does not select it.  While the compilation is
running, the word @samp{run} is shown in the major mode indicator for
the @samp{*compilation*} buffer, and the word @samp{Compiling} appears
in all mode lines.  You do not have to keep the @samp{*compilation*}
buffer visible while compilation is running; it continues in any case.
When the compilation ends, for whatever reason, the mode line of the
@samp{*compilation*} buffer changes to say @samp{exit} (followed by
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,
switch to the @samp{*compilation*} buffer and move point to the end of
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
92 93 94

@cindex compilation buffer, keeping point at end
@vindex compilation-scroll-output
95
  If you change the variable @code{compilation-scroll-output} to a
96 97 98 99 100
non-@code{nil} value, the @samp{*compilation*} buffer scrolls
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
101 102 103

@findex recompile
  To rerun the last compilation with the same command, type @kbd{M-x
104 105
recompile}.  This reuses the compilation command from the last
invocation of @kbd{M-x compile}.  It also reuses the
Glenn Morris's avatar
Glenn Morris committed
106 107 108 109 110 111 112 113 114 115 116 117
@samp{*compilation*} buffer and starts the compilation in its default
directory, which is the directory in which the previous compilation
was started.

@findex kill-compilation
  Starting a new compilation also kills any compilation already
running in @samp{*compilation*}, as the buffer can only handle one
compilation at any time.  However, @kbd{M-x compile} asks for
confirmation before actually killing a compilation that is running.
You can also kill the compilation process with @kbd{M-x
kill-compilation}.

118 119 120 121
  To run two compilations at once, start the first one, then rename
the @samp{*compilation*} buffer (perhaps using @code{rename-uniquely};
@pxref{Misc Buffer}), then switch buffers and start the other
compilation.  This will create a new @samp{*compilation*} buffer.
Glenn Morris's avatar
Glenn Morris committed
122 123 124 125 126 127 128 129 130 131 132 133 134

@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
135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153
@cindex locus
  The @samp{*compilation*} buffer uses a major mode called Compilation
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
appears in the @samp{*compilation*} buffer.

  Compilation mode provides the following additional commands.  These
commands can also be used in @samp{*grep*} buffers, where the
hyperlinks are search matches rather than error messages (@pxref{Grep
Searching}).
Glenn Morris's avatar
Glenn Morris committed
154 155 156 157 158

@table @kbd
@item M-g M-n
@itemx M-g n
@itemx C-x `
159
Visit the locus of the next error message or match (@code{next-error}).
Glenn Morris's avatar
Glenn Morris committed
160 161
@item M-g M-p
@itemx M-g p
162 163
Visit the locus of the previous error message or match
(@code{previous-error}).
Glenn Morris's avatar
Glenn Morris committed
164
@item M-n
165 166
Move point to the next error message or match, without visiting its
locus (@code{compilation-next-error}).
Glenn Morris's avatar
Glenn Morris committed
167
@item M-p
168 169
Move point to the previous error message or match, without visiting
its locus (@code{compilation-previous-error}).
Glenn Morris's avatar
Glenn Morris committed
170
@item M-@}
171 172
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
173
@item M-@{
174 175
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
176 177 178 179 180 181 182 183 184 185
@item C-c C-f
Toggle Next Error Follow minor mode, which makes cursor motion in the
compilation buffer produce automatic source display.
@end table

@kindex M-g M-n
@kindex M-g n
@kindex C-x `
@findex next-error
@vindex next-error-highlight
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
  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
@samp{*compilation*} buffer, subsequent @w{@kbd{C-x `}} commands
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
act on the errors or matches listed in @samp{*compilation*} and
@samp{*grep*} buffers; they also know how to iterate through error or
match lists produced by other commands, such as @kbd{M-x occur}
(@pxref{Other Repeating Search}).  If you are already in a buffer
containing error messages or matches, those are the ones that are
iterated through; otherwise, Emacs looks for a buffer containing error
messages or matches amongst the windows of the selected frame, then
for one that @code{next-error} or @code{previous-error} previously
iterated through, and finally amongst all other buffers.  If the
buffer chosen for iterating through is not currently displayed in a
window, it will be displayed.
Glenn Morris's avatar
Glenn Morris committed
213 214

@vindex compilation-skip-threshold
215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236
  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
  If the @samp{*compilation*} buffer is shown in a window with a left
fringe (@pxref{Fringes}), the locus-visiting commands put an arrow in
the fringe, pointing to the current error message.  If the window has
no left fringe, such as on a text-only 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
237 238 239 240 241

@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
242 243 244
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
245 246 247 248 249

@findex compilation-next-error
@findex compilation-previous-error
@findex compilation-next-file
@findex compilation-previous-file
250 251 252 253 254 255
  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
256 257 258 259 260

@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
261 262
automatically updates the source buffer, i.e.@: moving the cursor over
an error message causes the locus of that error to be displayed.
Glenn Morris's avatar
Glenn Morris committed
263 264 265

  The features of Compilation mode are also available in a minor mode
called Compilation Minor mode.  This lets you parse error messages in
266 267 268 269 270
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
271 272 273 274

@node Compilation Shell
@section Subshells for Compilation

275 276 277 278 279 280 281 282
  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
@samp{*compilation*} buffer, it means you have made a mistake in your
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
283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298
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

299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319
  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
320 321

@ifnottex
322 323 324 325
  On the MS-DOS ``operating system'', asynchronous subprocesses are
not supported, so @kbd{M-x compile} runs the compilation command
synchronously (i.e.@: you must wait until the command finishes before
you can do anything else in Emacs).  @xref{MS-DOS}.
Glenn Morris's avatar
Glenn Morris committed
326 327 328 329 330 331
@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
332 333 334 335
with compilation errors, you can also run @command{grep} and then
visit the lines on which matches were found.  This works by treating
the matches reported by @command{grep} as if they were ``errors.''
The output buffer uses Grep mode, which is a variant of Compilation
Glenn Morris's avatar
Glenn Morris committed
336 337 338 339
mode (@pxref{Compilation Mode}).

@table @kbd
@item M-x grep
340
@itemx M-x lgrep
341 342
Run @command{grep} asynchronously under Emacs, listing matching lines in
the buffer named @samp{*grep*}.
Glenn Morris's avatar
Glenn Morris committed
343 344 345
@item M-x grep-find
@itemx M-x find-grep
@itemx M-x rgrep
346 347
Run @command{grep} via @code{find}, and collect output in the
@samp{*grep*} buffer.
348
@item M-x zrgrep
349
Run @code{zgrep} and collect output in the @samp{*grep*} buffer.
Glenn Morris's avatar
Glenn Morris committed
350
@item M-x kill-grep
351
Kill the running @command{grep} subprocess.
Glenn Morris's avatar
Glenn Morris committed
352 353 354
@end table

@findex grep
355 356 357
  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
358 359 360 361
regexp (usually in single-quotes to quote the shell's special
characters) followed by file names, which may use wildcards.  If you
specify a prefix argument for @kbd{M-x grep}, it finds the tag
(@pxref{Tags}) in the buffer around point, and puts that into the
362
default @command{grep} command.
Glenn Morris's avatar
Glenn Morris committed
363

364
  Your command need not simply run @command{grep}; you can use any shell
Glenn Morris's avatar
Glenn Morris committed
365
command that produces output in the same format.  For instance, you
366
can chain @command{grep} commands, like this:
Glenn Morris's avatar
Glenn Morris committed
367 368 369 370 371

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

372
  The output from @command{grep} goes in the @samp{*grep*} buffer.  You
Glenn Morris's avatar
Glenn Morris committed
373 374 375 376 377 378 379 380 381 382 383 384 385 386
can find the corresponding lines in the original files using @w{@kbd{C-x
`}}, @key{RET}, and so forth, just like compilation errors.

  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.

@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
387
@command{grep}, so as to search every file in a directory tree.  See also
Glenn Morris's avatar
Glenn Morris committed
388 389 390 391
the @code{find-grep-dired} command, in @ref{Dired and Find}.

@findex lgrep
@findex rgrep
392
@findex zrgrep
Glenn Morris's avatar
Glenn Morris committed
393
  The commands @kbd{M-x lgrep} (local grep) and @kbd{M-x rgrep}
394
(recursive grep) are more user-friendly versions of @command{grep} and
Glenn Morris's avatar
Glenn Morris committed
395 396
@code{grep-find}, which prompt separately for the regular expression
to match, the files to search, and the base directory for the search.
397 398
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
399 400
@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
401

402
  These commands build the shell commands based on the variables
Glenn Morris's avatar
Glenn Morris committed
403
@code{grep-template} (for @code{lgrep}) and @code{grep-find-template}
404 405
(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
406

407 408 409 410 411
@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
412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428

@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++,
Perl, HTML, and @TeX{}/La@TeX{}.  It is somewhat analogous to Flyspell
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.

429 430
  To enable Flymake mode, type @kbd{M-x flymake-mode}.  You can go to
the errors found by Flymake mode with @kbd{M-x
Glenn Morris's avatar
Glenn Morris committed
431 432 433 434
flymake-goto-next-error} and @kbd{M-x flymake-goto-prev-error}.  To
display any error messages associated with the current line, use
@kbd{M-x flymake-display-err-menu-for-current-line}.

435 436 437 438 439 440 441
  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
442 443 444 445 446 447 448 449 450 451 452 453 454

@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
455
The GUD (Grand Unified Debugger) library provides an Emacs interface
456 457 458
to a wide variety of symbolic debuggers.  It can run the GNU Debugger
(GDB), as well as DBX, SDB, XDB, Perl's debugging mode, the Python
debugger PDB, and the Java Debugger JDB.
Glenn Morris's avatar
Glenn Morris committed
459

460 461 462 463 464 465 466
  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}.
467

Glenn Morris's avatar
Glenn Morris committed
468
@menu
469 470 471 472
* 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.
473 474 475
* GDB Graphical Interface::  An enhanced mode that uses GDB features to
                        implement a graphical debugging environment through
                        Emacs.
Glenn Morris's avatar
Glenn Morris committed
476 477 478
@end menu

@node Starting GUD
479
@subsection Starting GUD
Glenn Morris's avatar
Glenn Morris committed
480

481
  There are several commands for starting a debugger subprocess, each
Chong Yidong's avatar
Chong Yidong committed
482
corresponding to a particular debugger program.
Glenn Morris's avatar
Glenn Morris committed
483 484

@table @kbd
485
@item M-x gdb
486
@findex gdb
487 488 489
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.
490

491
@item M-x gud-gdb
492
@findex gud-gdb
493 494 495
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
496

497 498
The other commands in this list do the same, for other debugger
programs.
Glenn Morris's avatar
Glenn Morris committed
499

500
@item M-x perldb
Glenn Morris's avatar
Glenn Morris committed
501
@findex perldb
502
Run the Perl interpreter in debug mode.
Glenn Morris's avatar
Glenn Morris committed
503

504
@item M-x jdb
Glenn Morris's avatar
Glenn Morris committed
505
@findex jdb
506
Run the Java debugger.
Glenn Morris's avatar
Glenn Morris committed
507

508
@item M-x pdb
Glenn Morris's avatar
Glenn Morris committed
509
@findex pdb
510 511 512 513 514 515 516 517 518 519 520 521 522 523
Run the Python debugger.

@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
524 525
@end table

526 527 528 529 530 531 532
  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
533

Chong Yidong's avatar
Chong Yidong committed
534
@cindex remote host, debugging on
535 536 537 538 539 540 541
  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
542 543

@node Debugger Operation
544
@subsection Debugger Operation
545
@cindex GUD interaction buffer
Glenn Morris's avatar
Glenn Morris committed
546

547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587
  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.
@end iftext
@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
@end iftext
@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
indicating the current execution line.  (On a text-only 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
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
588
@vindex gud-tooltip-echo-area
589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604
  GUD Tooltip mode is a global minor mode that adds tooltip support to
GUD.  To toggle this mode, type @kbd{M-x gud-tooltip-mode}.  It is
disabled by default.  If enabled, you can move the mouse cursor over a
variable to show its value in a tooltip (@pxref{Tooltips}); this 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 @code{gud-tooltip-echo-area} is non-@code{nil}, values are
shown in the echo area instead of a tooltip.

  When using GUD Tooltip mode with @kbd{M-x gud-gdb}, you should note
that displaying an expression's value in GDB can sometimes expand a
macro, potentially causing side effects in the debugged program.  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
605 606

@node Commands of GUD
607
@subsection Commands of GUD
Glenn Morris's avatar
Glenn Morris committed
608

609 610
  GUD provides commands for setting and clearing breakpoints,
selecting stack frames, and stepping through the program.
Glenn Morris's avatar
Glenn Morris committed
611 612 613 614 615 616 617

@table @kbd
@item C-x @key{SPC}
@kindex C-x SPC
Set a breakpoint on the source line that point is on.
@end table

618 619 620 621 622 623
  @kbd{C-x @key{SPC}} (@code{gud-break}), when called in a source
buffer, sets a debugger breakpoint on the current source line.  This
command is available only after starting GUD.  If you call it in a
buffer that is not associated with any debugger subprocess, it signals
a error.

Glenn Morris's avatar
Glenn Morris committed
624
@kindex C-x C-a @r{(GUD)}
625 626
  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
627
starting with @kbd{C-c} are available only in the GUD interaction
628 629 630
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
631 632 633 634 635 636

@table @kbd
@item C-c C-l
@kindex C-c C-l @r{(GUD)}
@itemx C-x C-a C-l
@findex gud-refresh
637 638
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
639 640 641 642 643

@item C-c C-s
@kindex C-c C-s @r{(GUD)}
@itemx C-x C-a C-s
@findex gud-step
644 645 646
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
647 648 649 650 651

@item C-c C-n
@kindex C-c C-n @r{(GUD)}
@itemx C-x C-a C-n
@findex gud-next
652 653
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
654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 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

@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}
@kindex TAB @r{(GUD)}
@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
enter a tab as input to the program you are debugging with GDB.
Instead, type @kbd{C-q @key{TAB}} to enter a tab.

@node GUD Customization
755
@subsection GUD Customization
Glenn Morris's avatar
Glenn Morris committed
756 757 758 759 760 761 762 763

@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
764 765 766 767 768 769 770 771 772 773 774
  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;
@code{xdb-mode-hook}, if you are using XDB; @code{perldb-mode-hook},
for Perl debugging mode; @code{pdb-mode-hook}, for PDB;
@code{jdb-mode-hook}, for JDB.  @xref{Hooks}.

  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
775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829

@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
buffer, then the ``current source file'' is the file that the program
stopped in.

@item %l
The number of the current source line.  If the current buffer is the GUD
buffer, then the ``current source line'' is the line that the program
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

830 831 832 833 834
  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
835 836

@vindex gud-gdb-command-name
837 838 839 840 841 842 843 844 845
  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}.

  Internally, @kbd{M-x gdb} informs GDB that its ``screen size'' is
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
846 847

@menu
848
* GDB User Interface Layout::   Control the number of displayed buffers.
Glenn Morris's avatar
Glenn Morris committed
849 850 851
* Source Buffers::              Use the mouse in the fringe/margin to
                                control your program.
* Breakpoints Buffer::          A breakpoint control panel.
852
* Threads Buffer::              Displays your threads.
Glenn Morris's avatar
Glenn Morris committed
853
* Stack Buffer::                Select a frame from the call stack.
854
* Other GDB Buffers::           Other buffers for controlling the GDB state.
Glenn Morris's avatar
Glenn Morris committed
855
* Watch Expressions::           Monitor variable values in the speedbar.
856
* Multithreaded Debugging::     Debugging programs with several threads.
Glenn Morris's avatar
Glenn Morris committed
857 858
@end menu

859
@node GDB User Interface Layout
Glenn Morris's avatar
Glenn Morris committed
860 861 862 863
@subsubsection GDB User Interface Layout
@cindex GDB User Interface layout

@vindex gdb-many-windows
864 865
  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
866
However, if the variable @code{gdb-show-main} is also non-@code{nil},
867 868 869
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
870 871 872 873 874 875 876

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

@smallexample
@group
+--------------------------------+--------------------------------+
877
|   GUD interaction buffer       |   Locals/Registers buffer      |
Glenn Morris's avatar
Glenn Morris committed
878 879 880
|--------------------------------+--------------------------------+
|   Primary Source buffer        |   I/O buffer for debugged pgm  |
|--------------------------------+--------------------------------+
881
|   Stack buffer                 |   Breakpoints/Threads buffer   |
Glenn Morris's avatar
Glenn Morris committed
882 883 884 885 886 887 888 889 890 891
+--------------------------------+--------------------------------+
@end group
@end smallexample

  However, if @code{gdb-use-separate-io-buffer} is @code{nil}, the I/O
buffer does not appear and the primary source buffer occupies the full
width of the frame.

@findex gdb-restore-windows
@findex gdb-many-windows
892 893 894 895
  If you ever change the window layout, you can restore the ``many
windows'' layout by typing @kbd{M-x gdb-restore-windows}.  To toggle
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
896 897 898

  You may also specify additional GDB-related buffers to display,
either in the same frame or a different one.  Select the buffers you
899 900 901 902 903 904 905 906 907 908 909 910 911 912 913
want by typing @code{M-x gdb-display-@var{buffertype}-buffer} or
@code{M-x gdb-frame-@var{buffertype}-buffer}, where @var{buffertype}
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
914 915 916

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

919 920 921
@table @asis
@item @kbd{Mouse-1} (in fringe)
Set or clear a breakpoint on that line.
Glenn Morris's avatar
Glenn Morris committed
922

923 924
@item @kbd{C-Mouse-1} (in fringe)
Enable or disable a breakpoint on that line.
Glenn Morris's avatar
Glenn Morris committed
925

926 927
@item @kbd{Mouse-3} (in fringe)
Continue execution to that line.
Glenn Morris's avatar
Glenn Morris committed
928

929 930
@item @kbd{C-Mouse-3} (in fringe)
Jump to that line.
Glenn Morris's avatar
Glenn Morris committed
931 932
@end table

933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955
  On a graphical display, you can click @kbd{Mouse-1} in the fringe of
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
already exists there, the click removes it.  A @kbd{C-Mouse-1} click
enables or disables an existing breakpoint; a breakpoint that is
disabled, but not unset, is indicated by a gray dot.

  On a text-only terminal, or when fringes are disabled, enabled
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
line of the innermost frame where the debugged program has stopped. A
hollow arrow indicates the current execution line of a higher-level
frame.  If you drag the arrow in the fringe with @kbd{Mouse-1}, that
causes execution to advance to the line where you release the button.
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
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
956 957 958 959

@node Breakpoints Buffer
@subsubsection Breakpoints Buffer

960 961 962 963
  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
964 965 966

@table @kbd
@item @key{SPC}
967
@kindex SPC @r{(GDB Breakpoints buffer)}
Glenn Morris's avatar
Glenn Morris committed
968
@findex gdb-toggle-breakpoint
969 970 971 972
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
973 974

@item D
975
@kindex D @r{(GDB Breakpoints buffer)}
Glenn Morris's avatar
Glenn Morris committed
976 977 978 979
@findex gdb-delete-breakpoint
Delete the current breakpoint (@code{gdb-delete-breakpoint}).

@item @key{RET}
980
@kindex RET @r{(GDB Breakpoints buffer)}
Glenn Morris's avatar
Glenn Morris committed
981 982 983 984 985
@findex gdb-goto-breakpoint
Visit the source line for the current breakpoint
(@code{gdb-goto-breakpoint}).

@item Mouse-2
986
@kindex Mouse-2 @r{(GDB Breakpoints buffer)}
Glenn Morris's avatar
Glenn Morris committed
987 988 989
Visit the source line for the breakpoint you click on.
@end table

990
@vindex gdb-show-threads-by-default
991 992 993 994 995
  When @code{gdb-many-windows} is non-@code{nil}, the GDB Breakpoints
buffer shares its window with the GDB Threads buffer.  To switch from
one to the other click with @kbd{Mouse-1} on the relevant button in
the header line.  If @code{gdb-show-threads-by-default} is
non-@code{nil}, the GDB Threads buffer is the one shown by default.
996 997 998 999 1000

@node Threads Buffer
@subsubsection Threads Buffer

@findex gdb-select-thread
1001 1002 1003 1004 1005 1006
  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
point there and type @key{RET} (@code{gdb-select-thread}), or click on
it with @kbd{Mouse-2}.  This also displays the associated source
buffer, and updates the contents of the other GDB buffers.
1007 1008

  You can customize variables under @code{gdb-buffers} group to select
1009
fields included in GDB Threads buffer.
1010 1011 1012 1013

@table @code
@item gdb-thread-buffer-verbose-names
@vindex gdb-thread-buffer-verbose-names
1014
Show long thread names like @samp{Thread 0x4e2ab70 (LWP 1983)}.
1015 1016 1017

@item gdb-thread-buffer-arguments
@vindex gdb-thread-buffer-arguments
1018
Show arguments of thread top frames.
1019 1020 1021

@item gdb-thread-buffer-locations
@vindex gdb-thread-buffer-locations
1022
Show file information or library names.
1023 1024 1025 1026 1027 1028

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

1029 1030
  To view information for several threads simultaneously, use the
following commands from the GDB Threads buffer.
1031 1032 1033 1034 1035

@table @kbd
@item d
@kindex d @r{(GDB threads buffer)}
@findex gdb-display-disassembly-for-thread
1036 1037
Display disassembly buffer for the thread at current line
(@code{gdb-display-disassembly-for-thread}).
1038 1039 1040 1041

@item f
@kindex f @r{(GDB threads buffer)}
@findex gdb-display-stack-for-thread
1042
Display the GDB Stack buffer for the thread at current line
1043 1044 1045 1046 1047
(@code{gdb-display-stack-for-thread}).

@item l
@kindex l @r{(GDB threads buffer)}
@findex gdb-display-locals-for-thread
1048
Display the GDB Locals buffer for the thread at current line
1049 1050 1051 1052 1053
(@code{gdb-display-locals-for-thread}).

@item r
@kindex r @r{(GDB threads buffer)}
@findex gdb-display-registers-for-thread
1054
Display the GDB Registers buffer for the thread at current line
1055 1056 1057
(@code{gdb-display-registers-for-thread}).
@end table

1058 1059 1060
@noindent
Their upper-case counterparts, @kbd{D}, @kbd{F} ,@kbd{L} and @kbd{R},
display the corresponding buffer in a new frame.
1061 1062 1063

  When you create a buffer showing information about some specific
thread, it becomes bound to that thread and keeps showing actual
1064 1065 1066 1067
information while you debug your program.  The mode indicator for each
GDB buffer shows the number of thread it is showing information about.
The thread number is also included in the buffer name of bound
buffers.
1068

1069 1070 1071
  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}.
1072

Glenn Morris's avatar
Glenn Morris committed
1073 1074 1075
@node Stack Buffer
@subsubsection Stack Buffer

1076 1077 1078 1079
  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
1080 1081

@findex gdb-frames-select
1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093
  On graphical displays, the selected stack frame is indicated by an
arrow in the fringe.  On text-only 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}
(@code{gdb-frames-select}), or click @kbd{Mouse-2} on it.  Doing so
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
1094

1095
@node Other GDB Buffers
1096
@subsubsection Other GDB Buffers
Glenn Morris's avatar
Glenn Morris committed
1097 1098 1099

@table @asis
@item Locals Buffer
1100 1101
This buffer displays the values of local variables of the current
frame for simple data types (@pxref{Frame Info, Frame Info,
1102
Information on a frame, gdb, The GNU debugger}).  Press @key{RET} or
Glenn Morris's avatar
Glenn Morris committed
1103 1104 1105
click @kbd{Mouse-2} on the value if you want to edit it.

Arrays and structures display their type only.  With GDB 6.4 or later,
1106 1107 1108
you can examine the value of the local variable at point by typing
@key{RET}, or with a @kbd{Mouse-2} click.  With earlier versions of
GDB, use @key{RET} or @kbd{Mouse-2} on the type description
Glenn Morris's avatar
Glenn Morris committed
1109 1110 1111 1112
(@samp{[struct/union]} or @samp{[array]}).  @xref{Watch Expressions}.

@item Registers Buffer
@findex toggle-gdb-all-registers
1113
This buffer displays the values held by the registers
Glenn Morris's avatar
Glenn Morris committed
1114
(@pxref{Registers,,, gdb, The GNU debugger}).  Press @key{RET} or
1115 1116 1117
click @kbd{Mouse-2} on a register if you want to edit its value.  With
GDB 6.4 or later, recently changed register values display with
@code{font-lock-warning-face}.
Glenn Morris's avatar
Glenn Morris committed
1118

1119 1120
@item Assembler Buffer
The assembler buffer displays the current frame as machine code.  An
Glenn Morris's avatar
Glenn Morris committed
1121 1122 1123 1124 1125 1126 1127 1128 1129
arrow points to the current instruction, and you can set and remove
breakpoints as in a source buffer.  Breakpoint icons also appear in
the fringe or margin.

@item Memory Buffer
The memory buffer lets you examine sections of program memory
(@pxref{Memory, Memory, Examining memory, gdb, The GNU debugger}).
Click @kbd{Mouse-1} on the appropriate part of the header line to
change the starting address or number of data items that the buffer
1130 1131 1132
displays.  Alternatively, use @kbd{S} or @kbd{N} respectively.  Click
@kbd{Mouse-3} on the header line to select the display format or unit
size for these data items.
Glenn Morris's avatar
Glenn Morris committed
1133 1134
@end table

1135
When @code{gdb-many-windows} is non-@code{nil}, the locals buffer
1136 1137
shares its window with the registers buffer, just like breakpoints and
threads buffers. To switch from one to the other, click with
1138
@kbd{Mouse-1} on the relevant button in the header line.
1139

Glenn Morris's avatar
Glenn Morris committed
1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151
@node Watch Expressions
@subsubsection Watch Expressions
@cindex Watching expressions in GDB

@findex gud-watch
@kindex C-x C-a C-w @r{(GUD)}
  If you want to see how a variable changes each time your program
stops, move point into the variable name and click on the watch icon
in the tool bar (@code{gud-watch}) or type @kbd{C-x C-a C-w}.  If you
specify a prefix argument, you can enter the variable name in the
minibuffer.

1152 1153 1154 1155 1156 1157 1158 1159 1160
  Each watch expression is displayed in the speedbar
(@pxref{Speedbar}).  Complex data types, such as arrays, structures
and unions are represented in a tree format.  Leaves and simple data
types show the name of the expression and its value and, when the
speedbar frame is selected, display the type as a tooltip.  Higher
levels show the name, type and address value for pointers and just the
name and type otherwise.  Root expressions also display the frame
address as a tooltip to help identify the frame in which they were
defined.
Glenn Morris's avatar
Glenn Morris committed
1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187

  To expand or contract a complex data type, click @kbd{Mouse-2} or
press @key{SPC} on the tag to the left of the expression.  Emacs asks
for confirmation before expanding the expression if its number of
immediate children exceeds the value of the variable
@code{gdb-max-children}.

@kindex D @r{(GDB speedbar)}
@findex gdb-var-delete
  To delete a complex watch expression, move point to the root
expression in the speedbar and type @kbd{D} (@code{gdb-var-delete}).

@kindex RET @r{(GDB speedbar)}
@findex gdb-edit-value
  To edit a variable with a simple data type, or a simple element of a
complex data type, move point there in the speedbar and type @key{RET}
(@code{gdb-edit-value}).  Or you can click @kbd{Mouse-2} on a value to
edit it.  Either way, this reads the new value using the minibuffer.

@vindex gdb-show-changed-values
  If you set the variable @code{gdb-show-changed-values} to
non-@code{nil} (the default value), Emacs uses
@code{font-lock-warning-face} to highlight values that have recently
changed and @code{shadow} face to make variables which have gone out of
scope less noticeable.  When a variable goes out of scope you can't
edit its value.

1188
@vindex gdb-delete-out-of-scope
1189 1190 1191
  If the variable @code{gdb-delete-out-of-scope} is non-@code{nil}
(the default value), Emacs automatically deletes watch expressions
which go out of scope.  Sometimes, when re-entering the same function,
Chong Yidong's avatar
Chong Yidong committed
1192 1193
it may be useful to set this value to @code{nil} so that you don't
need to recreate the watch expression.
1194

Glenn Morris's avatar
Glenn Morris committed
1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206
@vindex gdb-use-colon-colon-notation
  If the variable @code{gdb-use-colon-colon-notation} is
non-@code{nil}, Emacs uses the @samp{@var{function}::@var{variable}}
format.  This allows the user to display watch expressions which share
the same variable name.  The default value is @code{nil}.

@vindex gdb-speedbar-auto-raise
To automatically raise the speedbar every time the display of watch
expressions updates, set @code{gdb-speedbar-auto-raise} to
non-@code{nil}.  This can be useful if you are debugging with a full
screen Emacs frame.

1207
@node Multithreaded Debugging
1208
@subsubsection Multithreaded Debugging
1209 1210 1211
@cindex Multithreaded debugging in GDB
@cindex Non-stop debugging in GDB

1212 1213 1214 1215 1216 1217 1218 1219 1220
  In GDB's @dfn{all-stop mode}, whenever your program stops, all
execution threads stop.  Likewise, whenever you restart the program,
all threads start executing.  @xref{All-Stop Mode, , All-Stop Mode,
gdb, The GNU debugger}.  For some multi-threaded targets, GDB supports
a further mode of operation, called @dfn{non-stop mode}, in which you
can examine stopped program threads in the debugger while other
threads continue to execute freely.  @xref{Non-Stop Mode, , Non-Stop
Mode, gdb, The GNU debugger}.  Versions of GDB prior to 7.0 do not
support non-stop mode, and it does not work on all targets.
1221 1222

@vindex gdb-non-stop-setting
1223 1224 1225 1226 1227 1228 1229
  The variable @code{gdb-non-stop-setting} determines whether Emacs
runs GDB in all-stop mode or non-stop mode.  The default is @code{t},
which means it tries to use non-stop mode if that is available.  If
you change the value to @code{nil}, or if non-stop mode is
unavailable, Emacs runs GDB in all-stop mode.  The variable takes
effect when Emacs begins a debugging session; if you change its value,
you should restart any active debugging session.
1230 1231

@vindex gdb-switch-when-another-stopped
1232 1233 1234 1235
  When a thread stops in non-stop mode, Emacs usually switches to that
thread.  If you don't want Emacs to do this switch if another stopped
thread is already selected, change the variable
@code{gdb-switch-when-another-stopped} to @code{nil}.
1236 1237

@vindex gdb-switch-reasons
1238 1239 1240 1241
  Emacs can decide whether or not to switch to the stopped thread
depending on the reason which caused the stop.  Customize the variable
@code{gdb-switch-reasons} to select the stop reasons which will cause
a thread switch.
1242 1243

@vindex gdb-stopped-hooks
1244
  The variable @code{gdb-stopped-hooks} allows you to execute your
1245 1246 1247 1248 1249 1250 1251 1252 1253
functions whenever some thread stops.

  In non-stop mode, you can switch between different modes for GUD
execution control commands.

@vindex gdb-gud-control-all-threads
@table @dfn
@item Non-stop/A

1254
  When @code{gdb-gud-control-all-threads} is @code{t} (the default
1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279
value), interruption and continuation commands apply to all threads,
so you can halt or continue all your threads with one command using
@code{gud-stop-subjob} and @code{gud-cont}, respectively.  The
@samp{Go} button is shown on the toolbar when at least one thread is
stopped, whereas @samp{Stop} button is shown when at least one thread
is running.

@item Non-stop/T

When @code{gdb-gud-control-all-threads} is @code{nil}, only the
current thread is stopped/continued.  @samp{Go} and @samp{Stop}
buttons on the GUD toolbar are shown depending on the state of current
thread.
@end table

You can change the current value of @code{gdb-gud-control-all-threads}
from the tool bar or from @samp{GUD->GDB-MI} menu.

  Stepping commands always apply to the current thread.

  In non-stop mode, you can interrupt/continue your threads without
selecting them.  Hitting @kbd{i} in threads buffer interrupts thread
under point, @kbd{c} continues it, @kbd{s} steps through.  More such
commands may be added in the future.

1280 1281
  Note that when you interrupt a thread, it stops with the
@samp{signal received} reason.  If that reason is included in your
1282 1283
@code{gdb-switch-reasons} (it is by default), Emacs will switch to
that thread.
1284

Glenn Morris's avatar
Glenn Morris committed
1285 1286 1287
@node Executing Lisp
@section Executing Lisp Expressions

1288 1289 1290 1291
  Emacs has major modes for several variants of Lisp.  They use the
same editing commands as other programming language modes
(@pxref{Programs}).  In addition, they provide special commands for
executing Lisp expressions.
Glenn Morris's avatar
Glenn Morris committed
1292 1293

@table @asis
1294 1295 1296 1297
@item Emacs Lisp mode
The mode for editing Emacs Lisp source files.  It defines @kbd{C-M-x}
to evaluate the current top-level Lisp expression.  @xref{Lisp Eval}.

Glenn Morris's avatar
Glenn Morris committed
1298
@item Lisp Interaction mode
1299 1300
The mode for an interactive Emacs Lisp session.  It defines @kbd{C-j}
to evaluate the expression before point and insert its value in the
Glenn Morris's avatar
Glenn Morris committed
1301
buffer.  @xref{Lisp Interaction}.
1302

Glenn Morris's avatar
Glenn Morris committed
1303 1304
@item Lisp mode
The mode for editing source files of programs that run in Lisps other
1305 1306 1307
than Emacs Lisp.  It defines @kbd{C-M-x} to evaluate the current
top-level expression in an external Lisp.  @xref{External Lisp}.

Glenn Morris's avatar
Glenn Morris committed
1308
@item Inferior Lisp mode
1309 1310 1311 1312 1313 1314
The mode for an interactive session with an external Lisp which is
being run as a subprocess (or @dfn{inferior process}) of Emacs.
@ifnottex
@xref{External Lisp}.
@end ifnottex

Glenn Morris's avatar
Glenn Morris committed
1315
@item Scheme mode
1316 1317
Like Lisp mode, but for Scheme programs.

Glenn Morris's avatar
Glenn Morris committed
1318
@item Inferior Scheme mode
1319
Like Inferior Lisp mode, but for Scheme.
Glenn Morris's avatar
Glenn Morris committed
1320 1321 1322 1323 1324 1325 1326
@end table

@node Lisp Libraries
@section Libraries of Lisp Code for Emacs
@cindex libraries
@cindex loading Lisp code

1327 1328
  Emacs Lisp code is stored in files whose names conventionally end in
@file{.el}.  Such files are automatically visited in Emacs Lisp mode.
Glenn Morris's avatar
Glenn Morris committed
1329 1330 1331

@cindex byte code
  Emacs Lisp code can be compiled into byte-code, which loads faster,
1332 1333 1334 1335 1336
takes up less space, and executes faster.  By convention, compiled
Emacs Lisp code goes in a separate file whose name ends in
@samp{.elc}.  For example, the compiled code for @file{foo.el} goes in
@file{foo.elc}.  @xref{Byte Compilation,, Byte Compilation, elisp, the
Emacs Lisp Reference Manual}.
Glenn Morris's avatar
Glenn Morris committed
1337 1338

@findex load-file
1339 1340 1341 1342 1343
  To @dfn{load} an Emacs Lisp file, type @kbd{M-x load-file}.  This
command reads a file name using the minibuffer, and executes the
contents of that file as Emacs Lisp code.  It is not necessary to
visit the file first; this command reads the file directly from disk,
not from an existing Emacs buffer.
Glenn Morris's avatar
Glenn Morris committed
1344 1345 1346

@findex load
@findex load-library
1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368
@cindex load path for Emacs Lisp
  If an Emacs Lisp file is installed in the Emacs Lisp @dfn{load path}
(defined below), you can load it by typing @kbd{M-x load-library},
instead of using @kbd{M-x load-file}.  The @kbd{M-x load-library}
command prompts for a @dfn{library name} rather than a file name; it
searches through each directory in the Emacs Lisp load path, trying to
find a file matching that library name.  If the library name is
@samp{@var{foo}}, it tries looking for files named
@file{@var{foo}.elc}, @file{@var{foo}.el}, and lastly just
@file{@var{foo}}; the first one found is loaded.  This command prefers
@file{.elc} files over @file{.el} files because compiled files load
and run faster.  If it finds that @file{@var{lib}.el} is newer than
@file{@var{lib}.elc}, it issues a warning, in case someone made
changes to the @file{.el} file and forgot to recompile it, but loads
the @file{.elc} file anyway.  (Due to this behavior, you can save
unfinished edits to Emacs Lisp source files, and not recompile until
your changes are ready for use.)

  Emacs Lisp programs usually load Emacs Lisp files using the
@code{load} function.  This is similar to @code{load-library}, but is
lower-level and accepts additional arguments.  @xref{How Programs Do
Loading,,, elisp, the Emacs Lisp Reference Manual}.
Glenn Morris's avatar
Glenn Morris committed
1369 1370

@vindex load-path
1371 1372 1373 1374 1375 1376 1377 1378
  The Emacs Lisp load path is specified by the variable
@code{load-path}.  Its value should be a list of directory names
(strings).  These directories are searched, in the specified order, by
the @kbd{M-x load-library} command, the lower-level @code{load}
function, and other Emacs functions that find Emacs Lisp libraries.  A
list entry in @code{load-path} can also have the special value
@code{nil}, which stands for the current default directory, but it is
almost always a bad idea to use this.  (If you find yourself wishing
Chong Yidong's avatar
Chong Yidong committed
1379
that @code{nil} were in the list, most likely what you really want is
1380
to use @kbd{M-x load-file}.)
1381 1382

  The default value of @code{load-path} is a list of directories where
Glenn Morris's avatar
Glenn Morris committed
1383
the Lisp code for Emacs itself is stored.  If you have libraries of
1384 1385 1386 1387 1388
your own in another directory, you can add that directory to the load
path.  Unlike most other variables described in this manual,
@code{load-path} cannot be changed via the Customize interface
(@pxref{Easy Customization}), but you can add a directory to it by
putting a line like this in your init file (@pxref{Init File}):
1389 1390

@example
1391
(add-to-list 'load-path "/path/to/my/lisp/library")
1392
@end example
Glenn Morris's avatar
Glenn Morris committed
1393 1394

@cindex autoload
1395 1396 1397 1398 1399 1400
  Some commands are @dfn{autoloaded}: when you run them, Emacs
automatically loads the associated library first.  For instance, the
@kbd{M-x compile} command (@pxref{Compilation}) is autoloaded; if you
call it, Emacs automatically loads the @code{compile} library first.
In contrast, the command @kbd{M-x recompile} is not autoloaded, so it
is unavailable until you load the @code{compile} library.
Glenn Morris's avatar
Glenn Morris committed
1401 1402 1403 1404 1405 1406 1407 1408 1409 1410

@vindex load-dangerous-libraries
@cindex Lisp files byte-compiled by XEmacs
  By default, Emacs refuses to load compiled Lisp files which were
compiled with XEmacs, a modified versions of Emacs---they can cause
Emacs to crash.  Set the variable @code{load-dangerous-libraries} to
@code{t} if you want to try loading them.

@node Lisp Eval
@section Evaluating Emacs Lisp Expressions
1411 1412
@cindex Emacs Lisp mode
@cindex mode, Emacs Lisp
Glenn Morris's avatar
Glenn Morris committed
1413 1414

@findex emacs-lisp-mode
1415 1416
  Emacs Lisp mode is the major mode for editing Emacs Lisp.  Its mode
command is @kbd{M-x emacs-lisp-mode}.
Glenn Morris's avatar
Glenn Morris committed
1417

1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433
  Emacs provides several commands for evaluating Emacs Lisp
expressions.  You can use these commands in Emacs Lisp mode, to test
your Emacs Lisp code as it is being written.  For example, after
re-writing a function, you can evaluate the function definition to
make it take effect for subsequent function calls.  These commands are
also available globally, and can be used outside Emacs Lisp mode.

@table @asis
@item @kbd{M-:}
Read a single Emacs Lisp expression in the minibuffer, evaluate it,
and print the value in the echo area (@code{eval-expression}).
@item @kbd{C-x C-e}
Evaluate the Emacs Lisp expression before point, and print the value
in the echo area (@code{eval-last-sexp}).
@item @kbd{C-M-x} @r{(in Emacs Lisp mode)}
@itemx @kbd{M-x eval-defun}