gdb.texinfo: Expand documentation for debuginfod

Message ID 20210430235048.1371108-1-amerey@redhat.com
State Superseded
Headers show
Series
  • gdb.texinfo: Expand documentation for debuginfod
Related show

Commit Message

Mike Frysinger via Gdb-patches April 30, 2021, 11:50 p.m.
Add section describing GDB's usage of debuginfod.

Refer to this new section in the description of the '--with-debuginfod'
configure option.

Mention debuginfod in the 'Separate Debug Files' section.

gdb/doc/ChangeLog:

	* gdb.texinfo (Debuginfod): New section.
	(Configure Options): Refer to debuginfod section.
	(Separate Debug Files): Mention debuginfod.
---
 gdb/doc/gdb.texinfo | 38 ++++++++++++++++++++++++++++++++------
 1 file changed, 32 insertions(+), 6 deletions(-)

-- 
2.30.2

Comments

Mike Frysinger via Gdb-patches May 1, 2021, 6:22 a.m. | #1
> Date: Fri, 30 Apr 2021 19:50:48 -0400

> From: Aaron Merey via Gdb-patches <gdb-patches@sourceware.org>

> 

> Add section describing GDB's usage of debuginfod.

> 

> Refer to this new section in the description of the '--with-debuginfod'

> configure option.

> 

> Mention debuginfod in the 'Separate Debug Files' section.

> 

> gdb/doc/ChangeLog:

> 

> 	* gdb.texinfo (Debuginfod): New section.

> 	(Configure Options): Refer to debuginfod section.

> 	(Separate Debug Files): Mention debuginfod.


Thanks, some comments below.

> --- a/gdb/doc/gdb.texinfo

> +++ b/gdb/doc/gdb.texinfo

> @@ -184,6 +184,7 @@ software in general.  We will miss him.

>                                   the operating system

>  * Trace File Format::		GDB trace file format

>  * Index Section Format::        .gdb_index section format

> +* Debuginfod::			Download debugging resources with debuginfod


Please don't use TAB characters in Texinfo sources; use spaces
instead.

> -hex characters, not 10.)

> +hex characters, not 10.) @value{GDBN} can automatically query

> +debuginfod servers using build IDs in order to download separate debug

> +files that cannot be found locally. For more information see

> +@ref{Debuginfod}.


Please leave 2 spaces between sentences, here and elsewhere in your
patch.  We use US English conventions and spelling.

> +If the debug file still has not been found and debuginfod is enabled,

> +@value{GDBN} will attempt to download the file from debuginfod servers.


Please add here a cross-reference to the node which describes
debuginfod (preferably @pxref in parentheses after "debuginfod"), so
that the readers could easily find the relevant information.

Also, I wonder whether "debuginfod" should be in @code everywhere
(except in cross-references and the node name), since I believe we use
that markup for other packages.

> +Used to automatically fetch ELF, DWARF and source files from debuginfod

> +servers using their associated build IDs.

                 ^^^^^
This "their" is ambiguous: it could refer to ELF/DWARF/source files,
or it could refer to debuginfod servers.  FWIW, I think the original
text is better in this regard.

>                                             Enabled by default if

> +libdebuginfod is installed and found at configure time. For more

> +information regarding debuginfod see @ref{Debuginfod}.


"libdebuginfod" should have the @file markup.

> +@node Debuginfod

> +@appendix Download debugging resources with Debuginfod


Please add here the "@cindex debuginfod" index entry.

> +Using the debuginfod client library, libdebuginfod, @value{GDBN} can

                                        ^^^^^^^^^^^^^
@file{libdebuginfod}

> +See @ref{Configure Options,,--with-debuginfod} for instructions on

   ^^^^^^^^
It's better to use @xref here instead of "See @ref".

> +building @value{GDBN} with libdebuginfod. Debuginfod is packaged with

> +elfutils, starting with version 0.178. See

   ^^^^^^^^
@code{elfutils}

> +`https://sourceware.org/elfutils/Debuginfod.html` for more information

   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Please use @uref here instead of Markdown-like quoting.

Patch

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 802d0f9cfb6..268bebd9c0a 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -184,6 +184,7 @@  software in general.  We will miss him.
                                  the operating system
 * Trace File Format::		GDB trace file format
 * Index Section Format::        .gdb_index section format
+* Debuginfod::			Download debugging resources with debuginfod
 * Man Pages::			Manual pages
 * Copying::			GNU General Public License says
                                 how you can copy and share GDB
@@ -21358,7 +21359,10 @@  For the ``build ID'' method, @value{GDBN} looks in the
 a file named @file{@var{nn}/@var{nnnnnnnn}.debug}, where @var{nn} are the
 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.)
+hex characters, not 10.) @value{GDBN} can automatically query
+debuginfod servers using build IDs in order to download separate debug
+files that cannot be found locally. For more information see
+@ref{Debuginfod}.
 @end itemize
 
 So, for example, suppose you ask @value{GDBN} to debug
@@ -21379,6 +21383,9 @@  debug information files, in the indicated order:
 @file{/usr/lib/debug/usr/bin/ls.debug}.
 @end itemize
 
+If the debug file still has not been found and debuginfod is enabled,
+@value{GDBN} will attempt to download the file from debuginfod servers.
+
 @anchor{debug-file-directory}
 Global debugging info directories default to what is set by @value{GDBN}
 configure option @option{--with-separate-debug-dir}.  During @value{GDBN} run
@@ -38568,11 +38575,10 @@  terminal operations.
 
 @item --with-debuginfod
 Build @value{GDBN} with libdebuginfod, the debuginfod client library.
-Used to automatically fetch source files and separate debug files from
-debuginfod servers using the associated executable's build ID. Enabled
-by default if libdebuginfod is installed and found at configure time.
-debuginfod is packaged with elfutils, starting with version 0.178. You
-can get the latest version from `https://sourceware.org/elfutils/'.
+Used to automatically fetch ELF, DWARF and source files from debuginfod
+servers using their associated build IDs. Enabled by default if
+libdebuginfod is installed and found at configure time. For more
+information regarding debuginfod see @ref{Debuginfod}.
 
 @item --with-libunwind-ia64
 Use the libunwind library for unwinding function call stack on ia64
@@ -46825,6 +46831,26 @@  switch (die->tag)
   @}
 @end smallexample
 
+@node Debuginfod
+@appendix Download debugging resources with Debuginfod
+
+Debuginfod is an HTTP server for distributing ELF, DWARF and source
+code.
+
+Using the debuginfod client library, libdebuginfod, @value{GDBN} can
+query servers using the build IDs of missing resources in order to
+download them on demand.
+
+@value{GDBN} is able to automatically download missing debug info files
+and source code using debuginfod. @value{GDBN} can also download
+missing executables and shared libraries when handling core files.
+
+See @ref{Configure Options,,--with-debuginfod} for instructions on
+building @value{GDBN} with libdebuginfod. Debuginfod is packaged with
+elfutils, starting with version 0.178. See
+`https://sourceware.org/elfutils/Debuginfod.html` for more information
+regarding debuginfod.
+
 @node Man Pages
 @appendix Manual pages
 @cindex Man pages