with different facilities for running
the Lisp programs.
* Libraries: Lisp Libraries. Creating Lisp programs to run in Emacs.
-* Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer.
* Eval: Lisp Eval. Executing a single Lisp expression in Emacs.
+* Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer.
* External Lisp:: Communicating through Emacs with a separate Lisp.
@end menu
Run @code{grep} asynchronously under Emacs, with matching lines
listed in the buffer named @samp{*grep*}.
@item M-x grep-find
+@item M-x find-grep
Run @code{grep} via @code{find}, with user-specified arguments, and
collect output in the buffer named @samp{*grep*}.
@item M-x kill-compilation
wait $pid # @r{Wait for subprocess}
@end example
+ 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
+
+@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 Grep Searching
@section Searching with Grep under Emacs
@code{grep} command.
@findex grep-find
- The command @kbd{M-x grep-find} is similar to @kbd{M-x grep}, but it
-supplies a different initial default for the command---one that runs
-both @code{find} and @code{grep}, so as to search every file in a
-directory tree. See also the @code{find-grep-dired} command,
-in @ref{Dired and 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
+@code{grep}, so as to search every file in a directory tree. See also
+the @code{find-grep-dired} command, in @ref{Dired and Find}.
@node Compilation Mode
@section Compilation Mode
buffer and finds no more error messages to visit, it fails and signals
an Emacs error.
+ You don't have to be in the compilation buffer in order to use
+@code{next-error}. If one window on the selected frame can be the
+target of the @code{next-error} call, it is used. Else, if a buffer
+previously had @code{next-error} called on it, it is used. Else,
+if the current buffer can be the target of @code{next-error}, it is
+used. Else, all the buffers Emacs manages are tried for
+@code{next-error} support.
+
@kbd{C-u C-x `} starts scanning from the beginning of the compilation
buffer. This is one way to process the same set of errors again.
@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 you can also run DBX, SDB or XDB if you
-have them. GUD can also serve as an interface to the 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.
+various symbolic debuggers from within Emacs. We recommend the
+debugger GDB, which is free software, but you can also run DBX, SDB or
+XDB if you have them. GUD can also serve as an interface to Perl's
+debugging mode, the Python debugger PDB, the bash debugger, and to
+JDB, the Java Debugger. @xref{Debugging,, The Lisp Debugger, elisp,
+the Emacs Lisp Reference Manual}, for information on debugging Emacs
+Lisp programs.
@menu
* Starting GUD:: How to start a debugger subprocess.
@table @kbd
@item M-x gdb @key{RET} @var{file} @key{RET}
@findex 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.
+Run GDB as a subprocess of Emacs. By default, GDB starts as for
+@kbd{M-x gdba} below. If you want GDB to start as in Emacs 21.3 and
+earlier then edit the string in the minibuffer or set
+@code{gud-gdb-command-name} to ``gdb --fullname''. You need to do
+this if you want to run multiple debugging sessions within one Emacs
+session. In this case, the 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 gdba @key{RET} @var{file} @key{RET}
Run GDB as a subprocess of Emacs, providing a graphical interface
also provides commands for setting and clearing breakpoints, for
selecting stack frames, and for stepping through the program. These
commands are available both in the GUD buffer and globally, but with
-different key bindings.
+different key bindings. It also has its own toolbar from which you
+can invoke the more common commands by clicking on the appropriate
+icon. This is particularly useful for repetitive commands like
+gud-next and gud-step and allows the user to hide the GUD buffer.
The breakpoint commands are normally used in source file buffers,
because that is the easiest way to specify where to set or clear the
details.
@end table
+With the GDB Graphical Interface, you can click @kbd{Mouse-1} on a
+line of the source buffer, in the fringe or display margin, to set a
+breakpoint there. If a breakpoint already exists on that line, this
+action will remove it (@code{gdb-mouse-set-clear-breakpoint}). Where
+Emacs uses the margin to display breakpoints, it is also possible to
+enable or disable them when you click @kbd{Mouse-3} there
+(@code{gdb-mouse-toggle--breakpoint}).
+
These commands interpret a numeric argument as a repeat count, when
that makes sense.
@node GDB Graphical Interface
@subsection GDB Graphical Interface
+By default, the command @code{gdb} starts GDB using a graphical
+interface where you view and control the program's data using Emacs
+windows. You can still interact with GDB through the GUD buffer, but
+the point of this mode is that you can do it through menus and clicks,
+without needing to know GDB commands.
+
@findex gdba
-The command @code{gdba} starts GDB using a graphical interface where
-you view and control the program's data using Emacs windows. You can
-still interact with GDB through the GUD buffer, but the point of this
-mode is that you can do it through menus and clicks, without needing
-to know GDB commands.
+If you have customised @code{gud-gdb-command-name}, then start this
+mode with the command @code{gdba}.
@menu
-* Breakpoints Buffer:: A breakpoint control panel.
-* Stack Buffer:: Select a frame from the call stack.
-* Data Display:: Display and update expressions in their own buffer.
-* Display Buffer:: Control the displayed expressions.
-* Other Buffers:: Input/output, locals, registers and assembler buffers.
* Layout:: Control the number of displayed buffers.
+* Breakpoints Buffer:: A breakpoint control panel.
+* Stack Buffer:: Select a frame from the call stack.
+* Watch Expressions:: Monitor variable values in the speedbar.
+* Other Buffers:: Input/output, locals, registers, assembler, threads
+ and memory buffers.
@end menu
+@node Layout
+@subsubsection Layout
+@cindex GDB User Interface layout
+
+@findex gdb-many-windows
+@vindex gdb-many-windows
+
+If the variable @code{gdb-many-windows} is @code{nil} (the default
+value) then gdb just pops up the GUD buffer unless the variable
+@code{gdb-show-main} is non-@code{nil}. In this case it starts with
+two windows: one displaying the GUD buffer and the other with the
+source file with the main routine of the inferior.
+
+If @code{gdb-many-windows} is non-@code{nil}, regardless of the value of
+@code{gdb-show-main}, the layout below will appear unless
+@code{gdb-use-inferior-io-buffer} is @code{nil}. In this case the
+source buffer occupies the full width of the frame.
+
+@multitable @columnfractions .5 .5
+@item GUD buffer (I/O of GDB)
+@tab Locals buffer
+@item
+@tab
+@item Source buffer
+@tab Input/Output (of inferior) buffer
+@item
+@tab
+@item Stack buffer
+@tab Breakpoints buffer
+@end multitable
+
+To toggle this layout, do @kbd{M-x gdb-many-windows}.
+
+@findex gdb-restore-windows
+If you change the window layout, for example, while editing and
+re-compiling your program, then you can restore it with the command
+@code{gdb-restore-windows}.
+
+You may also choose which additional buffers you want to display,
+either in the same frame or a different one. Select GDB-windows or
+GDB-Frames from the menu-bar under the heading GUD. If the menu-bar
+is unavailable, type @code{M-x
+gdb-display-@var{buffertype}-buffer} or @code{M-x
+gdb-frame-@var{buffertype}-buffer} respectively, where @var{buffertype}
+is the relevant buffer type e.g breakpoints.
+
+When you finish debugging then kill the GUD 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 continue debugging. When you
+restart execution, GDB will automatically find your new executable.
+Keeping the GUD buffer has the advantage of keeping the shell history
+as well as GDB's breakpoints. You need to check, however, that the
+breakpoints in the recently edited code are still where you want them.
+
@node Breakpoints Buffer
@subsubsection Breakpoints Buffer
-The breakpoints buffer shows the existing breakpoints and watchpoints
+The breakpoints buffer shows the existing breakpoints and watchpoints
(@pxref{Breakpoints,,, gdb, The GNU debugger}). It has three special
commands:
@table @kbd
-@item @key{SPC}
+@item @key{SPC}
@kindex SPC @r{(GDB breakpoints buffer)}
@findex gdb-toggle-breakpoint
Enable/disable the breakpoint at the current line
locals buffer is displayed then its contents update to display the
variables that are local to the new frame.
-@node Data Display
-@subsubsection Data Display
-@cindex displaying expressions in GDB
+@node Watch Expressions
+@subsubsection Watch Expressions
+@cindex Watching expressions in GDB
If you want to see how a variable changes each time your program stops
-then place the cursor over the variable name and click on the display
-icon in the toolbar (@code{gud-display}).
-
-Each displayed expression has its own frame on a graphical display and
-its own buffer on a text-only terminal. Arrays and structures have
-their own display formats. To display an array as a slice, at the top
-of the display window, click @kbd{Mouse-2} on the array index that you
-want to restrict and you will be prompted in the mini-buffer for a
-start and a stop value. Click @kbd{Mouse-2} on a pointer to
-dereference it in the same frame/buffer. Click @kbd{S-Mouse-2} there
-to do the same thing but in a new frame/buffer. There are two special
-commands for these buffers:
-
-@table @kbd
-@item @kbd{v}
-@kindex v @r{(GDB data buffer)}
-@findex gdb-array-visualise
-Visualise an array using the graph program from plotutils if this is
-installed. This only works for one dimensional arrays
-(@code{gdb-array-visualise}).
-
-@item @kbd{q}
-@kindex q @r{(GDB data buffer)}
-@findex gdb-delete-expression
-Delete the displayed expression and the associated frame
-(@code{gdb-delete-expression}).
-@end table
-
-@node Display Buffer
-@subsubsection Display Buffer
-
-The display buffer shows the list of displayed expressions
-(@pxref{Auto Display,,, gdb, The GNU debugger}). As with the
-breakpoints, you can enable/disable or delete the displayed
-expressions:
-
-@table @kbd
-@item @key{SPC}
-@kindex SPC @r{(GDB display buffer)}
-@findex gdb-toggle-display
-Enable/disable the display at the current line
-(@code{gdb-toggle-display}).
-
-@item @kbd{d}
-@kindex d @r{(GDB display buffer)}
-@findex gdb-delete-display
-Delete the display at the current line (@code{gdb-delete-display}).
-@end table
+then place the cursor over the variable name and click on the watch
+icon in the toolbar (@code{gud-watch}).
+
+Each watch expression is displayed in the speedbar. Complex data
+types, such as arrays, structures and unions are represented in a tree
+format. To expand or contract a complex data type, click @kbd{Mouse-2}
+on the tag to the left of the expression.
+
+@kindex RET @r{(GDB speedbar)}
+@findex gdb-var-delete
+With the cursor over the root expression of a complex data type, type
+@kbd{D} to delete it from the speedbar
+(@code{gdb-var-delete}).
+
+@findex gdb-edit-value
+With the cursor over a simple data type or an element of a complex
+data type which holds a value, type @key{RET} or click @kbd{Mouse-2} to edit
+its value. A prompt for a new value appears in the mini-buffer
+(@code{gdb-edit-value}).
+
+If you set the variable @code{gdb-show-changed-values} to
+non-@code{nil} (the default value), then Emacs will use
+font-lock-warning-face to display values that have recently changed in
+the speedbar.
+
+If you set the variable @code{gdb-use-colon-colon-notation} to a
+non-@code{nil} value, then, in C, Emacs will use the
+FUNCTION::VARIABLE format to display variables in the speedbar.
+Since this does not work for variables defined in compound statements,
+the default value is @code{nil}.
@node Other Buffers
@subsubsection Other Buffers
@table @asis
@item Input/Output Buffer
-The executable program that is being debugged takes its input and
+If the variable @code{gdb-use-inferior-io-buffer} is non-@code{nil},
+the executable program that is being debugged takes its input and
displays its output here. Some of the commands from shell mode are
available here. @xref{Shell Mode}.
debugger}).
Arrays and structures display their type only. You must display them
-separately to examine their values. @ref{Data Display}.
+separately to examine their values. @ref{Watch Expressions}.
@item Registers Buffer
The registers buffer displays the values held by the registers
@item Assembler Buffer
The assembler buffer displays the current frame as machine code. An
overlay arrow points to the current instruction and you can set and
-remove breakpoints as with the source buffer. Breakpoints also
-appear in the margin.
-@end table
+remove breakpoints as with the source buffer. Breakpoint icons also
+appear in the fringe or margin.
-@node Layout
-@subsubsection Layout
-@cindex GDB User Interface layout
-You may choose to display the additional buffers described previously
-either in the same frame or a different one. Select GDB-windows or
-GDB-Frames from the menu-bar under the heading GUD. If the menu-bar
-is unavailable, type @code{M-x
-gdb-display-@var{buffertype}-buffer} or @code{M-x
-gdb-frame-@var{buffertype}-buffer} respectively, where @var{buffertype}
-is the relevant buffer type e.g breakpoints.
+@item Threads Buffer
-@findex gdb-many-windows
-@vindex gdb-many-windows
-If @code{gdb-many-windows} is @code{nil} (the default value), then GDB starts
-with just two windows: the GUD and the source buffer. If it is @code{t}, then
-six windows with the following layout will appear:
+The threads buffer displays a summary of all threads currently in your
+program (@pxref{Threads,,, gdb, The GNU debugger}). Move point to
+any thread in the list and type @key{RET} to make it become the
+current thread (@code{gdb-threads-select}) and display the associated
+source in the source buffer. Alternatively, click @kbd{Mouse-2} to
+make the selected thread become the current one.
-@multitable @columnfractions .5 .5
-@item GUD buffer (I/O of GDB)
-@tab Locals buffer
-@item
-@tab
-@item Source buffer
-@tab Input/Output (of debuggee) buffer
-@item
-@tab
-@item Stack buffer
-@tab Breakpoints buffer
-@end multitable
+@item Memory Buffer
-To toggle this layout, do @kbd{M-x gdb-many-windows}.
+The memory buffer allows the user to examine sections of program
+memory (@pxref{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.
-@findex gdb-restore-windows
-If you change the window layout, for example, while editing and
-re-compiling your program, then you can restore it with
-@code{gdb-restore-windows}.
+@end table
@node Executing Lisp
@section Executing Lisp Expressions
@code{t} if you want to try loading them.
@node Lisp Eval
-@section Evaluating Emacs-Lisp Expressions
+@section Evaluating Emacs Lisp Expressions
@cindex Emacs-Lisp mode
@cindex mode, Emacs-Lisp
variable to the initial value specified in the @code{defvar} expression.
@code{defcustom} expressions are treated similarly.
This special feature is convenient for debugging Lisp programs.
+Typing @kbd{C-M-x} on a @code{defface} expression reinitializes
+the face according to the @code{defface} specification.
@kindex C-x C-e
@findex eval-last-sexp