darkkirb/old-cross-binutils
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

* gdb.texinfo (Separate Debug Files): Fix last change. Add

Browse source 
indexing for ``build ID'' support.
This commit is contained in:
Eli Zaretskii 2007-09-01 10:28:25 +00:00
parent 77069918ac
commit c7e83d54a2
2 changed files with 93 additions and 63 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
gdb/doc/ChangeLog
View file

@ -1,3 +1,8 @@
2007-09-01 Eli Zaretskii <eliz@gnu.org>
* gdb.texinfo (Separate Debug Files): Fix last change. Add
indexing for ``build ID'' support.
2007-09-01 Jan Kratochvil <jan.kratochvil@redhat.com> 2007-09-01 Jan Kratochvil <jan.kratochvil@redhat.com>
* gdb.texinfo (Separate Debug Files): Included a BUILD ID description. * gdb.texinfo (Separate Debug Files): Included a BUILD ID description.

151
gdb/doc/gdb.texinfo
View file

@ -11893,66 +11893,79 @@ Display the current shared library search path.
@cindex @file{.debug} subdirectories @cindex @file{.debug} subdirectories
@cindex debugging information directory, global @cindex debugging information directory, global
@cindex global debugging information directory @cindex global debugging information directory
@cindex build ID, and separate debugging files
@cindex @file{.build-id} directory
@value{GDBN} allows you to put a program's debugging information in a @value{GDBN} allows you to put a program's debugging information in a
file separate from the executable itself, in a way that allows file separate from the executable itself, in a way that allows
@value{GDBN} to find and load the debugging information automatically. @value{GDBN} to find and load the debugging information automatically.
Since debugging information can be very large --- sometimes larger Since debugging information can be very large---sometimes larger
than the executable code itself --- some systems distribute debugging than the executable code itself---some systems distribute debugging
information for their executables in separate files, which users can information for their executables in separate files, which users can
install only when they need to debug a problem. install only when they need to debug a problem.
There are two identificators how the separate debug file may be found: @value{GDBN} supports two ways of specifying the separate debug info
file:
@itemize @bullet @itemize @bullet
@item @item
@dfn{debug link} is present only in the executable if its debug information has The executable contains a @dfn{debug link} that specifies the name of
been split out. It is not present in the separate debug file. It provides the the separate debug info file. The separate debug file's name is
separate debug file filename, usually as @file{executable.debug}. usually @file{@var{executable}.debug}, where @var{executable} is the
name of the corresponding executable file without leading directories
(e.g., @file{ls.debug} for @file{/usr/bin/ls}). In addition, the
debug link specifies a CRC32 checksum for the debug file, which
@value{GDBN} uses to validate that the executable and the debug file
came from the same build.
@item @item
@dfn{build id} is present in all the files (if the operating system supports The executable contains a @dfn{build ID}, a unique signature that is
it). The executable file and its separate debug file have the same unique also present in the corresponding debug info file. (This is supported
@dfn{build id} content. only on some operating systems, notably on @sc{gnu}/Linux. For more
details about this feature, see
@uref{http://fedoraproject.org/wiki/Releases/FeatureBuildId, the
Fedora Project's description of the buid ID feature}.) The debug info
file's name is not specified explicitly by the debug ID, but can be
computed from the build ID, see below.
@end itemize @end itemize
If the full name of the directory containing the executable is @var{execdir}, Depending on the way the debug info file is specified, @value{GDBN}
the executable has a debug link that specifies the name @var{debugfile}, uses two different methods of looking for the debug file:
@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 @itemize @bullet
@item @item
a specific file in the subdirectory of the global debug file directory For the ``debug link'' method, @value{GDBN} looks up the named file in
according to the @dfn{build id} content (if present), the file tried is the directory of the executable file, then in a subdirectory of that
@file{@var{globaldebugdir}/.debug-id/@var{bu}/@var{ild-id}.debug}. directory named @file{.debug}, and finally under the global debug
@item directory, in a subdirectory whose name is identical to the leading
the directory containing the executable file (that is, it will look directories of the executable's absolute file name.
for a file named @file{@var{execdir}/@var{debugfile}},
@item
a subdirectory of that directory named @file{.debug} (that is, the
file @file{@var{execdir}/.debug/@var{debugfile}}, and
@item
a subdirectory of the global debug file directory that includes the
executable's full path, and the name from the link (that is, the file
@file{@var{globaldebugdir}/@var{execdir}/@var{debugfile}}, where
@var{globaldebugdir} is the global debug file directory, and
@var{execdir} has been turned into a relative path).
@end itemize
@noindent
@value{GDBN} checks under each of these names for a debugging
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 @item
a @dfn{debug link} containing the name @file{ls.debug}, its @dfn{build id} For the ``debug ID'' method, @value{GDBN} looks in the
value in hexadecimal is @code{abcdef} and the global debug directory is @file{.build-id} subdirectory of the global debug directory for a file
@file{/usr/lib/debug}, then @value{GDBN} will look for debug information in named @file{@var{nn}/@var{nnnnnnnn}.debug}, where @var{nn} are the
@file{/usr/lib/debug/.build-id/ab/cdef.debug}, @file{/usr/bin/ls.debug}, first 2 hex characters of the debug ID signature, and @var{nnnnnnnn}
@file{/usr/bin/.debug/ls.debug}, and @file{/usr/lib/debug/usr/bin/ls.debug}. are the rest of the signature. (Real signatures are 32 or more
characters, not 10.)
@end itemize
So, for example, suppose you ask @value{GDBN} to debug
@file{/usr/bin/ls}, which has a @dfn{debug link} that specifies the
file @file{ls.debug}, and a @dfn{build id} whose value in hex is
@code{abcdef1234}. If the global debug directory is
@file{/usr/lib/debug}, then @value{GDBN} will look for the following
debug information files, in the indicated order:
@itemize @minus
@item
@file{/usr/lib/debug/.build-id/ab/cdef1234.debug}
@item
@file{/usr/bin/ls.debug}
@item
@file{/usr/bin/.debug/ls.debug}
@item
@file{/usr/lib/debug/usr/bin/ls.debug}.
@end itemize
You can set the global debugging info directory's name, and view the You can set the global debugging info directory's name, and view the
name @value{GDBN} is currently using. name @value{GDBN} is currently using.
@ -11972,7 +11985,7 @@ information files.
@end table @end table
@cindex @code{.gnu_debuglink} sections @cindex @code{.gnu_debuglink} sections
@cindex debug links @cindex debug link sections
A debug link is a special section of the executable file named A debug link is a special section of the executable file named
@code{.gnu_debuglink}. The section must contain: @code{.gnu_debuglink}. The section must contain:
@ -11995,37 +12008,46 @@ contain a section named @code{.gnu_debuglink} with the contents
described above. described above.
@cindex @code{.note.gnu.build-id} sections @cindex @code{.note.gnu.build-id} sections
@cindex build id @cindex build ID sections
Build id is a special section of the executable file named A build ID is a special section of the executable file named
@code{.note.gnu.build-id}. The section contains unique identification hash @code{.note.gnu.build-id}. This section contains unique
derived from the built files - it remains the same across multiple builds of identification for the built files---it remains the same across
the same build tree. The default algorithm SHA1 produces 160 bits (40 multiple builds of the same build tree. The default algorithm SHA1
hexadecimal characters) of the content. The same section and value is present produces 160 bits (40 hexadecimal characters) of the content. The
in the original built binary with symbols, in its stripped variant and in the same section with an identical value is present in the original built
separate debug information file. binary with symbols, in its stripped variant, and in the separate
debugging information file.
The debugging information file itself should be an ordinary The debugging information file itself should be an ordinary
executable, containing a full set of linker symbols, sections, and executable, containing a full set of linker symbols, sections, and
debugging information. The sections of the debugging information file debugging information. The sections of the debugging information file
should have the same names, addresses and sizes as the original 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 but they need not contain any data---much like a @code{.bss} section
in an ordinary executable. in an ordinary executable.
@sc{gnu} binary utilities contain the @samp{objcopy} utility able to produce @sc{gnu} binary utilities (Binutils) package includes the
the separated executable / debugging information file pairs by commands @samp{objcopy} utility that can produce
@kbd{objcopy --only-keep-debug foo foo.debug; strip -g foo; objcopy the separated executable / debugging information file pairs using the
--add-gnu-debuglink="foo.debug" "foo"}. These commands remove the debugging following commands:
@smallexample
@kbd{objcopy --only-keep-debug foo foo.debug}
@kbd{strip -g foo}
@kbd{objcopy --add-gnu-debuglink="foo.debug" "foo"}
@end smallexample
@noindent
These commands remove the debugging
information from the executable file @file{foo}, place it in the file 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 @file{foo.debug}, and leave behind a debug link in @file{foo}. Ulrich
Drepper's @file{elfutils} package, starting with version 0.53, contains 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 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. foo.debug} has the same functionality as the three commands above.
Since there are many different ways to compute CRC's for the debug link Since there are many different ways to compute CRC's for the debug
(different polynomials, reversals, byte ordering, etc.). This computation does link (different polynomials, reversals, byte ordering, etc.), the
not apply to the build id section. The simplest way to describe the CRC used simplest way to describe the CRC used in @code{.gnu_debuglink}
in @code{.gnu_debuglink} sections is to give the complete code for a function sections is to give the complete code for a function that computes it:
that computes it:
@kindex gnu_debuglink_crc32 @kindex gnu_debuglink_crc32
@smallexample @smallexample
@ -12097,6 +12119,9 @@ gnu_debuglink_crc32 (unsigned long crc,
@} @}
@end smallexample @end smallexample
@noindent
This computation does not apply to the ``build ID'' method.
@node Symbol Errors @node Symbol Errors
@section Errors Reading Symbol Files @section Errors Reading Symbol Files