From 0595bd7e90cca425fe1d9abe145f8ead4d963a57 Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Sat, 10 Dec 2011 15:39:43 +0800 Subject: [PATCH] More updates to Building chapter of Emacs manual. * doc/emacs/building.texi (Compilation): Say what the -k flag to make does. Move subprocess discussion to Compilation Shell. (Compilation Mode): Add xref for grep, occur, and mouse references. Define "locus". (Grep Searching): Use @command. (Debuggers, Commands of GUD, GDB Graphical Interface): Clarify intro. (Starting GUD): Clarify how arguments are specified. (Debugger Operation): Index entry for "GUD interaction buffer", and move basic description here from Commands of GUD node. (GDB User Interface Layout): Copyedits. (Source Buffers): Remove gdb-find-source-frame, which is not in gdb-mi.el. (Other GDB Buffers): Remove gdb-use-separate-io-buffer and toggle-gdb-all-registers, which are not in gdb-mi.el. Don't re-document GUD interaction buffers. --- doc/emacs/ChangeLog | 13 +- doc/emacs/building.texi | 696 +++++++++++++++++++--------------------- doc/emacs/emacs.texi | 3 +- 3 files changed, 339 insertions(+), 373 deletions(-) diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog index 2627586f1f4..d0a22bbd867 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@ -1,10 +1,21 @@ -2011-12-08 Chong Yidong +2011-12-10 Chong Yidong * building.texi (Compilation): Say what the -k flag to make does. Move subprocess discussion to Compilation Shell. (Compilation Mode): Add xref for grep, occur, and mouse references. Define "locus". (Grep Searching): Use @command. + (Debuggers, Commands of GUD, GDB Graphical Interface): Clarify + intro. + (Starting GUD): Clarify how arguments are specified. + (Debugger Operation): Index entry for "GUD interaction buffer", + and move basic description here from Commands of GUD node. + (GDB User Interface Layout): Copyedits. + (Source Buffers): Remove gdb-find-source-frame, which is not in + gdb-mi.el. + (Other GDB Buffers): Remove gdb-use-separate-io-buffer and + toggle-gdb-all-registers, which are not in gdb-mi.el. Don't + re-document GUD interaction buffers. * programs.texi (Symbol Completion): M-TAB can now use Semantic. (Semantic): Add cindex entries for Semantic. diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi index 34ac5887a1d..5e2cb8119de 100644 --- a/doc/emacs/building.texi +++ b/doc/emacs/building.texi @@ -453,16 +453,18 @@ see the Flymake Info manual, which is distributed with Emacs. @cindex JDB @cindex PDB -@c Do you believe in GUD? 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. +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. - 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. + 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}. @menu * Starting GUD:: How to start a debugger subprocess. @@ -477,146 +479,136 @@ Lisp Reference Manual}, for information on the Emacs Lisp debugger. @node Starting GUD @subsection Starting GUD - There are several commands for starting a debugger under GUD, each + There are several commands for starting a debugger subprocess, each corresponding to a particular debugger program. @table @kbd -@item M-x gdb @key{RET} @var{file} @key{RET} +@item M-x gdb @findex gdb -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. +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. -@item M-x gud-gdb @key{RET} @var{file} @key{RET} +@item M-x gud-gdb @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 -Run DBX as a subprocess of Emacs. Since Emacs does not implement a -graphical interface for DBX, communication with DBX works by typing -commands in the GUD interaction buffer. The same is true for all -the other supported debuggers. +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. -@item M-x xdb @key{RET} @var{file} @key{RET} -@findex xdb -@vindex gud-xdb-directories -Run XDB as a subprocess of Emacs. Use the variable -@code{gud-xdb-directories} to specify directories to search for source -files. +The other commands in this list do the same, for other debugger +programs. -@item M-x sdb @key{RET} @var{file} @key{RET} -@findex sdb -Run SDB as a subprocess of Emacs. - -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. - -@item M-x perldb @key{RET} @var{file} @key{RET} +@item M-x perldb @findex perldb -Run the Perl interpreter in debug mode to debug @var{file}, a Perl program. +Run the Perl interpreter in debug mode. -@item M-x jdb @key{RET} @var{file} @key{RET} +@item M-x jdb @findex jdb -Run the Java debugger to debug @var{file}. +Run the Java debugger. -@item M-x pdb @key{RET} @var{file} @key{RET} +@item M-x pdb @findex pdb -Run the Python debugger to debug @var{file}. +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. @end table - Each of these commands takes one argument: a command line to invoke -the debugger. In the simplest case, specify just the name of the -executable file you want to debug. You may also use options that the -debugger supports. However, shell wildcards and variables are not -allowed. GUD assumes that the first argument not starting with a -@samp{-} is the executable file name. + 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. @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}). + 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}). @node Debugger Operation @subsection Debugger Operation +@cindex GUD interaction buffer -@cindex fringes, and current execution line in GUD - Generally when you run a debugger with GUD, the debugger uses an Emacs -buffer for its ordinary input and output. This is called the GUD -buffer. Input and output from the program you are debugging also use -this buffer. We call this @dfn{text command mode}. The GDB Graphical -Interface can use further buffers (@pxref{GDB Graphical Interface}). - - The debugger displays the source files of the program by visiting -them in Emacs buffers. An arrow in the left fringe indicates the -current execution line.@footnote{On a text-only terminal, the arrow -appears as @samp{=>} and overlays the first two text columns.} Moving -point in this buffer does not move the arrow. The arrow is not part -of the file's text; it appears only on the screen. - - You can start editing these source files at any time in the buffers -that display them. If you do modify a source file, keep in mind that -inserting or deleting lines will throw off the arrow's positioning; -GUD has no way of figuring out which line corresponded before your -changes to the line number in a debugger message. Also, you'll -typically have to recompile and restart the program for your changes -to be reflected in the debugger's tables. - -@cindex tooltips with GUD -@vindex tooltip-gud-modes -@vindex gud-tooltip-mode + 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 @vindex gud-tooltip-echo-area - The Tooltip facility (@pxref{Tooltips}) provides support for GUD@. -You activate this feature by turning on the minor mode -@code{gud-tooltip-mode}. Then you can display a variable's value in a -tooltip simply by pointing at it with the mouse. This operates in the -GUD buffer and in source buffers with major modes in the list -@code{gud-tooltip-modes}. If the variable @code{gud-tooltip-echo-area} -is non-@code{nil} then the variable's value is displayed in the echo -area. When debugging a C program using the GDB Graphical Interface, you -can also display macro definitions associated with an identifier when -the program is not executing. - - GUD tooltips are disabled when you use GDB in text command mode -(@pxref{GDB Graphical Interface}), because displaying an expression's -value in GDB can sometimes expand a macro and result in a side effect -that interferes with the program's operation. The GDB graphical -interface supports GUD tooltips and assures they will not cause side -effects. + 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. @node Commands of GUD @subsection Commands of GUD - The GUD interaction buffer uses a variant of Shell mode, so the -Emacs commands of Shell mode are available (@pxref{Shell Mode}). All -the usual commands for your debugger are available, and you can use -the Shell mode history commands to repeat them. If you wish, you can -control your debugger process entirely through this buffer. - - GUD mode 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. It also has its own tool -bar from which you can invoke the more common commands by clicking on -the appropriate icon. This is particularly useful for repetitive -commands like @code{gud-next} and @code{gud-step}, and allows you to -keep the GUD buffer hidden. - - The breakpoint commands are normally used in source file buffers, -because that is the easiest way to specify where to set or clear the -breakpoint. Here's the global command to set a breakpoint: + GUD provides commands for setting and clearing breakpoints, +selecting stack frames, and stepping through the program. @table @kbd @item C-x @key{SPC} @@ -624,35 +616,42 @@ breakpoint. Here's the global command to set a breakpoint: Set a breakpoint on the source line that point is on. @end table + @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. + @kindex C-x C-a @r{(GUD)} - Here are the other special commands provided by GUD@. The keys + The following commands are available both in the GUD interaction +buffer and globally, but with different key bindings. The keys starting with @kbd{C-c} are available only in the GUD interaction -buffer. The key bindings that start with @kbd{C-x C-a} are available -in the GUD interaction buffer and also in source files. Some of these -commands are not available to all the supported debuggers. +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. @table @kbd @item C-c C-l @kindex C-c C-l @r{(GUD)} @itemx C-x C-a C-l @findex gud-refresh -Display in another window the last line referred to in the GUD -buffer (that is, the line indicated in the last location message). -This runs the command @code{gud-refresh}. +Display, in another window, the last source line referred to in the +GUD interaction buffer (@code{gud-refresh}). @item C-c C-s @kindex C-c C-s @r{(GUD)} @itemx C-x C-a C-s @findex gud-step -Execute a single line of code (@code{gud-step}). If the line contains -a function call, execution stops after entering the called function. +Execute the next single line of code (@code{gud-step}). If the line +contains a function call, execution stops after entering the called +function. @item C-c C-n @kindex C-c C-n @r{(GUD)} @itemx C-x C-a C-n @findex gud-next -Execute a single line of code, stepping across entire function calls -at full speed (@code{gud-next}). +Execute the next single line of code, stepping across function calls +without stopping inside the functions (@code{gud-next}). @item C-c C-i @kindex C-c C-i @r{(GUD)} @@ -763,17 +762,17 @@ Instead, type @kbd{C-q @key{TAB}} to enter a tab. @vindex perldb-mode-hook @vindex pdb-mode-hook @vindex jdb-mode-hook - 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. You can -use these hooks to define custom key bindings for the debugger -interaction buffer. @xref{Hooks}. - - Here is a convenient way to define a command that sends a particular -command string to the debugger, and set up a key binding for it in the -debugger interaction buffer: + 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: @findex gud-def @example @@ -829,21 +828,22 @@ Fully qualified class name derived from the expression surrounding point @node GDB Graphical Interface @subsection GDB Graphical Interface - The command @code{gdb} starts GDB in a graphical interface, using -Emacs windows for display program state information. 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. + 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. @vindex gud-gdb-command-name - 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. + 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. @menu * GDB User Interface Layout:: Control the number of displayed buffers. @@ -852,8 +852,7 @@ multiple programs within one Emacs session. * Breakpoints Buffer:: A breakpoint control panel. * Threads Buffer:: Displays your threads. * Stack Buffer:: Select a frame from the call stack. -* Other GDB Buffers:: Input/output, locals, registers, - assembler, threads and memory buffers. +* Other GDB Buffers:: Other buffers for controlling the GDB state. * Watch Expressions:: Monitor variable values in the speedbar. * Multithreaded Debugging:: Debugging programs with several threads. @end menu @@ -863,12 +862,12 @@ multiple programs within one Emacs session. @cindex GDB User Interface layout @vindex gdb-many-windows - If the variable @code{gdb-many-windows} is @code{nil} (the default -value) then @kbd{M-x gdb} normally displays only the GUD buffer. + If the variable @code{gdb-many-windows} is @code{nil} (the default), +@kbd{M-x gdb} normally displays only the GUD interaction buffer. However, if the variable @code{gdb-show-main} is also non-@code{nil}, -it starts with two windows: one displaying the GUD buffer, and the -other showing the source for the @code{main} function of the program -you are debugging. +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. If @code{gdb-many-windows} is non-@code{nil}, then @kbd{M-x gdb} displays the following frame layout: @@ -876,7 +875,7 @@ displays the following frame layout: @smallexample @group +--------------------------------+--------------------------------+ -| GUD buffer (I/O of GDB) | Locals/Registers buffer | +| GUD interaction buffer | Locals/Registers buffer | |--------------------------------+--------------------------------+ | Primary Source buffer | I/O buffer for debugged pgm | |--------------------------------+--------------------------------+ @@ -890,264 +889,233 @@ buffer does not appear and the primary source buffer occupies the full width of the frame. @findex gdb-restore-windows - If you change the window layout, for example, while editing and -re-compiling your program, then you can restore this standard window -layout with the command @code{gdb-restore-windows}. - @findex gdb-many-windows - To switch between this standard layout and a simple layout -containing just the GUD buffer and a source file, type @kbd{M-x -gdb-many-windows}. + 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}. You may also specify additional GDB-related buffers to display, either in the same frame or a different one. Select the buffers you -want with the @samp{GUD->GDB-Windows} and @samp{GUD->GDB-Frames} -sub-menus. 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, such as -@samp{breakpoints}. Most of these buffers are read-only, and typing -@kbd{q} in them kills them. - - When you finish debugging, 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 do need to check that the -breakpoints in recently edited source files are still in the right -places. +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. @node Source Buffers @subsubsection Source Buffers -@cindex GDB commands in Fringe - -@c @findex gdb-mouse-set-clear-breakpoint -@c @findex gdb-mouse-toggle-breakpoint -Many GDB commands can be entered using key bindings or the tool bar but -sometimes it is quicker to use the fringe. These commands either -manipulate breakpoints or control program execution. When there is no -fringe, you can use the margin but this is only present when the -source file already has a breakpoint. - -You can click @kbd{Mouse-1} in the fringe or display margin of a -source buffer to set a breakpoint there and, on a graphical display, a -red bullet will appear on that line. If a breakpoint already exists -on that line, the same click will remove it. You can also enable or -disable a breakpoint by clicking @kbd{C-Mouse-1} on the bullet. - -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 higher level -frames. - -If you drag the arrow in the fringe with @kbd{Mouse-1} -(@code{gdb-mouse-until}), execution will continue to the line where -you release the button, provided it is still in the same frame. -Alternatively, you can click @kbd{Mouse-3} at some point in the fringe -of this buffer and execution will advance to there. A similar command -(@code{gdb-mouse-jump}) allows you to jump to a source line without -executing the intermediate lines by clicking @kbd{C-Mouse-3}. 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. +@cindex fringes, for debugging -@table @kbd -@item Mouse-1 -Set or clear a breakpoint. +@table @asis +@item @kbd{Mouse-1} (in fringe) +Set or clear a breakpoint on that line. -@item C-Mouse-1 -Enable or disable a breakpoint. +@item @kbd{C-Mouse-1} (in fringe) +Enable or disable a breakpoint on that line. -@item Mouse-3 -Continue execution to here. +@item @kbd{Mouse-3} (in fringe) +Continue execution to that line. -@item C-Mouse-3 -Jump to here. +@item @kbd{C-Mouse-3} (in fringe) +Jump to that line. @end table -If the variable @code{gdb-find-source-frame} is non-@code{nil} and -execution stops in a frame for which there is no source code e.g after -an interrupt, then Emacs finds and displays the first frame further up -stack for which there is source. If it is @code{nil} then the source -buffer continues to display the last frame which maybe more useful, -for example, when re-setting a breakpoint. + 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. @node Breakpoints Buffer @subsubsection Breakpoints Buffer - The breakpoints buffer shows the existing breakpoints, watchpoints and -catchpoints (@pxref{Breakpoints,,, gdb, The GNU debugger}). It has -these special commands, which mostly apply to the @dfn{current -breakpoint}, the breakpoint which point is on. + 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): @table @kbd @item @key{SPC} -@kindex SPC @r{(GDB breakpoints buffer)} +@kindex SPC @r{(GDB Breakpoints buffer)} @findex gdb-toggle-breakpoint -Enable/disable current breakpoint (@code{gdb-toggle-breakpoint}). -On a graphical display, this changes the color of a bullet in the -margin of a source buffer at the relevant line. This is red when -the breakpoint is enabled and gray when it is disabled. Text-only -terminals correspondingly display a @samp{B} or @samp{b}. +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. @item D -@kindex D @r{(GDB breakpoints buffer)} +@kindex D @r{(GDB Breakpoints buffer)} @findex gdb-delete-breakpoint Delete the current breakpoint (@code{gdb-delete-breakpoint}). @item @key{RET} -@kindex RET @r{(GDB breakpoints buffer)} +@kindex RET @r{(GDB Breakpoints buffer)} @findex gdb-goto-breakpoint Visit the source line for the current breakpoint (@code{gdb-goto-breakpoint}). @item Mouse-2 -@kindex Mouse-2 @r{(GDB breakpoints buffer)} +@kindex Mouse-2 @r{(GDB Breakpoints buffer)} Visit the source line for the breakpoint you click on. @end table @vindex gdb-show-threads-by-default -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. If @code{gdb-show-threads-by-default} is non-@code{nil}, the -threads buffer, rather than the breakpoints buffer, is shown at start -up. + 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. @node Threads Buffer @subsubsection Threads Buffer @findex gdb-select-thread -The threads buffer displays a summary of all threads currently in your -program (@pxref{Threads, Threads, Debugging programs with multiple -threads, gdb, The GNU debugger}). Move point to any thread in the list -and press @key{RET} to select it (@code{gdb-select-thread}) and -display the associated source in the primary source buffer. -Alternatively, click @kbd{Mouse-2} on a thread to select it. Contents -of all GDB buffers are updated whenever you select a thread. + 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. You can customize variables under @code{gdb-buffers} group to select -fields included in threads buffer. +fields included in GDB Threads buffer. @table @code @item gdb-thread-buffer-verbose-names @vindex gdb-thread-buffer-verbose-names -Show long thread names like @samp{Thread 0x4e2ab70 (LWP 1983)} in -threads buffer. +Show long thread names like @samp{Thread 0x4e2ab70 (LWP 1983)}. @item gdb-thread-buffer-arguments @vindex gdb-thread-buffer-arguments -Show arguments of thread top frames in threads buffer. +Show arguments of thread top frames. @item gdb-thread-buffer-locations @vindex gdb-thread-buffer-locations -Show file information or library names in threads buffer. +Show file information or library names. @item gdb-thread-buffer-addresses @vindex gdb-thread-buffer-addresses Show addresses for thread frames in threads buffer. @end table - It's possible to observe information for several threads -simultaneously (in addition to buffers which show information for -currently selected thread) using the following keys from the threads -buffer. + To view information for several threads simultaneously, use the +following commands from the GDB Threads buffer. @table @kbd @item d @kindex d @r{(GDB threads buffer)} @findex gdb-display-disassembly-for-thread -Display disassembly buffer for the thread at current line. -(@code{gdb-display-disassembly-for-thread}) +Display disassembly buffer for the thread at current line +(@code{gdb-display-disassembly-for-thread}). @item f @kindex f @r{(GDB threads buffer)} @findex gdb-display-stack-for-thread -Display stack buffer for the thread at current line. +Display the GDB Stack buffer for the thread at current line (@code{gdb-display-stack-for-thread}). @item l @kindex l @r{(GDB threads buffer)} @findex gdb-display-locals-for-thread -Display locals buffer for the thread at current line. +Display the GDB Locals buffer for the thread at current line (@code{gdb-display-locals-for-thread}). @item r @kindex r @r{(GDB threads buffer)} @findex gdb-display-registers-for-thread -Display registers buffer for the thread at current line. +Display the GDB Registers buffer for the thread at current line (@code{gdb-display-registers-for-thread}). @end table -Pressing their upper-case counterparts, @kbd{D}, @kbd{F} ,@kbd{L} and -@kbd{R} displays the corresponding buffer in a new frame. +@noindent +Their upper-case counterparts, @kbd{D}, @kbd{F} ,@kbd{L} and @kbd{R}, +display the corresponding buffer in a new frame. When you create a buffer showing information about some specific thread, it becomes bound to that thread and keeps showing actual -information while you debug your program. Every GDB buffer contains a -number of thread it shows information for in its mode name. Thread -number is also included in the buffer name of bound buffers to prevent -buffer names clashing. +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. -Further commands are available in the threads buffer which depend on the -mode of GDB that is used for controlling execution of your program. -(@pxref{Multithreaded Debugging, Stopping and Starting Multi-threaded Programs}). + 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}. @node Stack Buffer @subsubsection Stack Buffer - The stack buffer displays a @dfn{call stack}, with one line for each -of the nested subroutine calls (@dfn{stack frames}) now active in the -program. @xref{Backtrace,, Backtraces, gdb, The GNU debugger}. + 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}. @findex gdb-frames-select -An arrow in the fringe points to the selected frame or, if the fringe is -not present, the number of the selected frame is displayed in reverse -contrast. To select a frame in GDB, move point in the stack buffer to -that stack frame and type @key{RET} (@code{gdb-frames-select}), or click -@kbd{Mouse-2} on a stack frame. If the locals buffer is visible, -selecting a stack frame updates it to display the local variables of the -new frame. + 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 @node Other GDB Buffers -@subsubsection Other Buffers +@subsubsection Other GDB Buffers @table @asis -@item Input/Output Buffer -@vindex gdb-use-separate-io-buffer -If the variable @code{gdb-use-separate-io-buffer} is non-@code{nil}, -the program being debugged takes its input and displays its output -here. Otherwise it uses the GUD buffer for that. To toggle whether -GUD mode uses this buffer, do @kbd{M-x gdb-use-separate-io-buffer}. -This takes effect when you next restart the program you are debugging. - -The history and replay commands from Shell mode are available here, -as are the commands to send signals to the debugged program. -@xref{Shell Mode}. - @item Locals Buffer -The locals buffer displays the values of local variables of the -current frame for simple data types (@pxref{Frame Info, Frame Info, +This buffer displays the values of local variables of the current +frame for simple data types (@pxref{Frame Info, Frame Info, Information on a frame, gdb, The GNU debugger}). Press @key{RET} or 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, -move point to their name and press @key{RET}, or alternatively click -@kbd{Mouse-2} there, to examine their values. With earlier versions -of GDB, use @kbd{Mouse-2} or @key{RET} on the type description +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 (@samp{[struct/union]} or @samp{[array]}). @xref{Watch Expressions}. @item Registers Buffer @findex toggle-gdb-all-registers -The registers buffer displays the values held by the registers +This buffer displays the values held by the registers (@pxref{Registers,,, gdb, The GNU debugger}). Press @key{RET} or -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}. With earlier versions of GDB, you can -press @key{SPC} to toggle the display of floating point registers -(@code{toggle-gdb-all-registers}). +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}. @item Assembler Buffer The assembler buffer displays the current frame as machine code. An @@ -1166,8 +1134,8 @@ size for these data items. @end table When @code{gdb-many-windows} is non-@code{nil}, the locals buffer -shares its window with the registers buffer, just like breakpoints -and threads buffers. To switch from one to the other click with +shares its window with the registers buffer, just like breakpoints and +threads buffers. To switch from one to the other, click with @kbd{Mouse-1} on the relevant button in the header line. @node Watch Expressions @@ -1182,14 +1150,15 @@ 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. - Each watch expression is displayed in the 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. + 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. 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 @@ -1237,51 +1206,43 @@ non-@code{nil}. This can be useful if you are debugging with a full screen Emacs frame. @node Multithreaded Debugging -@subsubsection Stopping and Starting Multi-threaded Programs +@subsubsection Multithreaded Debugging @cindex Multithreaded debugging in GDB - -@subsubheading All-stop Debugging - -In all-stop mode, whenever your program stops, @emph{all} threads of -execution stop. Likewise, whenever you restart the program, all -threads start executing. @xref{All-Stop Mode, , All-Stop Mode, gdb, -The GNU debugger}. You can enable this behavior in Emacs by setting -@code{gdb-non-stop-setting} to @code{nil} before starting a debugging -session. - -@subsubheading Non-stop Debugging @cindex Non-stop debugging in GDB -For some multi-threaded targets, GDB supports a further mode of -operation 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}. -This is referred to as @dfn{non-stop} mode. - -Versions of GDB prior to 7.0 do not support non-stop mode and it does -not work on all targets. In such cases, Emacs uses all-stop mode -regardless of the value of @code{gdb-non-stop-setting}. + 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. @vindex gdb-non-stop-setting -If the variable @code{gdb-non-stop-setting} is non-@code{nil} (the -default value), Emacs tries to start GDB in non-stop mode. Note that -GDB debugging session needs to be restarted for change of this setting -to take effect. + 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. @vindex gdb-switch-when-another-stopped -When a thread stops in non-stop mode, Emacs automatically switches to -that thread. It may be undesirable to allow switching of current -thread when some other stopped thread is already selected. Set -@code{gdb-switch-when-another-stopped} to @code{nil} to prevent this. + 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}. @vindex gdb-switch-reasons -Emacs can decide whether or not to switch to the stopped thread -depending on the reason which caused the stop. Customize -@code{gdb-switch-reasons} to select stop reasons which make Emacs -switch thread. + 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. @vindex gdb-stopped-hooks -The variable @code{gdb-stopped-hooks} allows you to execute your + The variable @code{gdb-stopped-hooks} allows you to execute your functions whenever some thread stops. In non-stop mode, you can switch between different modes for GUD @@ -1291,7 +1252,7 @@ execution control commands. @table @dfn @item Non-stop/A -When @code{gdb-gud-control-all-threads} is @code{t} (the default + When @code{gdb-gud-control-all-threads} is @code{t} (the default 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 @@ -1312,18 +1273,13 @@ from the tool bar or from @samp{GUD->GDB-MI} menu. Stepping commands always apply to the current thread. -@subsubheading Fine Thread Control - 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. -Combined with creating bound buffers for any thread, this allows you -to change and track state of many threads in the same time. - - Note that when you interrupt a thread, it stops with @samp{signal -received} reason. If that reason is included in your + Note that when you interrupt a thread, it stops with the +@samp{signal received} reason. If that reason is included in your @code{gdb-switch-reasons} (it is by default), Emacs will switch to that thread. diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index 5336384c3b9..8ecf0982e46 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -722,8 +722,7 @@ GDB Graphical Interface * Breakpoints Buffer:: A breakpoint control panel. * Threads Buffer:: Displays your threads. * Stack Buffer:: Select a frame from the call stack. -* Other GDB Buffers:: Input/output, locals, registers, - assembler, threads and memory buffers. +* Other GDB Buffers:: Other buffers for controlling the GDB state. * Watch Expressions:: Monitor variable values in the speedbar. * Multithreaded Debugging:: Debugging programs with several threads. -- 2.39.2