[PATCH] gdb.texinfo: Expand documentation for debuginfod

[PATCH] gdb.texinfo: Expand documentation for debuginfod

[Aaron Merey]

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(-)

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
-- 
2.30.2

Re: [PATCH] gdb.texinfo: Expand documentation for debuginfod

[Eli Zaretskii]

> 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] gdb.texinfo: Expand documentation for debuginfod

[Aaron Merey]

Hi Eli,

Thanks, I've updated the patch with your feedback.

Aaron

---

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 | 41 ++++++++++++++++++++++++++++++++++-------
 1 file changed, 34 insertions(+), 7 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 802d0f9cfb6..406842a6d56 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 @code{debuginfod}
 * Man Pages::			Manual pages
 * Copying::			GNU General Public License says
                                 how you can copy and share GDB
@@ -21358,7 +21359,9 @@ 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
+@code{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 +21382,10 @@ 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 @code{debuginfod}
+(@pxref{Debuginfod}) is enabled, @value{GDBN} will attempt to download the
+file from @code{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
@@ -38567,12 +38574,12 @@ Use the curses library instead of the termcap library, for text-mode
 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/'.
+Build @value{GDBN} with @file{libdebuginfod}, the @code{debuginfod} client
+library.  Used to automatically fetch ELF, DWARF and source files from
+@code{debuginfod} servers using build IDs associated with any missing
+files.  Enabled by default if @file{libdebuginfod} is installed and found
+at configure time.  For more information regarding @code{debuginfod} see
+@ref{Debuginfod}.
 
 @item --with-libunwind-ia64
 Use the libunwind library for unwinding function call stack on ia64
@@ -46825,6 +46832,26 @@ switch (die->tag)
   @}
 @end smallexample
 
+@node Debuginfod
+@appendix Download debugging resources with Debuginfod
+@cindex debuginfod
+
+@code{debuginfod} is an HTTP server for distributing ELF, DWARF and source code.
+
+With the @code{debuginfod} client library, @file{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 @code{debuginfod}.  @value{GDBN} can also download
+missing executables and shared libraries when handling core files.
+
+@xref{Configure Options,,--with-debuginfod} for instructions on
+building @value{GDBN} with @file{libdebuginfod}.  @code{debuginfod} is packaged
+with @code{elfutils}, starting with version 0.178.  See
+@uref{https://sourceware.org/elfutils/Debuginfod.html} for more information
+regarding @code{debuginfod}.
+
 @node Man Pages
 @appendix Manual pages
 @cindex Man pages
-- 
2.30.2

Re: [PATCH] gdb.texinfo: Expand documentation for debuginfod

[Eli Zaretskii]

> From: Aaron Merey <amerey@redhat.com>
> Cc: gdb-patches@sourceware.org
> Date: Thu,  6 May 2021 13:18:55 -0400
> 
> Hi Eli,
> 
> Thanks, I've updated the patch with your feedback.

Thanks.