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
@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.
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
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
projects / deliverable / binutils-gdb.git / commitdiff
