[patch to 20.7] enhancement to gud.el: add GDB `jump' feature

[Benjamin Rutt]

This bug report will be sent to the Free Software Foundation,
 not to your local site managers!!
Please write in English, because the Emacs maintainers do not have
translators to read other languages for them.

In GNU Emacs 20.7.1 (i386-redhat-linux-gnu, X toolkit)
 of Tue Jun 13 2000 on porky.devel.redhat.com
configured using `configure  --mandir=/usr/man --infodir=/usr/info 
--prefix=/usr --libexecdir=/usr/lib --sharedstatedir=/var --with-gcc --with-pop 
--with-x-toolkit i386-redhat-linux-gnu'

Please describe exactly what actions triggered the bug
and the precise symptoms of the bug:

This patch to emacs 20.7 adds an ability to easily change (relocate)
the current execution line (denoted by the => arrow) under GDB.

Motivation:

Let's say you have a function foo in a C program, which is returning a
nonzero error code somewhere inside it, but you don't know where, and
you need to find out.  You'd like to know where (inside which function
call) it's receiving the error, and then jump back and step into that
function.

Let's take a really simple example, with only 2 function calls that
could be the failing ones.

e.g. in a file called foo.c

0  int foo()
1  {
2    int err_code;
3
4    err_code = bar();
5    if ( err_code)
6      return err_code;
7
8    err_code = baz();
9    if ( err_code)
10     return err_code;
11
12   return 0;
13 }

One approach would be to set breakpoints at lines 6 and 10, waiting
for the bad error code to be generated.  Then, if only you could step
back up to lines 4 or 8, respectively, and step into bar() or baz()
and run them again.

Well, this type of relocation of the next execution line is possible
with GDB, if you use the `tbreak' command followed by the `jump'
command (see the GDB manual entry regarding `jump' for details).  But
that's a lengthy operation to type manually into the GUD interaction
buffer (it's two functions, and it requires that you know the file and
line number you want to go to).  Wouldn't it be great if emacs could
make it easier?  Well, it can, with the attached patches, which I hope
will be considered for inclusion.

Let's say you hit your breakpoint at line 6 and wanted to jump back to
line 4 and then step into bar().  Simply put point at line 4 above,
and run M-x gud-jump (or type C-x C-a C-j).  This will cause "tbreak
foo.c:4\njump foo.c:4" to be sent to GDB, and the => arrow will go to
line 4, at which point you can step inside bar() and figure out what
went wrong one level deeper.  If you run C-c C-j from the GUD
interaction buffer, nothing special happens since you will jump to the
point in the current source buffer where the => is (in effect, a
no-op).  As a result, this function is only useful in a source buffer
via C-x C-a C-j.

Note: I implemented the `gud-jump' function only for M-x gdb, and
wrote the manual entry under a section for "GDB only" commands.  There
are 2 reasons why I didn't implement gud-jump for the other debuggers
(dbx, xdb, etc.): 1) I don't know if similar features are available on
those other debuggers, and 2) I don't have access to systems
containing those debuggers.  Reason #1 is also why I did not create a
menu item for `gud-jump': as far as I could tell from gud.el, menu
items are used for functions used across more than 1 debugger.  If
anyone can correct me on this point, I will add the menu item for
`gud-jump'.

4 files are patched:  

./lisp/gud.el
./lisp/ChangeLog
./man/building.texi
./man/ChangeLog

Here begins the patches:

*** lisp/gud.el.orig    Fri Jul 27 00:23:45 2001
--- lisp/gud.el Fri Jul 27 16:15:22 2001
***************
*** 376,381 ****
--- 376,382 ----
    (gud-def gud-up     "up %p"        "<" "Up N stack frames (numeric arg).")
    (gud-def gud-down   "down %p"      ">" "Down N stack frames (numeric arg).")
    (gud-def gud-print  "print %e"     "\C-p" "Evaluate C expression at point.")
+   (gud-def gud-jump   "tbreak %f:%l\njump %f:%l" "\C-j" "Relocate next 
instruction to line at point in source buffer.")
  
    (local-set-key "\C-i" 'gud-gdb-complete-command)
    (local-set-key [menu-bar debug tbreak] '("Temporary Breakpoint" . 
gud-tbreak))


*** lisp/ChangeLog.orig Fri Jul 27 15:47:10 2001
--- lisp/ChangeLog      Fri Jul 27 16:57:38 2001
***************
*** 1,3 ****
--- 1,7 ----
+ 2001-07-27  Benjamin Rutt  <brutt@bloomington.in.us>
+ 
+       * gud.el (gud-jump): New gud-def inside gdb defun.
+ 
  2000-06-13  Gerd Moellmann  <gerd@gnu.org>
  
        * Version 20.7 released.


*** man/building.texi.orig      Fri Jul 27 12:28:13 2001
--- man/building.texi   Fri Jul 27 16:31:12 2001
***************
*** 456,461 ****
--- 456,471 ----
  @findex gud-finish
  Run the program until the selected stack frame returns (or until it
  stops for some other reason).
+ 
+ @item C-c C-j
+ @kindex C-c C-j @r{(GUD)}
+ @itemx C-x C-a C-j
+ @findex gud-jump
+ Relocate (@code{gud-jump}) the execution line to the current line at
+ point in a source buffer (if the new execution line is in a different
+ function from the previously one, you will be prompted for confirmation
+ since the results may be bizzare.  See the GDB manual entry regarding
+ `jump' for details).  This is only useful in a source buffer.
  @end table
  
    These commands interpret a numeric argument as a repeat count, when


*** man/ChangeLog.orig  Fri Jul 27 15:46:53 2001
--- man/ChangeLog       Fri Jul 27 15:46:24 2001
***************
*** 1,3 ****
--- 1,7 ----
+ 2001-07-27  Benjamin Rutt  <brutt@bloomington.in.us>
+ 
+       * building.texi (Commands of GUD): Add description of `gud-jump'.
+ 
  2000-06-13  Gerd Moellmann  <gerd@gnu.org>
  
        * Version 20.7 released.



Recent input:
M-x g n u s return M-x r e p o r t - e m a c s - b 
u g return

Recent messages:
Checking new news...
Opening nntp server on news.gnus.org...

Opening nndraft server...

Checking new news...done
Loading gnus-topic...
Loading gnus-topic...done
Loading emacsbug...
Loading emacsbug...done

-- 
Benjamin Rutt <brutt@bloomington.in.us>