commit 06e0aacb4b288403bd02a0820dd0f87c7f017a2b (HEAD -> master) Author: Frank Ch. Eigler <f...@redhat.com> Date: Tue Nov 14 14:09:40 2023 -0500
doc/debuginfod.8: clarify source file handling Added text about the archive common-prefix heuristic, mentioned the new eu-srcfiles tool, and gave some extra debian advice. Signed-off-by: Frank Ch. Eigler <f...@redhat.com> diff --git a/doc/debuginfod.8 b/doc/debuginfod.8 index 4f1f04b386bd..d79a193c8d9e 100644 --- a/doc/debuginfod.8 +++ b/doc/debuginfod.8 @@ -48,16 +48,10 @@ file. Source files are matched with DWARF files based on the source files listed in the DWARF may be a path \fIanywhere\fP in the file system, and debuginfod will readily serve their content on demand. (Imagine a doctored DWARF file that lists \fI/etc/passwd\fP -as a source file.) If this is a concern, audit your binaries with -tools such as: +as a source file.) If this is a concern, audit your binaries: .SAMPLE -% eu-readelf -wline BINARY | sed -n '/^Directory.table/,/^File.name.table/p' -or -% eu-readelf -wline BINARY | sed -n '/^Directory.table/,/^Line.number/p' -or even use debuginfod itself: -% debuginfod -vvv -d :memory: -F BINARY 2>&1 | grep 'recorded.*source' -^C +% eu-srcfiles -e BINARY .ESAMPLE If any of the \fB\-R\fP, \fB-U\fP, or \fB-Z\fP options is given, each @@ -65,12 +59,17 @@ file is scanned as an archive file that may contain ELF/DWARF/source files. Archive files are recognized by extension. If \-R is given, ".rpm" files are scanned; if \-U is given, ".deb" and ".ddeb" files are scanned; if \-Z is given, the listed extensions are scanned. -Because of complications such as DWZ-compressed debuginfo, may require -\fItwo\fP traversal passes to identify all source code. Source files -for RPMs are only served from other RPMs, so the caution for \-F does -not apply. Note that due to Debian/Ubuntu packaging policies & -mechanisms, debuginfod cannot resolve source files for DEB/DDEB at -all. + +Because of complications such as DWZ-compressed debuginfo, it may +require \fItwo\fP traversal passes to identify all source code. +Source files for binaries in archives are only served from archives, +so the caution for \-F does not apply. If the same source file may be +found in multiple different archives, a heuristic chooses the one +closest to the archive holding the debuginfo. ("closest" means +"longest common archive name prefix"). Note that due to Debian/Ubuntu +packaging policies & mechanisms, debuginfod cannot resolve source +files for DEB/DDEB at all. Consider using the +\-\-disable\-source\-scan option. If no PATH is listed, or none of the scanning options is given, then \fBdebuginfod\fP will simply serve content that it accumulated into