RFA: document binutils support for separate debug info

[Jim Blandy <jimb at redhat dot com>]

2003-06-25  Jim Blandy  <jimb@redhat.com>

	* gdb.texinfo (Separate Debug Files): Update documentation to
	describe GNU Binutils' support for separate debug info files.

Index: gdb/doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.168
diff -c -r1.168 gdb.texinfo
*** gdb/doc/gdb.texinfo	24 Jun 2003 21:59:36 -0000	1.168
--- gdb/doc/gdb.texinfo	25 Jun 2003 17:31:18 -0000
***************
*** 10036,10041 ****
--- 10036,10094 ----
  
  @end table
  
+ The debugging information file itself should be an ordinary
+ executable, containing a full set of linker symbols, sections, and
+ debugging information.  The sections of the debugging information file
+ should have the same names, addresses and sizes as the original file,
+ but they need not contain any data --- much like a @code{.bss} section
+ in an ordinary executable.
+ 
+ @cindex @code{objdump}
+ @cindex @code{--add-gnu-debuglink}
+ @cindex @code{strip}
+ The GNU Binutils (@pxref{top,, The GNU Binary Utilities, binutils, The
+ GNU Binary Utilities}) can add debug links to executables, beginning
+ with version 2.14.  If your executable is named @file{frob}, here are
+ the steps to take:
+ @enumerate
+ 
+ @item
+ Save a copy of the original executable file, with full debugging
+ information, to act as your debugging information file.
+ 
+ @item 
+ Use the Binutils' @code{strip} command to remove all debugging
+ information from the executable file you will install.
+ 
+ @item
+ Use the @code{--add-gnu-debuglink} flag of the Binutils'
+ @code{objcopy} command to add a debug link to the stripped executable.
+ 
+ @end enumerate
+ 
+ For example, here's how one would create a separate debug info file
+ for an executable named @file{hello}:
+ @example
+ $ ./hello
+ Hello, world!
+ $ cp hello hello.debug
+ $ strip hello
+ $ objcopy --add-gnu-debuglink=hello.debug hello
+ $ file hello
+ hello: ELF 32-bit LSB executable, @dots{} stripped
+ $ gdb hello
+ GNU gdb 2003-04-17-cvs
+ Copyright 2003 Free Software Foundation, Inc.
+ GDB is free software, @dots{}
+ (gdb) break main
+ Breakpoint 1 at 0x8048334: file hello.c, line 5.
+ (gdb)
+ @end example
+ @noindent
+ As the example shows, the executable file @file{hello} is stripped,
+ but @value{GDBN} can still find the information it needs to set a
+ breakpoint on a function, and report the breakpoint's source location.
+ 
  @cindex @code{.gnu_debuglink} sections
  @cindex debug links
  A debug link is a special section of the executable file named
***************
*** 10058,10078 ****
  Any executable file format can carry a debug link, as long as it can
  contain a section named @code{.gnu_debuglink} with the contents
  described above.
- 
- The debugging information file itself should be an ordinary
- executable, containing a full set of linker symbols, sections, and
- debugging information.  The sections of the debugging information file
- should have the same names, addresses and sizes as the original file,
- but they need not contain any data --- much like a @code{.bss} section
- in an ordinary executable.
- 
- As of December 2002, there is no standard GNU utility to produce
- separated executable / debugging information file pairs.  Ulrich
- Drepper's @file{elfutils} package, starting with version 0.53,
- contains a version of the @code{strip} command such that the command
- @kbd{strip foo -f foo.debug} removes the debugging information from
- the executable file @file{foo}, places it in the file
- @file{foo.debug}, and leaves behind a debug link in @file{foo}.
  
  Since there are many different ways to compute CRC's (different
  polynomials, reversals, byte ordering, etc.), the simplest way to
--- 10111,10116 ----