Merge branch 'master' of ssh://git.fedorahosted.org/git/abrt

1 files changed, 57 insertions, 8 deletions

diff --git a/src/Daemon/abrt-debuginfo-install b/src/Daemon/abrt-debuginfo-install
index fe55250..fc5380b 100755
--- a/src/Daemon/abrt-debuginfo-install
+++ b/src/Daemon/abrt-debuginfo-install
@@ -1,4 +1,61 @@
 #!/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.
+#
+# Output goes to GUI as debuginfo install log. The script should be careful
+# to give useful, but not overly cluttered info to stdout.
+# Additionally, abrt daemon handles "MISSING:xxxx" messages specially:
+# xxxx will be prepended to backtrace. This is used to inform about
+# missing debuginfos.
+#
+# Exitcodes:
+# 0 - all debuginfos are installed
+# 1 - not all debuginfos are installed
+# 2+ - serious problem
+#
+# 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.
+#
+# For better debuggability, eu_unstrip.OUT, yum_provides.OUT etc files
+# are saved in TEMPDIR, and TEMPDIR is not deleted if we exit with exitcode 2
+# ("serious problem").
+#
+# 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.
+
 
 core=$1
 tempdir=$2
@@ -11,14 +68,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