debuginfod-find.1: note on how to find a comp_dir

doc/ChangeLog:

* debuginfod-find.1: add a note to DESCRIPTION section for the 'source'
  subcommand, clarifying where to find the CU compilation-directory.

I'm looking at how to improve and document the workflow for using
debuginfod-find to study the behaviour of packaged software on a system, e.g.
in conjunction with a tracing tool like SystemTap. You can read the exact
compiled source code with debuginfod-find source and use that to figure out
which source code locations are interesting to trace. But that process has
several non-obvious or inconvenient steps.

This patch is a clarification to the debuginfod-find source man page pointing
out the eu-readelf command that can show the comp_dir in downloaded debuginfo.
Since debuginfod-find source could be picked up and used by a developer
unfamiliar with DWARF terminology, I think such a clarification saves time
for newbies figuring out what a CU compilation-directory is.

Signed-off-by: Serhei Makarov <serhei@serhei.io>

diff --git a/doc/debuginfod-find.1 b/doc/debuginfod-find.1
index 957ec7e716f9cb2c1a42d680ab56b36a6ba04656..7d577babeb89ba1301f5063b6ccbe239cb08adb0 100644 (file)
--- a/doc/debuginfod-find.1
+++ b/doc/debuginfod-find.1
@@ -92,6 +92,19 @@ is made up of multiple CUs.  Therefore, to disambiguate, debuginfod
 expects source queries to prefix relative path names with the CU
 compilation-directory, followed by a mandatory "/".
 
+Note: for software packaged by distributions, the CU
+compilation-directory may not be obvious.  It can be found by
+inspecting AT_comp_dir values in downloaded debuginfo.  For example,
+the comp_dir of the Fedora 37 version of /bin/ls can be found as
+follows:
+
+.SAMPLE
+% debuginfod-find debuginfo /bin/ls
+~/.cache/debuginfod_client/03529d48345409576cd5c82a56ad08555088d353/
+% eu-readelf -w ~/.cache/debuginfod_client/03529d48345409576cd5c82a56ad08555088d353/debuginfo | grep comp_dir
+           comp_dir             (line_strp) "/usr/src/debug/coreutils-9.1-6.fc37.x86_64/separate"
+.ESAMPLE
+
 Note: the caller may or may not elide \fB../\fP or \fB/./\fP or extraneous
 \fB///\fP sorts of path components in the directory names.  debuginfod
 accepts both forms.  Specifically, debuginfod canonicalizes path names