mirror/binutils-gdb
2
0
Fork 0
mirror of https://sourceware.org/git/binutils-gdb.git synced 2024-11-27 03:51:15 +08:00
Code Issues Packages Projects Releases Wiki Activity

* gdb.texinfo (Separate Debug Files): Included a BUILD ID description.

Browse Source 
Enlisted BUILD ID to the debug file searching example.
	Included a BUILD ID `.note.gnu.build-id' section description.
	Updated/added the debug files splitting instructions for OBJCOPY.
This commit is contained in:
Jan Kratochvil 2007-09-01 08:17:13 +00:00
parent 4935890f4d
commit d3750b24f6
2 changed files with 64 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
gdb/doc/ChangeLog
View File

@ -1,3 +1,10 @@
2007-09-01 Jan Kratochvil <jan.kratochvil@redhat.com>
* gdb.texinfo (Separate Debug Files): Included a BUILD ID description.
Enlisted BUILD ID to the debug file searching example.
Included a BUILD ID `.note.gnu.build-id' section description.
Updated/added the debug files splitting instructions for OBJCOPY.
2007-08-31 Vladimir Prus <vladimir@codesourcery.com>
* gdb.texinfo (Variable Objects): Adjust docs

85
gdb/doc/gdb.texinfo
View File

@ -11902,18 +11902,32 @@ than the executable code itself --- some systems distribute debugging
information for their executables in separate files, which users can
install only when they need to debug a problem.
If an executable's debugging information has been extracted to a
separate file, the executable should contain a @dfn{debug link} giving
the name of the debugging information file (with no directory
components), and a checksum of its contents. (The exact form of a
debug link is described below.) If the full name of the directory
containing the executable is @var{execdir}, and the executable has a
debug link that specifies the name @var{debugfile}, then @value{GDBN}
will automatically search for the debugging information file in three
places:
There are two identificators how the separate debug file may be found:
@itemize @bullet
@item
@dfn{debug link} is present only in the executable if its debug information has
been split out. It is not present in the separate debug file. It provides the
separate debug file filename, usually as @file{executable.debug}.
@item
@dfn{build id} is present in all the files (if the operating system supports
it). The executable file and its separate debug file have the same unique
@dfn{build id} content.
@end itemize
If the full name of the directory containing the executable is @var{execdir},
the executable has a debug link that specifies the name @var{debugfile},
@var{bu} is the first byte (two hexadecimal characters) of the build id
content, @var{ild-id} are the remaining bytes / hexadecimal characters and
@var{globaldebugdir} is the global debug file directory then @value{GDBN} will
automatically search for the debugging information file in four places:
@itemize @bullet
@item
a specific file in the subdirectory of the global debug file directory
according to the @dfn{build id} content (if present), the file tried is
@file{@var{globaldebugdir}/.debug-id/@var{bu}/@var{ild-id}.debug}.
@item
the directory containing the executable file (that is, it will look
for a file named @file{@var{execdir}/@var{debugfile}},
@item
@ -11928,15 +11942,17 @@ executable's full path, and the name from the link (that is, the file
@end itemize
@noindent
@value{GDBN} checks under each of these names for a debugging
information file whose checksum matches that given in the link, and
reads the debugging information from the first one it finds.
information file with build id content matching the build id content of the
executable file - or - whose checksum matches the one given in the link in the
debug link case. In each case @value{GDBN} reads the debugging information
from the first debug file it finds.
So, for example, if you ask @value{GDBN} to debug @file{/usr/bin/ls},
which has a link containing the name @file{ls.debug}, and the global
debug directory is @file{/usr/lib/debug}, then @value{GDBN} will look
for debug information in @file{/usr/bin/ls.debug},
@file{/usr/bin/.debug/ls.debug}, and
@file{/usr/lib/debug/usr/bin/ls.debug}.
So, for example, if you ask @value{GDBN} to debug @file{/usr/bin/ls}, which has
a @dfn{debug link} containing the name @file{ls.debug}, its @dfn{build id}
value in hexadecimal is @code{abcdef} and the global debug directory is
@file{/usr/lib/debug}, then @value{GDBN} will look for debug information in
@file{/usr/lib/debug/.build-id/ab/cdef.debug}, @file{/usr/bin/ls.debug},
@file{/usr/bin/.debug/ls.debug}, and @file{/usr/lib/debug/usr/bin/ls.debug}.
You can set the global debugging info directory's name, and view the
name @value{GDBN} is currently using.
@ -11978,6 +11994,16 @@ 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.
@cindex @code{.note.gnu.build-id} sections
@cindex build id
Build id is a special section of the executable file named
@code{.note.gnu.build-id}. The section contains unique identification hash
derived from the built files - it remains the same across multiple builds of
the same build tree. The default algorithm SHA1 produces 160 bits (40
hexadecimal characters) of the content. The same section and value is present
in the original built binary with symbols, in its stripped variant and in the
separate debug information file.
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
@ -11985,18 +12011,21 @@ 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}.
@sc{gnu} binary utilities contain the @samp{objcopy} utility able to produce
the separated executable / debugging information file pairs by commands
@kbd{objcopy --only-keep-debug foo foo.debug; strip -g foo; objcopy
--add-gnu-debuglink="foo.debug" "foo"}. These commands remove the debugging
information from the executable file @file{foo}, place it in the file
@file{foo.debug}, and leave behind a debug link in @file{foo}. 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} has the same functionality as the three commands above.
Since there are many different ways to compute CRC's (different
polynomials, reversals, byte ordering, etc.), the simplest way to
describe the CRC used in @code{.gnu_debuglink} sections is to give the
complete code for a function that computes it:
Since there are many different ways to compute CRC's for the debug link
(different polynomials, reversals, byte ordering, etc.). This computation does
not apply to the build id section. The simplest way to describe the CRC used
in @code{.gnu_debuglink} sections is to give the complete code for a function
that computes it:
@kindex gnu_debuglink_crc32
@smallexample