Improve release doc slightly.

[deliverable/binutils-gdb.git] / gdb / doc / gdb.emacs-m4

_dnl__								-*- Texinfo -*-
_dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc.
_dnl__ This file is part of the source for the GDB manual.
@c M4 FRAGMENT: $Id$
@node Emacs, _GDBN__ Bugs, Sequences, Top
@chapter Using _GDBN__ under GNU Emacs

@cindex emacs
A special interface allows you to use GNU Emacs to view (and
edit) the source files for the program you are debugging with
_GDBN__.

To use this interface, use the command @kbd{M-x gdb} in Emacs.  Give the
executable file you want to debug as an argument.  This command starts
_GDBN__ as a subprocess of Emacs, with input and output through a newly
created Emacs buffer.

Using _GDBN__ under Emacs is just like using _GDBN__ normally except for two
things:

@itemize @bullet
@item
All ``terminal'' input and output goes through the Emacs buffer.  
@end itemize

This applies both to _GDBN__ commands and their output, and to the input
and output done by the program you are debugging.

This is useful because it means that you can copy the text of previous
commands and input them again; you can even use parts of the output
in this way.

All the facilities of Emacs' Shell mode are available for this purpose.

@itemize @bullet
@item
_GDBN__ displays source code through Emacs.  
@end itemize

Each time _GDBN__ displays a stack frame, Emacs automatically finds the
source file for that frame and puts an arrow (_0__@samp{=>}_1__) at the
left margin of the current line.  Emacs uses a separate buffer for
source display, and splits the window to show both your _GDBN__ session
and the source.

Explicit _GDBN__ @code{list} or search commands still produce output as
usual, but you probably will have no reason to use them.

@quotation
@emph{Warning:} If the directory where your program resides is not your
current directory, it can be easy to confuse Emacs about the location of
the source files, in which case the auxiliary display buffer will not
appear to show your source.  _GDBN__ can find programs by searching your
environment's @code{PATH} variable, so the _GDBN__ input and output
session will proceed normally; but Emacs doesn't get enough information
back from _GDBN__ to locate the source files in this situation.  To
avoid this problem, either start _GDBN__ mode from the directory where
your program resides, or specify a full path name when prompted for the
@kbd{M-x gdb} argument.

A similar confusion can result if you use the _GDBN__ @code{file} command to
switch to debugging a program in some other location, from an existing
_GDBN__ buffer in Emacs.
@end quotation

By default, @kbd{M-x gdb} calls the program called @file{gdb}.  If
you need to call _GDBN__ by a different name (for example, if you keep
several configurations around, with different names) you can set the
Emacs variable @code{gdb-command-name}; for example,
@example
(setq gdb-command-name "mygdb")
@end example
@noindent
(preceded by @kbd{ESC ESC}, or typed in the @code{*scratch*} buffer, or
in your @file{.emacs} file) will make Emacs call the program named
``@code{mygdb}'' instead.

In the _GDBN__ I/O buffer, you can use these special Emacs commands in
addition to the standard Shell mode commands:

@table @kbd
@item C-h m
Describe the features of Emacs' _GDBN__ Mode.

@item M-s
Execute to another source line, like the _GDBN__ @code{step} command; also
update the display window to show the current file and location.

@item M-n
Execute to next source line in this function, skipping all function
calls, like the _GDBN__ @code{next} command.  Then update the display window
to show the current file and location.

@item M-i
Execute one instruction, like the _GDBN__ @code{stepi} command; update
display window accordingly.

@item M-x gdb-nexti
Execute to next instruction, using the _GDBN__ @code{nexti} command; update
display window accordingly.

@item C-c C-f
Execute until exit from the selected stack frame, like the _GDBN__
@code{finish} command.

@item M-c
Continue execution of the program, like the _GDBN__ @code{continue}
command.  @emph{Warning:} In Emacs v19, this command is @kbd{C-c C-p}.

@item M-u
Go up the number of frames indicated by the numeric argument
(@pxref{Arguments, , Numeric Arguments, emacs, The GNU Emacs Manual}),
like the _GDBN__ @code{up} command.  @emph{Warning:} In Emacs v19, this
command is @kbd{C-c C-u}.@refill

@item M-d
Go down the number of frames indicated by the numeric argument, like the
_GDBN__ @code{down} command.  @emph{Warning:} In Emacs v19, this command
is @kbd{C-c C-d}.

@item C-x &
Read the number where the cursor is positioned, and insert it at the end
of the _GDBN__ I/O buffer.  For example, if you wish to disassemble code
around an address that was displayed earlier, type @kbd{disassemble};
then move the cursor to the address display, and pick up the
argument for @code{disassemble} by typing @kbd{C-x &}.  

You can customize this further on the fly by defining elements of the list
@code{gdb-print-command}; once it is defined, you can format or
otherwise process numbers picked up by @kbd{C-x &} before they are
inserted.  A numeric argument to @kbd{C-x &} will both flag that you
wish special formatting, and act as an index to pick an element of the
list.  If the list element is a string, the number to be inserted is
formatted using the Emacs function @code{format}; otherwise the number
is passed as an argument to the corresponding list element.

@end table

In any source file, the Emacs command @kbd{C-x SPC} (@code{gdb-break})
tells _GDBN__ to set a breakpoint on the source line point is on.

If you accidentally delete the source-display buffer, an easy way to get
it back is to type the command @code{f} in the _GDBN__ buffer, to
request a frame display; when you run under Emacs, this will recreate
the source buffer if necessary to show you the context of the current
frame.

The source files displayed in Emacs are in ordinary Emacs buffers
which are visiting the source files in the usual way.  You can edit
the files with these buffers if you wish; but keep in mind that _GDBN__
communicates with Emacs in terms of line numbers.  If you add or
delete lines from the text, the line numbers that _GDBN__ knows will cease
to correspond properly to the code.

@c The following dropped because Epoch is nonstandard.  Reactivate
@c if/when v19 does something similar. ---pesch@cygnus.com 19dec1990
@ignore
@kindex emacs epoch environment  
@kindex epoch
@kindex inspect

Version 18 of Emacs has a built-in window system called the @code{epoch}
environment.  Users of this environment can use a new command,
@code{inspect} which performs identically to @code{print} except that
each value is printed in its own window.
@end ignore