RFA: document binutils support for separate debug info

RFA: document binutils support for separate debug info

[Jim Blandy]

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 ----

Re: RFA: document binutils support for separate debug info

[Eli Zaretskii]

> From: Jim Blandy <jimb@redhat.com>
> Date: 25 Jun 2003 12:35:00 -0500
> 
> 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.

Approved.  Thanks.

Re: RFA: document binutils support for separate debug info

[Elena Zannoni]

Eli Zaretskii writes:
 > > From: Jim Blandy <jimb@redhat.com>
 > > Date: 25 Jun 2003 12:35:00 -0500
 > > 
 > > 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.
 > 
 > Approved.  Thanks.


Wait a second. I am fixing gdb bugs ATM with that code.
I think let's hold the doco until it works completely.

elena

Re: RFA: document binutils support for separate debug info

[Jim Blandy]

Elena Zannoni <ezannoni@redhat.com> writes:

> Eli Zaretskii writes:
>  > > From: Jim Blandy <jimb@redhat.com>
>  > > Date: 25 Jun 2003 12:35:00 -0500
>  > > 
>  > > 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.
>  > 
>  > Approved.  Thanks.
> 
> 
> Wait a second. I am fixing gdb bugs ATM with that code.
> I think let's hold the doco until it works completely.

Yes, Nick just told me that things are in flux, too.  I tried things
out and what I tried worked (I didn't fake the example!) but I'm happy
to wait and see how things settle out.

Do you have the Dejagnu magic to run the entire test suite with
separate debug info?  I keep wanting to integrate it into
testsuite/lib/gdb.exp so one can get it just by adding magic to one's
target_list, but I don't get around to it.

Re: RFA: document binutils support for separate debug info

[Andrew Cagney]

> Elena Zannoni <ezannoni@redhat.com> writes:
> 
> 
>> Eli Zaretskii writes:
>>  > > From: Jim Blandy <jimb@redhat.com>
>>  > > Date: 25 Jun 2003 12:35:00 -0500
>>  > > 
>>  > > 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.
>>  > 
>>  > Approved.  Thanks.
>> 
>> 
>> Wait a second. I am fixing gdb bugs ATM with that code.
>> I think let's hold the doco until it works completely.
> 
> 
> Yes, Nick just told me that things are in flux, too.  I tried things
> out and what I tried worked (I didn't fake the example!) but I'm happy
> to wait and see how things settle out.
> 
> Do you have the Dejagnu magic to run the entire test suite with
> separate debug info?  I keep wanting to integrate it into
> testsuite/lib/gdb.exp so one can get it just by adding magic to one's
> target_list, but I don't get around to it.

There really needs to be a unit test for this feature.  That way people 
will know it works, even when their system isn't set up to use it.

Andrew

Re: RFA: document binutils support for separate debug info

[Eli Zaretskii]

> From: Jim Blandy <jimb@redhat.com>
> Date: 27 Jun 2003 01:39:44 -0500
> 
> I'm happy to wait and see how things settle out.

So am I.