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

Eli Zaretskii
2007-09-15T09:52:29Z

> 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