diff options
Diffstat (limited to 'gdb/doc')
| -rw-r--r-- | gdb/doc/ChangeLog | 7 | ||||
| -rw-r--r-- | gdb/doc/gdb.texinfo | 89 |
2 files changed, 66 insertions, 30 deletions
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 1c1a2ca..05d55ae 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -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 diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 8d93565..4c1a200 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -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. - -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}. +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. @@ -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}. - -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: +@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 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 |