From FEDORA_PATCHES Mon Sep 17 00:00:00 2001

From: =?UTF-8?q?Alexandra=20H=C3=A1jkov=C3=A1?= <ahajkova@redhat.com>

Date: Mon, 10 Jan 2022 13:00:50 +0100

Subject: gdb-rhbz2024875-expand-documentation-for-debuginfod.patch

;;Backport upstream commit from Aaron Merey

;;3ea44f21299 gdb.texinfo: Expand documentation for debuginfod

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

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

@@ -21373,7 +21374,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

@@ -21394,6 +21397,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

@@ -38746,12 +38753,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

@@ -47012,6 +47019,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