Re: Starting multiple GUD session; doc problem

[Stephen Leake]

Nick Roberts <address@hidden> writes:

> Stephen Leake writes:
>  > I just tried to start two gdb sessions in one CVS Emacs session for
>  > the first time (I've done this many times in Emacs 21). I got the
>  > error message:
>  > 
>  >  "gdb: Multiple debugging is only supported with "gdb --fullname"
>  > 
>  > So I dutifully added "--fullname" to the gdb command line:
>  >
>  >     gdb --annotate=3 --fullname gds-main_models_test.exe 
>
> Well, I'm not sure that's dutiful, it means start with "gdb --fullname"
> _instead of_ "gdb --annotate=3" but if other's find it ambiguous too
> I'll change it.

Since the info manual never mentions "--annotate=3", I thought it was
always necessary. So yes, I found it ambiguous.

>  > It seems the real issue is the presence or absence of "--annotate=3",
>  > not the presence of "--fullname". In fact, "--fullname" is not
>  > necessary if compilation-search-path is set to include the source
>  > directories.
>
> That's not true.  If "--annotate=3" is not used the option "--fullname" is
> necessary for the Emacs to display the current line in the source
> buffer.

"--fullname" provides path information for source files. Apparently
"--annotate=3" also provides that, but in a different way. 

But I run "gdb" without "--fullname" all the time in Emacs 21. I
thought that meant gud was searching the directory path in
compilation-search-path. 

However, testing on Emacs 22, I see the --fullname is required now.

> The current doc string goes on to explain what how this function
> lays out the buffers. To the first time user what would GUI mode
> mean?

Good point. On the other hand, the first sentence in 32.6.5 mentions a
"graphical interface"; so that would be a good place to define "GUI
mode".

> The other changes are wrong because "--fullname" is needed. Perhaps
> some confusion arises over the term "text command mode". It refers
> to the way that it works in Emacs 21: GUD buffer + source buffer.

Right, I did understand that. "gdb --fullname" works the same in Emacs
22 as "gdb" in Emacs 21, and that is the behavior I was expecting. In
particular, I don't have to do anything special to get two debugging
sessions.

At the same time, if you don't customize 'gdb-many-windows', "gdb
--annotate=3" in Emacs 22 also works the same as "gdb" in Emacs 21,
except that it doesn't allow multiple debugging sessions. So that's
why I was surprised by this.

GUI mode (with 'gdb-many-windows' t) adds a fancy display (which I
find annoying; I prefer my screen real estate to show actual code :).
It also adds tooltips for viewing variables, which is very nice.

(aside; I don't understand why the tooltips are not available in "text
command mode". Is "--annotate" required to get tooltip variable values?)

> Perhaps it would help to refer to "text command mode" in the section
> "Debugger Operation" (it currently says "using the textual
> interface").

Yes, that would help.

Hmm. The first paragraph there says the program input and output is
via the GUD buffer, in text command mode. However, it doesn't say
where they are in GUI mode; are there separate buffers for that? Hmm.
I just tried it, and the answer seems to be "no"; stdin and stdout are
still mixed in the GUD buffer in GUI mode. Perhaps there is another
variable to customize? I'm running GNU gdb 5.3 for GNAT Pro 5.04a
(20060125), compiling Ada code.

So the discussion of debugger input/output and program input/output is
correct whether in GUI mode or text command mode.

If it was totally up to me, I'd make "M-x gdb" in Emacs 22 do "gdb
--fullname" by default, since that is closest to the Emacs 21 behavior
(it allows multiple debugging sessions). To get the GUI mode, you
would do "M-x gdba". (And that's how I've customized things in my
.emacs).

That means people would have to read the manual to know about the GUI
mode. But that is the case now anyway; you have to set
'gdb-many-windows' to get the GUI mode multiple windows display when
starting with "M-x gdb", and you have to read the manual to know that.
You also have to read the manual to know about the additional mouse
bindings. 

I've attached an updated patch.

Index: lisp/progmodes/gdb-ui.el
===================================================================
RCS file: /sources/emacs/emacs/lisp/progmodes/gdb-ui.el,v
retrieving revision 1.191
diff -c -r1.191 gdb-ui.el
*** lisp/progmodes/gdb-ui.el    10 Nov 2006 09:38:11 -0000      1.191
--- lisp/progmodes/gdb-ui.el    25 Nov 2006 13:19:16 -0000
***************
*** 214,220 ****
  
  ;;;###autoload
  (defun gdba (command-line)
!   "Run gdb on program FILE in buffer *gud-FILE*.
  The directory containing FILE becomes the initial working directory
  and source-file directory for your debugger.
  
--- 214,220 ----
  
  ;;;###autoload
  (defun gdba (command-line)
!   "Run gdb in GUI mode on program FILE in buffer *gud-FILE*.
  The directory containing FILE becomes the initial working directory
  and source-file directory for your debugger.
  
Index: lisp/progmodes/gud.el
===================================================================
RCS file: /sources/emacs/emacs/lisp/progmodes/gud.el,v
retrieving revision 1.116
diff -c -r1.116 gud.el
*** lisp/progmodes/gud.el       5 Sep 2006 03:40:54 -0000       1.116
--- lisp/progmodes/gud.el       25 Nov 2006 13:19:19 -0000
***************
*** 680,687 ****
  default this command starts GDB using a graphical interface.  See
  `gdba' for more information.
  
! To run GDB in text command mode, set `gud-gdb-command-name' to
! \"gdb --fullname\" and include the pathname, if necessary."
    (interactive (list (gud-query-cmdline 'gdb)))
  
    (if (and gud-comint-buffer
--- 680,687 ----
  default this command starts GDB using a graphical interface.  See
  `gdba' for more information.
  
! To run GDB in text command mode, delete \"--annotate=3\" from
! `gud-gdb-command-name', and add \"--fullname\"."
    (interactive (list (gud-query-cmdline 'gdb)))
  
    (if (and gud-comint-buffer
Index: man/building.texi
===================================================================
RCS file: /sources/emacs/emacs/man/building.texi,v
retrieving revision 1.109
diff -c -r1.109 building.texi
*** man/building.texi   7 Oct 2006 23:38:51 -0000       1.109
--- man/building.texi   25 Nov 2006 13:19:21 -0000
***************
*** 536,545 ****
  @subsection Debugger Operation
  
  @cindex fringes, and current execution line in GUD
!   When you run a debugger with GUD using the textual interface, 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.
  
    The debugger displays the source files of the program by visiting
  them in Emacs buffers.  An arrow in the left fringe indicates the
--- 536,545 ----
  @subsection Debugger Operation
  
  @cindex fringes, and current execution line in GUD
!   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.
  
    The debugger displays the source files of the program by visiting
  them in Emacs buffers.  An arrow in the left fringe indicates the
***************
*** 815,838 ****
  
    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.
! 
!   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
  @findex gdba
!   You can also run GDB in text command mode, like other debuggers.  To
! do this, set @code{gud-gdb-command-name} to @code{"gdb --fullname"} or
! edit the startup command in the minibuffer to say that.  You need to
! do use text command mode to run multiple debugging sessions within one
! Emacs session.  If you have customized @code{gud-gdb-command-name} in
! that way, you can use @kbd{M-x gdba} to invoke GDB in graphical mode.
  
  @menu
  * GDB-UI Layout::               Control the number of displayed buffers.
--- 815,856 ----
  
    By default, the command @code{gdb} starts GDB using a graphical
  interface, using Emacs windows for display program state information.
! This is called ``GUI mode''. 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.
! 
!   To display the program state information windows, you must set the
! variable @code{gdb-many-windows} to address@hidden Or you can use the
! command @code{gdba} to start the debugger.
! 
!   You can also run GDB without the program state information windows;
! this also disables many of the mouse bindings that interact with the
! debugger. This is called ``text command mode''. 
! 
!   You need to use text mode for the first and subsequent debugging
! sessions if you plan to run multiple debugging sessions within one
! Emacs session.
  
  @vindex gud-gdb-command-name
  @findex gdba
!   Emacs automatically switches to GUI mode if it sees annotations in
! the gdb output. GDB generates annotations when started with the
! command line option @code{"--annotate=3"}, which is set by default in
! @code{gud-gdb-command-name}. To run in text mode, you must customize
! @code{gud-gdb-command-name} to delete this option, and specify
! @code{"--fullname"} instead. Or you can make this change in the
! startup command in the minibuffer.
! 
! If you have customized @code{gud-gdb-command-name} in that way, you
! can use @code{gdba} to invoke GDB in graphical mode; it uses the
! default command @code{gud-gdba-command-name}.
! 
!   GUI 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.
  
  @menu
  * GDB-UI Layout::               Control the number of displayed buffers.

-- 
-- Stephe