[patch] build-id .debug files load (like .gnu_debuglink)

[Eli Zaretskii]

> From: Roland McGrath <roland@redhat.com>
> Cc: jan.kratochvil@redhat.com, gdb-patches@sourceware.org
> Date: Tue,  4 Sep 2007 00:21:29 -0700 (PDT)
> 
> > > It is also not good to use the term "signature" loosely with relation to
> > > build ID bits.
> > 
> > What alternative term would you suggest?  I have no shares in this
> > particular word, if a good alternative exists.
> 
> Well, there is "ID".  Also "bit string", or "set of bits", or "sequence of
> bytes" come to mind.  Whatever flows in the particular context to say what
> is so, which is that it is a small chunk of data taken solely as an
> identifier with no instrinsic meaning to its bits.  The text I wrote in the
> ld manual (ld/ld.texinfo @node Options) uses "unique bits" and "bit string".
> 
> Also, I don't think it is proper to refer to this as GNU/Linux operating
> system magic and refer to the Fedora wiki.  The build ID note is a GNU
> convention for ELF binaries and the tool involved in creating it is GNU ld.
> It is the linker, and how the linker is used, that determines whether
> creating a binary normally gives it one.  The GDB manual should refer
> directly to the GNU ld manual about how it's created.
> 
> If you mean the manual to document precise format details, then it should
> not say that a build ID section is "named @code{.note.gnu.build-id}".  That
> is the name of the input section that ld synthesizes under --build-id, and
> will often be the name of the final section seen in an executable or DSO.
> But the name is in no way magical and any tool would be broken if it worked
> only on a section by that name.  It should be mentioned only as a common
> case.  It is only the normative ELF data that controls what constitutes a
> proper build ID in an ELF file.  That is, SHT_NOTE sections, or PT_NOTE
> segments in sectionless files, with proper ELF note formats of name "GNU"
> and type NT_GNU_BUILD_ID.
> 
> The wording now says "executable" a lot, while in reality it can be any
> kind of ELF file that gdb would consider.  That is, executables or DSOs
> (ET_EXEC/ET_DYN), or ET_REL files that are contemplated in their own right,
> as is done for Linux kernel modules.  For all of these, gdb can find
> separate debug info, and should use build IDs to do so.

Thanks for your comments and explanations.

I believe I've fixed the manual according to your suggestions, the
patch I committed is attached below.

2007-09-15  Eli Zaretskii  <eliz@gnu.org>

	* gdb.texinfo (Separate Debug Files): More accurate wording
	regarding build ID and a reference to the ld manual rather
	than the Fedora wiki.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.430
diff -u -r1.430 gdb.texinfo
--- gdb.texinfo	15 Sep 2007 08:54:26 -0000	1.430
+++ gdb.texinfo	15 Sep 2007 09:48:18 -0000
@@ -11933,14 +11933,15 @@
 came from the same build.
 
 @item
-The executable contains a @dfn{build ID}, a unique signature that is
+The executable contains a @dfn{build ID}, a unique bit string 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 build ID, but can be
-computed from the build ID, see below.
+only on some operating systems, notably those which use the ELF format
+for binary files and the @sc{gnu} Binutils.)  For more details about
+this feature, see the description of the @option{--build-id}
+command-line option in @ref{Options, , Command Line Options, ld.info,
+The GNU Linker}.  The debug info file's name is not specified
+explicitly by the build ID, but can be computed from the build ID, see
+below.
 @end itemize
 
 Depending on the way the debug info file is specified, @value{GDBN}
@@ -11958,14 +11959,14 @@
 For the ``build 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 build ID signature, and @var{nnnnnnnn}
-are the rest of the signature.  (Real signatures are 32 or more
-characters, not 10.)
+first 2 hex characters of the build ID bit string, and @var{nnnnnnnn}
+are the rest of the bit string.  (Real build ID strings are 32 or more
+hex 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
+@file{/usr/bin/ls}, which has a debug link that specifies the
+file @file{ls.debug}, and a 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:
@@ -12023,14 +12024,15 @@
 
 @cindex @code{.note.gnu.build-id} sections
 @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 build ID is a special section in the executable file (and in other
+ELF binary files that @value{GDBN} may consider).  This section is
+often named @code{.note.gnu.build-id}, but that name is not mandatory.
+It contains unique identification for the built files---the ID remains
+the same across multiple builds of the same build tree.  The default
+algorithm SHA1 produces 160 bits (40 hexadecimal characters) of the
+content for the build ID string.  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
@@ -12039,7 +12041,7 @@
 but they need not contain any data---much like a @code{.bss} section
 in an ordinary executable.
 
-@sc{gnu} binary utilities (Binutils) package includes the
+The @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:
@@ -12073,7 +12075,7 @@
 Build ID gets embedded into the main executable using @code{ld --build-id} or
 the @value{NGCC} counterpart @code{gcc -Wl,--build-id}.  Build ID support plus
 compatibility fixes for debug files separation are present in @sc{gnu} binary
-utilities (Binutils) since version 2.18.
+utilities (Binutils) package since version 2.18.
 @end itemize
 
 @noindent