From 3ea44f212995117414bf0fee9aaa430f1e59fa20 Mon Sep 17 00:00:00 2001 From: Aaron Merey Date: Fri, 29 Oct 2021 20:49:29 -0400 Subject: [PATCH] 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. --- gdb/doc/gdb.texinfo | 97 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 90 insertions(+), 7 deletions(-) diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index c1046662724..e0b065e9663 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 @@ -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 -- 2.30.2