abrt-debuginfo-install: add mini-doc

Signed-off-by: Denys Vlasenko <vda.linux@googlemail.com>

1 files changed, 50 insertions, 8 deletions

diff --git a/src/Daemon/abrt-debuginfo-install b/src/Daemon/abrt-debuginfo-install
index fe55250a..e9b398a8 100755
--- a/src/Daemon/abrt-debuginfo-install
+++ b/src/Daemon/abrt-debuginfo-install
@@ -1,4 +1,54 @@
 #!/bin/sh
+# Called by abrtd before producing a backtrace.
+# The task of this script is to install debuginfos.
+#
+# Just using [pk-]debuginfo-install does not work well.
+# - they can't install more than one version of debuginfo
+#   for a package
+# - their output is unsuitable for scripting
+# - debuginfo-install aborts if yum lock is busy
+# - pk-debuginfo-install was observed to hang
+#
+# Usage: abrt-debuginfo-install CORE TEMPDIR [CACHEDIR]
+# If CACHEDIR is specified, debuginfos should be installed there.
+# If not, debuginfos should be installed into TEMPDIR.
+#
+# Currently, we are called with CACHEDIR set to "/", but in the future
+# it may be omitted or set to something else. script must be ready
+# for those cases too.
+#
+# Algorithm:
+# - Create TEMPDIR
+# - Extract build-ids from coredump
+# - For every build-id, check /usr/lib/debug/.build-id/XX/XXXX.debug
+#   and CACHEDIR/usr/lib/debug/.build-id/XX/XXXX.debug
+# - If they all exist, exit 0
+# - Using "yum provides /usr/lib/debug/.build-id/XX/XXXX.debug",
+#   figure out which debuginfo packages are needed
+# - Download them using "yumdownloader PACKAGE..."
+# - Unpack them with rpm2cpio | cpio to TEMPDIR
+# - If CACHEDIR is specified, copy usr/lib/debug/.build-id/XX/XXXX.debug
+#   to CACHEDIR/usr/lib/debug/.build-id/XX/XXXX.debug and delete TEMPDIR
+# - Report which XX/XXXX.debug are still missing.
+#
+# In the future, we may want to use a separate CACHEDIR (say, /var/cache/abrt-di)
+# and use it with this gdb command:
+#   set debug-file-directory /usr/lib/debug/.build-id:CACHEDIR/usr/lib/debug/.build-id
+# but current gdb can't handle DIR1:DIR2.
+# So, currently we are called with CACHEDIR set to "/", and don't pass
+# "set debug-file-directory" to gdb.
+# This is ugly, since it messes up /usr/lib/debug/.build-id over time
+# by piling up debuginfos there without any means to control their amount,
+# but it's the only way to make it work with current gdb.
+#
+# Output goes to GUI as debigunfo install log.
+# "MISSING:xxxx" messages result in xxxx being prepended to backtrace
+#
+# Exitcodes:
+# 0 - all debuginfos are installed
+# 1 - not all debuginfos are installed
+# 2+ - serious problem
+
 
 core=$1
 tempdir=$2
@@ -11,14 +61,6 @@ count_words() {
 
 exec 2>&1
 
-# Output goes to GUI as debigunfo install log.
-# "MISSING:xxxx" messages result in xxxx being prepended to backtrace
-
-# Exitcodes:
-# 0 - all debuginfos are installed
-# 1 - not all debuginfos are installed
-# 2+ - serious problem
-
 test -f "$core" || exit 2
 # cachedir is optional
 test x"$cachedir" = x"" || test -d "$cachedir" || exit 2