From: Aaron Merey <amerey@redhat.com>
To: gdb-patches@sourceware.org
Cc: simark@simark.ca, keiths@redhat.com
Subject: [PATCH 2/2] gdb.texinfo: Expand documentation for debuginfod
Date: Mon, 18 Oct 2021 19:01:33 -0400 [thread overview]
Message-ID: <20211018230133.265619-3-amerey@redhat.com> (raw)
In-Reply-To: <20211018230133.265619-1-amerey@redhat.com>
Add section describing GDB's usage of debuginfod and new
debuginfod commands.
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 | 94 +++++++++++++++++++++++++++++++++++++++++----
1 file changed, 87 insertions(+), 7 deletions(-)
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 631a7c03b31..90c73a6a2b6 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
@@ -21398,7 +21399,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
@@ -21419,6 +21422,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
@@ -38750,12 +38757,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
@@ -47069,6 +47076,79 @@ 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 and source
+files using @code{debuginfod}.
+
+For instructions on building @value{GDBN} with @file{libdebuginfod},
+@xref{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.
+
+@item set debuginfod ask
+@value{GDBN} will prompt the user to enable or disable @code{debuginfod} before
+attempting to perform the next query.
+
+@kindex show debuginfod
+@item show debuginfod
+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.
+
+@item show debuginfod-urls
+Display the list of URLs that @code{debuginfod} will attempt to query.
+
+@kindex set debug debuginfod
+@kindex show debug debuginfod
+@cindex debugging debuginfod
+@item set debug debuginfod
+@itemx show debug debuginfod
+Enable or disable @code{debuginfod}-related debugging output.
+Use @code{1} to enable and @code{0} to disable.
+@end table
+
+By default, @code{debuginfod} is set to @code{ask} for interactive sessions and
+@code{off} for non-interactive sessions. The default value of
+@code{debuginfod-urls} is copied from @var{$DEBUGINFOD_URLS}. Debuginfod
+debugging output is shown by default.
+
@node Man Pages
@appendix Manual pages
@cindex Man pages
--
2.31.1
next prev parent reply other threads:[~2021-10-18 23:01 UTC|newest]
Thread overview: 23+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-10-18 23:01 [PATCH 0/2 v3] gdb: Add debuginfod first-use notification Aaron Merey
2021-10-18 23:01 ` [PATCH 1/2] gdb: add set/show commands for managing debuginfod Aaron Merey
2021-10-20 20:34 ` Keith Seitz
2021-10-21 22:23 ` Lancelot SIX
2021-10-25 22:30 ` Aaron Merey
2021-10-21 22:02 ` Lancelot SIX
2021-10-26 16:08 ` Simon Marchi
2021-10-28 22:18 ` Aaron Merey
2021-10-29 1:47 ` Simon Marchi
2021-10-30 1:09 ` Aaron Merey
2021-10-30 1:54 ` Simon Marchi
2021-10-31 2:43 ` Simon Marchi
2021-11-01 15:52 ` Simon Marchi
2021-11-01 17:39 ` Aaron Merey
2021-11-01 18:00 ` Simon Marchi
2021-11-02 16:51 ` Simon Marchi
2021-11-02 20:35 ` Aaron Merey
2021-10-18 23:01 ` Aaron Merey [this message]
2021-10-19 11:17 ` [PATCH 2/2] gdb.texinfo: Expand documentation for debuginfod Eli Zaretskii
2021-10-19 22:35 ` Aaron Merey
2021-10-20 11:38 ` Eli Zaretskii
2021-10-30 1:18 ` Aaron Merey
2021-10-30 6:57 ` Tom de Vries
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20211018230133.265619-3-amerey@redhat.com \
--to=amerey@redhat.com \
--cc=gdb-patches@sourceware.org \
--cc=keiths@redhat.com \
--cc=simark@simark.ca \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).