gdb.texinfo: Expand documentation for debuginfod

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.

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index c1046662724e37ec17a4d6c597a6aef23f356b50..e0b065e96638c274590cbd07aab6831e27f68084 100644 (file)
--- 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
@@ -21402,7 +21403,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
@@ -21423,6 +21426,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
@@ -38754,12 +38761,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
@@ -47080,6 +47087,82 @@ 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
+files.
+
+With the @code{debuginfod} client library, @file{libdebuginfod}, @value{GDBN}
+can query servers using the build IDs associated with missing debug info,
+executables and source files in order to download them on demand.
+
+For instructions on building @value{GDBN} with @file{libdebuginfod},
+@pxref{Configure Options,,--with-debuginfod}.  @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}.
+
+@menu
+* Debuginfod Settings::                Configuring debuginfod with @value{GDBN}
+@end menu
+
+@node Debuginfod Settings
+@section Debuginfod Settings
+
+@value{GDBN} provides the following commands for configuring @code{debuginfod}.
+
+@table @code
+@kindex set debuginfod
+@anchor{set debuginfod}
+@item set debuginfod
+@itemx set debuginfod on
+@cindex enable debuginfod
+@value{GDBN} will attempt to query @code{debuginfod} servers when missing debug
+info or source files.
+
+@item set debuginfod off
+@value{GDBN} will not attempt to query @code{debuginfod} servers when missing
+debug info or source files.  By default, @code{debuginfod} is set to @code{off}
+for non-interactive sessions.
+
+@item set debuginfod ask
+@value{GDBN} will prompt the user to enable or disable @code{debuginfod} before
+attempting to perform the next query.  By default, @code{debuginfod} is set to
+@code{ask} for interactive sessions.
+
+@kindex show debuginfod status
+@item show debuginfod status
+Show whether @code{debuginfod} is set to @code{on}, @code{off} or @code{ask}.
+
+@kindex set debuginfod urls
+@cindex configure debuginfod URLs
+@item set debuginfod urls
+@itemx set debuginfod urls @var{urls}
+Set the space-separated list of URLs that @code{debuginfod} will attempt to
+query.  Only @code{http://}, @code{https://} and @code{file://} protocols
+should be used.  The default value of @code{debuginfod urls} is copied from
+the @var{DEBUGINFOD_URLS} environment variable.
+
+@kindex show debuginfod urls
+@item show debuginfod urls
+Display the list of URLs that @code{debuginfod} will attempt to query.
+
+@kindex set debuginfod verbose
+@cindex debuginfod verbosity
+@item set debuginfod verbose
+@itemx set debuginfod verbose @var{n}
+Enable or disable @code{debuginfod}-related output.  Use a non-zero value
+to enable and @code{0} to disable.  @code{debuginfod} output is shown by
+default.
+
+@kindex show debuginfod verbose
+@item show debuginfod verbose
+Show the current verbosity setting.
+
+@end table
+
 @node Man Pages
 @appendix Manual pages
 @cindex Man pages