* 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.

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

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
+There are two identificators how the separate debug file may be found:
-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:
 
 @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
+information file with build id content matching the build id content of the
-reads the debugging information from the first one it finds.
+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},
+So, for example, if you ask @value{GDBN} to debug @file{/usr/bin/ls}, which has
-which has a link containing the name @file{ls.debug}, and the global
+a @dfn{debug link} containing the name @file{ls.debug}, its @dfn{build id}
-debug directory is @file{/usr/lib/debug}, then @value{GDBN} will look
+value in hexadecimal is @code{abcdef} and the global debug directory is
-for debug information in @file{/usr/bin/ls.debug},
+@file{/usr/lib/debug}, then @value{GDBN} will look for debug information in
-@file{/usr/bin/.debug/ls.debug}, and
+@file{/usr/lib/debug/.build-id/ab/cdef.debug}, @file{/usr/bin/ls.debug},
-@file{/usr/lib/debug/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
+@sc{gnu} binary utilities contain the @samp{objcopy} utility able to produce
-separated executable / debugging information file pairs.  Ulrich
+the separated executable / debugging information file pairs by commands
-Drepper's @file{elfutils} package, starting with version 0.53,
+@kbd{objcopy --only-keep-debug foo foo.debug; strip -g foo; objcopy
-contains a version of the @code{strip} command such that the command
+--add-gnu-debuglink="foo.debug" "foo"}.  These commands remove the debugging
-@kbd{strip foo -f foo.debug} removes the debugging information from
+information from the executable file @file{foo}, place it in the file
-the executable file @file{foo}, places it in the file
+@file{foo.debug}, and leave behind a debug link in @file{foo}.  Ulrich
-@file{foo.debug}, and leaves behind a debug link in @file{foo}.
+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
+Since there are many different ways to compute CRC's for the debug link
-polynomials, reversals, byte ordering, etc.), the simplest way to
+(different polynomials, reversals, byte ordering, etc.).  This computation does
-describe the CRC used in @code{.gnu_debuglink} sections is to give the
+not apply to the build id section.  The simplest way to describe the CRC used
-complete code for a function that computes it:
+in @code{.gnu_debuglink} sections is to give the complete code for a function
+that computes it:
 
 @kindex gnu_debuglink_crc32
 @smallexample