diff options
| -rw-r--r-- | gdb/doc/ChangeLog | 5 | ||||
| -rw-r--r-- | gdb/doc/gdb.texinfo | 145 |
2 files changed, 90 insertions, 60 deletions
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 05d55ae..70c9e82 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -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> * gdb.texinfo (Separate Debug Files): Included a BUILD ID description. diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 4c1a200..83899d3 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -11893,66 +11893,79 @@ Display the current shared library search path. @cindex @file{.debug} subdirectories @cindex debugging information directory, global @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 file separate from the executable itself, in a way that allows @value{GDBN} to find and load the debugging information automatically. -Since debugging information can be very large --- sometimes larger -than the executable code itself --- some systems distribute debugging +Since debugging information can be very large---sometimes larger +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. -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 @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}. +The executable contains a @dfn{debug link} that specifies the name of +the separate debug info file. The separate debug file's name is +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 -@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. +The executable contains a @dfn{build ID}, a unique signature that is +also present in the corresponding debug info file. (This is supported +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 -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: +Depending on the way the debug info file is specified, @value{GDBN} +uses two different methods of looking for the debug file: @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}. +For the ``debug link'' method, @value{GDBN} looks up the named file in +the directory of the executable file, then in a subdirectory of that +directory named @file{.debug}, and finally under the global debug +directory, in a subdirectory whose name is identical to the leading +directories of the executable's absolute file name. + +@item +For the ``debug ID'' method, @value{GDBN} looks in the +@file{.build-id} subdirectory of the global debug directory for a file +named @file{@var{nn}/@var{nnnnnnnn}.debug}, where @var{nn} are the +first 2 hex characters of the debug ID signature, and @var{nnnnnnnn} +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 -the directory containing the executable file (that is, it will look -for a file named @file{@var{execdir}/@var{debugfile}}, +@file{/usr/bin/ls.debug} @item -a subdirectory of that directory named @file{.debug} (that is, the -file @file{@var{execdir}/.debug/@var{debugfile}}, and +@file{/usr/bin/.debug/ls.debug} @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). +@file{/usr/lib/debug/usr/bin/ls.debug}. @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 -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. @@ -11972,7 +11985,7 @@ information files. @end table @cindex @code{.gnu_debuglink} sections -@cindex debug links +@cindex debug link sections A debug link is a special section of the executable file named @code{.gnu_debuglink}. The section must contain: @@ -11995,37 +12008,46 @@ 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. +@cindex build ID sections +A build ID is a special section of the executable file named +@code{.note.gnu.build-id}. This section contains unique +identification for 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 with an identical value is present in the original built +binary with symbols, in its stripped variant, and in the separate +debugging 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 -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 +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. -@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 +@sc{gnu} binary utilities (Binutils) package includes the +@samp{objcopy} utility that can produce +the separated executable / debugging information file pairs using the +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 @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 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: +Since there are many different ways to compute CRC's for the debug +link (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: @kindex gnu_debuglink_crc32 @smallexample @@ -12097,6 +12119,9 @@ gnu_debuglink_crc32 (unsigned long crc, @} @end smallexample +@noindent +This computation does not apply to the ``build ID'' method. + @node Symbol Errors @section Errors Reading Symbol Files |