Apport per-package hooks
========================

Packages can add additional fields (or even modify existing fields, if
they want) of Apport crash or bug reports by placing a Python code
snippet into

  /usr/share/apport/package-hooks/<packagename>.py

or

  /usr/share/apport/package-hooks/source_<sourcepackagename>.py

Apport will import this and call a function

  add_info(report)

and pass the currently processed problem report. This is an instance
of apport.Report, and should mainly be used as a dictionary. Please
see the Python help of this class for details:

  >>> import apport
  >>> help(apport.Report)

Package independent hooks
=========================

Similarly to per-package hooks, you can also have additional
information collected for any crash or bug. For example, you might
want to include violation logs from SELinux or AppArmor for every
crash. The interface and file format is identical to the per-package
hooks, except that they need to be put into

  /usr/share/apport/general-hooks/<hookname>.py

The <hookname> can be arbitrary and should describe the functionality.

Examples
========

Trivial example: To attach a log file /var/log/foo.log for crashes in
binary package foo, put this into /usr/share/apport/package-hooks/foo.py:

------------ 8< ----------------
import os.path

def add_info(report):
    if os.path.exists('/var/log/foo.log'):
        report['FooLog'] = open('/var/log/foo.log').read()
------------ 8< ----------------

Apport itself ships a source package hook, see
/usr/share/apport/package-hooks/source_apport.py.

An interesting use case of hooks is to detect situations which should
not be reported as bugs, because they happen on known-bad hardware,
from a third-party repository, or other situations. This can be
achieved by adding a field

  report['UnreportableReason'] = _('explanation')

Such reports are displayed by the apport frontends as
unsupportable/unreportable with the given explanation. Please ensure
proper i18n for the texts.

If you want to entirely ignore a crash without presenting an
explanatory error dialog box, use "Ignore" instead of
"UnreportableReason":

  report['Ignore'] = 'True'

(the actual value does not matter, it just must be a string).
