gdb/doc/gdb.emacs-m4

   1 _dnl__                                                          -*- Texinfo -*-
   2 _dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc.
   3 _dnl__ This file is part of the source for the GDB manual.
   4 _dnl__ $Id$
   5 @node Emacs, _GDBN__ Bugs, Sequences, Top
   6 @chapter Using _GDBN__ under GNU Emacs
   7
   8 @cindex emacs
   9 A special interface allows you to use GNU Emacs to view (and
  10 edit) the source files for the program you are debugging with
  11 _GDBN__.
  12
  13 To use this interface, use the command @kbd{M-x gdb} in Emacs.  Give the
  14 executable file you want to debug as an argument.  This command starts
  15 _GDBN__ as a subprocess of Emacs, with input and output through a newly
  16 created Emacs buffer.
  17
  18 Using _GDBN__ under Emacs is just like using _GDBN__ normally except for two
  19 things:
  20
  21 @itemize @bullet
  22 @item
  23 All ``terminal'' input and output goes through the Emacs buffer.
  24 @end itemize
  25
  26 This applies both to _GDBN__ commands and their output, and to the input
  27 and output done by the program you are debugging.
  28
  29 This is useful because it means that you can copy the text of previous
  30 commands and input them again; you can even use parts of the output
  31 in this way.
  32
  33 All the facilities of Emacs' Shell mode are available for this purpose.
  34
  35 @itemize @bullet
  36 @item
  37 _GDBN__ displays source code through Emacs.
  38 @end itemize
  39
  40 Each time _GDBN__ displays a stack frame, Emacs automatically finds the
  41 source file for that frame and puts an arrow (_0__@samp{=>}_1__) at the
  42 left margin of the current line.  Emacs uses a separate buffer for
  43 source display, and splits the window to show both your _GDBN__ session
  44 and the source.
  45
  46 Explicit _GDBN__ @code{list} or search commands still produce output as
  47 usual, but you probably will have no reason to use them.
  48
  49 @quotation
  50 @emph{Warning:} If the directory where your program resides is not your
  51 current directory, it can be easy to confuse Emacs about the location of
  52 the source files, in which case the auxiliary display buffer will not
  53 appear to show your source.  _GDBN__ can find programs by searching your
  54 environment's @code{PATH} variable, so the _GDBN__ input and output
  55 session will proceed normally; but Emacs doesn't get enough information
  56 back from _GDBN__ to locate the source files in this situation.  To
  57 avoid this problem, either start _GDBN__ mode from the directory where
  58 your program resides, or specify a full path name when prompted for the
  59 @kbd{M-x gdb} argument.
  60
  61 A similar confusion can result if you use the _GDBN__ @code{file} command to
  62 switch to debugging a program in some other location, from an existing
  63 _GDBN__ buffer in Emacs.
  64 @end quotation
  65
  66 By default, @kbd{M-x gdb} calls the program called @file{gdb}.  If
  67 you need to call _GDBN__ by a different name (for example, if you keep
  68 several configurations around, with different names) you can set the
  69 Emacs variable @code{gdb-command-name}; for example,
  70 @example
  71 (setq gdb-command-name "mygdb")
  72 @end example
  73 @noindent
  74 (preceded by @kbd{ESC ESC}, or typed in the @code{*scratch*} buffer, or
  75 in your @file{.emacs} file) will make Emacs call the program named
  76 ``@code{mygdb}'' instead.
  77
  78 In the _GDBN__ I/O buffer, you can use these special Emacs commands in
  79 addition to the standard Shell mode commands:
  80
  81 @table @kbd
  82 @item C-h m
  83 Describe the features of Emacs' _GDBN__ Mode.
  84
  85 @item M-s
  86 Execute to another source line, like the _GDBN__ @code{step} command; also
  87 update the display window to show the current file and location.
  88
  89 @item M-n
  90 Execute to next source line in this function, skipping all function
  91 calls, like the _GDBN__ @code{next} command.  Then update the display window
  92 to show the current file and location.
  93
  94 @item M-i
  95 Execute one instruction, like the _GDBN__ @code{stepi} command; update
  96 display window accordingly.
  97
  98 @item M-x gdb-nexti
  99 Execute to next instruction, using the _GDBN__ @code{nexti} command; update
 100 display window accordingly.
 101
 102 @item C-c C-f
 103 Execute until exit from the selected stack frame, like the _GDBN__
 104 @code{finish} command.
 105
 106 @item M-c
 107 Continue execution of the program, like the _GDBN__ @code{continue}
 108 command.  @emph{Warning:} In Emacs v19, this command is @kbd{C-c C-p}.
 109
 110 @item M-u
 111 Go up the number of frames indicated by the numeric argument
 112 (@pxref{Arguments, , Numeric Arguments, emacs, The GNU Emacs Manual}),
 113 like the _GDBN__ @code{up} command.  @emph{Warning:} In Emacs v19, this
 114 command is @kbd{C-c C-u}.@refill
 115
 116 @item M-d
 117 Go down the number of frames indicated by the numeric argument, like the
 118 _GDBN__ @code{down} command.  @emph{Warning:} In Emacs v19, this command
 119 is @kbd{C-c C-d}.
 120
 121 @item C-x &
 122 Read the number where the cursor is positioned, and insert it at the end
 123 of the _GDBN__ I/O buffer.  For example, if you wish to disassemble code
 124 around an address that was displayed earlier, type @kbd{disassemble};
 125 then move the cursor to the address display, and pick up the
 126 argument for @code{disassemble} by typing @kbd{C-x &}.
 127
 128 You can customize this further on the fly by defining elements of the list
 129 @code{gdb-print-command}; once it is defined, you can format or
 130 otherwise process numbers picked up by @kbd{C-x &} before they are
 131 inserted.  A numeric argument to @kbd{C-x &} will both flag that you
 132 wish special formatting, and act as an index to pick an element of the
 133 list.  If the list element is a string, the number to be inserted is
 134 formatted using the Emacs function @code{format}; otherwise the number
 135 is passed as an argument to the corresponding list element.
 136
 137 @end table
 138
 139 In any source file, the Emacs command @kbd{C-x SPC} (@code{gdb-break})
 140 tells _GDBN__ to set a breakpoint on the source line point is on.
 141
 142 If you accidentally delete the source-display buffer, an easy way to get
 143 it back is to type the command @code{f} in the _GDBN__ buffer, to
 144 request a frame display; when you run under Emacs, this will recreate
 145 the source buffer if necessary to show you the context of the current
 146 frame.
 147
 148 The source files displayed in Emacs are in ordinary Emacs buffers
 149 which are visiting the source files in the usual way.  You can edit
 150 the files with these buffers if you wish; but keep in mind that _GDBN__
 151 communicates with Emacs in terms of line numbers.  If you add or
 152 delete lines from the text, the line numbers that _GDBN__ knows will cease
 153 to correspond properly to the code.
 154
 155 @c The following dropped because Epoch is nonstandard.  Reactivate
 156 @c if/when v19 does something similar. ---pesch@cygnus.com 19dec1990
 157 @ignore
 158 @kindex emacs epoch environment
 159 @kindex epoch
 160 @kindex inspect
 161
 162 Version 18 of Emacs has a built-in window system called the @code{epoch}
 163 environment.  Users of this environment can use a new command,
 164 @code{inspect} which performs identically to @code{print} except that
 165 each value is printed in its own window.
 166 @end ignore