From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by sourceware.org (Postfix) with ESMTPS id 05F063858C3A for ; Tue, 19 Oct 2021 22:35:13 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 05F063858C3A Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-467-PmRCBTBzMiamChXAXxT3xA-1; Tue, 19 Oct 2021 18:35:12 -0400 X-MC-Unique: PmRCBTBzMiamChXAXxT3xA-1 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 476A419200C0; Tue, 19 Oct 2021 22:35:11 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-114-104.phx2.redhat.com [10.3.114.104]) by smtp.corp.redhat.com (Postfix) with ESMTP id 59D16ADCD; Tue, 19 Oct 2021 22:35:10 +0000 (UTC) From: Aaron Merey To: eliz@gnu.org Cc: gdb-patches@sourceware.org, simark@simark.ca Subject: Re: [PATCH 2/2] gdb.texinfo: Expand documentation for debuginfod Date: Tue, 19 Oct 2021 18:35:09 -0400 Message-Id: <20211019223509.296292-1-amerey@redhat.com> In-Reply-To: <83tuhdclhb.fsf@gnu.org> References: <83tuhdclhb.fsf@gnu.org> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: 8bit Content-Type: text/plain; charset="US-ASCII" X-Spam-Status: No, score=-13.3 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H2, SPF_HELO_NONE, SPF_NONE, TXREP autolearn=ham autolearn_force=no version=3.4.4 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on server2.sourceware.org X-BeenThere: gdb-patches@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gdb-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 19 Oct 2021 22:35:16 -0000 Thanks Eli. The updated patch is below. Aaron >From 94df86b8775e0500a6ce6bbb8a65f90a8ec838da Mon Sep 17 00:00:00 2001 From: Aaron Merey Date: Tue, 19 Oct 2021 18:20:40 -0400 Subject: [PATCH] gdb.texinfo: Expand documentation for debuginfod 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 | 91 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 84 insertions(+), 7 deletions(-) diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 631a7c03b31..a7400c5bdf7 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,76 @@ 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 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 +@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. Only @code{http://}, @code{https://} and @code{file://} protocols +should be used. The default value of @code{debuginfod-urls} is copied from +@var{$DEBUGINFOD_URLS}. + +@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. Debuginfod debugging output is shown +by default. +@end table + @node Man Pages @appendix Manual pages @cindex Man pages -- 2.31.1