* 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.
This commit is contained in:
Jan Kratochvil
parent
4935890f4d
commit
d3750b24f6
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue