@c This is part of the Emacs manual.
@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Building, Maintaining, Programs, Top
@chapter Compiling and Testing Programs
@vindex compile-command
The default for the compilation command is normally @samp{make -k},
which is correct most of the time for nontrivial programs.
-(@xref{Top,, Make, make, GNU Make Manual}.) If you have done @kbd{M-x
+@xref{Top,, Make, make, GNU Make Manual}. If you have done @kbd{M-x
compile} before, the default each time is the command you used the
previous time. @code{compile} stores this command in the variable
@code{compile-command}, so setting that variable specifies the default
@cindex compilation buffer, keeping point at end
@vindex compilation-scroll-output
- If you set the variable @code{compilation-scroll-output} to a
-non-@code{nil} value, then the compilation buffer always scrolls to
-follow output as it comes in.
+ If you change the variable @code{compilation-scroll-output} to a
+non-@code{nil} value, the compilation buffer will scroll automatically
+to follow the output as it comes in. If the value is
+@code{first-error}, the scrolling stops at the first error that
+appears, leaving point at that error. For any other non-@code{nil}
+value, the buffer continues scrolling until there is no more output.
@findex recompile
To rerun the last compilation with the same command, type @kbd{M-x
@end table
@findex compile-goto-error
+@vindex compilation-auto-jump-to-first-error
You can visit the source for any particular error message by moving
point in the @samp{*compilation*} buffer to that error message and
typing @key{RET} (@code{compile-goto-error}). Alternatively, you can
click @kbd{Mouse-2} on the error message; you need not switch to the
-@samp{*compilation*} buffer first.
+@samp{*compilation*} buffer first. If you set the variable
+@code{compilation-auto-jump-to-first-error} to a non-@code{nil} value,
+Emacs automatically jumps to the first error, if any, as soon as it
+appears in the @samp{*compilation*} buffer.
@kindex M-g M-n
@kindex M-g n
@cindex PDB
@c Do you believe in GUD?
-The GUD (Grand Unified Debugger) library provides an interface to
-various symbolic debuggers from within Emacs. We recommend the
-debugger GDB, which is free software, but GUD can also run DBX, SDB or
-XDB. GUD can also serve as an interface to Perl's debugging mode, the
-Python debugger PDB, and to JDB, the Java Debugger.
-@xref{Debugging,, The Lisp Debugger, elisp, the Emacs Lisp Reference
-Manual}, for information on debugging Emacs Lisp programs.
+The GUD (Grand Unified Debugger) library provides an Emacs interface
+to a wide variety of symbolic debuggers. Unlike the GDB graphical
+interface, which only runs GDB (@pxref{GDB Graphical Interface}), GUD
+can also run DBX, SDB, XDB, Perl's debugging mode, the Python debugger
+PDB, or the Java Debugger JDB.
+
+ In addition, Emacs contains a built-in system for debugging Emacs
+Lisp programs. @xref{Debugging,, The Lisp Debugger, elisp, the Emacs
+Lisp Reference Manual}, for information on the Emacs Lisp debugger.
@menu
* Starting GUD:: How to start a debugger subprocess.
@node Starting GUD
@subsection Starting GUD
- There are several commands for starting a debugger, each corresponding
-to a particular debugger program.
+ There are several commands for starting a debugger under GUD, each
+corresponding to a particular debugger program.
@table @kbd
@item M-x gdb @key{RET} @var{file} @key{RET}
@findex gdb
-Run GDB as a subprocess of Emacs. By default, this uses an IDE-like
-graphical interface; see @ref{GDB Graphical Interface}. Only GDB
-works with the graphical interface.
+Run GDB as a subprocess of Emacs. This uses an IDE-like graphical
+interface; see @ref{GDB Graphical Interface}. Only GDB works with the
+graphical interface.
+
+@item M-x gud-gdb @key{RET} @var{file} @key{RET}
+@findex gud-gdb
+Run GDB as a subprocess of Emacs. This command creates a buffer for
+input and output to GDB, and switches to it. If a GDB buffer already
+exists, it just switches to that buffer.
@item M-x dbx @key{RET} @var{file} @key{RET}
@findex dbx
@item M-x xdb @key{RET} @var{file} @key{RET}
@findex xdb
@vindex gud-xdb-directories
-Similar, but run XDB. Use the variable
+Run XDB as a subprocess of Emacs. Use the variable
@code{gud-xdb-directories} to specify directories to search for source
files.
@item M-x sdb @key{RET} @var{file} @key{RET}
@findex sdb
-Similar, but run SDB.
+Run SDB as a subprocess of Emacs.
- Some versions of SDB do not mention source file names in their
+Some versions of SDB do not mention source file names in their
messages. When you use them, you need to have a valid tags table
(@pxref{Tags}) in order for GUD to find functions in the source code.
-If you have not visited a tags table or the tags table doesn't list one
-of the functions, you get a message saying @samp{The sdb support
-requires a valid tags table to work}. If this happens, generate a valid
-tags table in the working directory and try again.
+If you have not visited a tags table or the tags table doesn't list
+one of the functions, you get a message saying @samp{The sdb support
+requires a valid tags table to work}. If this happens, generate a
+valid tags table in the working directory and try again.
@item M-x perldb @key{RET} @var{file} @key{RET}
@findex perldb
allowed. GUD assumes that the first argument not starting with a
@samp{-} is the executable file name.
-Tramp provides a facility to debug programs on remote hosts.
-@xref{Running a debugger on a remote host, Running a debugger on a remote host,, tramp, The Tramp Manual}.
-@c Running a debugger on a remote host
+@cindex remote host, debugging on
+Tramp provides a facility to debug programs on remote hosts
+(@pxref{Running a debugger on a remote host, Running a debugger on a
+remote host,, tramp, The Tramp Manual}), whereby both the debugger and
+the program being debugged are on the same remote host. This should
+not be confused with debugging programs remotely, where the program
+and the debugger run on different machines, as can be done using the
+GDB remote debugging feature, for example (@pxref{Remote Debugging,,
+Debugging Remote Programs, gdb, The GNU debugger}).
@node Debugger Operation
@subsection Debugger Operation
@node GDB Graphical Interface
@subsection GDB Graphical Interface
- By default, the command @code{gdb} starts GDB using a graphical
-interface, using Emacs windows for display program state information.
-In effect, this makes Emacs into an IDE (interactive development
-environment). With it, you do not need to use textual GDB commands;
-you can control the debugging session with the mouse. For example,
-you can click in the fringe of a source buffer to set a breakpoint
-there, or on a stack frame in the stack buffer to select that frame.
+ The command @code{gdb} starts GDB in a graphical interface, using
+Emacs windows for display program state information. In effect, this
+makes Emacs into an IDE (interactive development environment). With
+it, you do not need to use textual GDB commands; you can control the
+debugging session with the mouse. For example, you can click in the
+fringe of a source buffer to set a breakpoint there, or on a stack
+frame in the stack buffer to select that frame.
This mode requires telling GDB that its ``screen size'' is
unlimited, so it sets the height and width accordingly. For correct
operation you must not change these values during the GDB session.
@vindex gud-gdb-command-name
- You can also run GDB in text command mode, like the other debuggers
-in Emacs. To do this, replace the GDB @code{"--annotate=3"} option
-with @code{"--fullname"} either in the minibuffer for the current
-Emacs session, or the custom variable @code{gud-gdb-command-name} for
-all future sessions. You need to use text command mode to debug
-multiple programs within one Emacs session. You can also use
-@kbd{M-x gud-gdb} to invoke GDB in text command mode if you have
-problems before execution has started.
+ To run GDB in text command mode, like the other debuggers in Emacs,
+use @kbd{M-x gud-gdb}. You need to use text command mode to debug
+multiple programs within one Emacs session.
@menu
* GDB-UI Layout:: Control the number of displayed buffers.
@smallexample
@group
+--------------------------------+--------------------------------+
-| GUD buffer (I/O of GDB) | Locals buffer |
+| GUD buffer (I/O of GDB) | Locals/Registers buffer |
|--------------------------------+--------------------------------+
| Primary Source buffer | I/O buffer for debugged pgm |
|--------------------------------+--------------------------------+
-| Stack buffer | Breakpoints buffer |
+| Stack buffer | Breakpoints/thread buffer |
+--------------------------------+--------------------------------+
@end group
@end smallexample
Visit the source line for the breakpoint you click on.
@end table
+When @code{gdb-many-windows} is non-@code{nil}, the breakpoints buffer
+shares its window with the threads buffer. To switch from one to the
+other click with @kbd{mouse-1} on the relevant button in the header
+line.
+
@node Stack Buffer
@subsubsection Stack Buffer
locals buffer is visible, its contents update to display the variables
that are local in the new thread.
+When there is more than one main thread and the threads buffer is
+present, Emacs displays the selected thread number in the mode line of
+many of the GDB-UI Buffers.
+
@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
-displays. Click @kbd{Mouse-3} on the header line to select the
-display format or unit size for these data items.
+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.
@end table
+When @code{gdb-many-windows} is non-@code{nil}, the threads buffer
+shares its window with the breakpoints buffer, and the locals buffer
+with the registers buffer. To switch from one to the other click with
+@kbd{mouse-1} on the relevant button in the header line.
+
@node Watch Expressions
@subsubsection Watch Expressions
@cindex Watching expressions in GDB
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,
-it may be useful to set this value to nil so that you don't need to
-recreate the watch expression.
+it may be useful to set this value to @code{nil} so that you don't
+need to recreate the watch expression.
@vindex gdb-use-colon-colon-notation
If the variable @code{gdb-use-colon-colon-notation} is
@node Lisp Interaction
@section Lisp Interaction Buffers
- The buffer @samp{*scratch*} which is selected when Emacs starts up is
-provided for evaluating Lisp expressions interactively inside Emacs.
-
- The simplest way to use the @samp{*scratch*} buffer is to insert Lisp
-expressions and type @kbd{C-j} after each expression. This command
-reads the Lisp expression before point, evaluates it, and inserts the
-value in printed representation before point. The result is a complete
-typescript of the expressions you have evaluated and their values.
+ When Emacs starts up, it contains a buffer named @samp{*scratch*},
+which is provided for evaluating Lisp expressions interactively inside
+Emacs. Its major mode is Lisp Interaction mode.
- The @samp{*scratch*} buffer's major mode is Lisp Interaction mode, which
-is the same as Emacs-Lisp mode except for the binding of @kbd{C-j}.
+@findex eval-print-last-sexp
+@kindex C-j @r{(Lisp Interaction mode)}
+ The simplest way to use the @samp{*scratch*} buffer is to insert
+Lisp expressions and type @kbd{C-j} (@code{eval-print-last-sexp})
+after each expression. This command reads the Lisp expression before
+point, evaluates it, and inserts the value in printed representation
+before point. The result is a complete typescript of the expressions
+you have evaluated and their values.
@findex lisp-interaction-mode
- The rationale for this feature is that Emacs must have a buffer when
-it starts up, but that buffer is not useful for editing files since a
-new buffer is made for every file that you visit. The Lisp interpreter
-typescript is the most useful thing I can think of for the initial
-buffer to do. Type @kbd{M-x lisp-interaction-mode} to put the current
-buffer in Lisp Interaction mode.
+ All other commands in Lisp Interaction mode are the same as in Emacs
+Lisp mode. You can enable Lisp Interaction mode by typing @kbd{M-x
+lisp-interaction-mode}.
@findex ielm
An alternative way of evaluating Emacs Lisp expressions interactively