.. _use-debuginfod-with-gdb:

==============================================
Use Debusine archives as a debuginfod source
==============================================

Debusine can act as a
`debuginfod <https://sourceware.org/elfutils/Debuginfod.html>`_ server for
archives it hosts.  After you build and publish packages,
:manpage:`gdb(1)` (and other debuginfod clients) can fetch matching debug
symbols automatically by ELF build-ID, without installing ``-dbgsym``
packages by hand.

When Debusine builds packages that include debug symbols, it extracts those
debug symbols and stores them separately so that it can retrieve them
quickly later.  Publishing binaries into a suite also publishes the related
debug symbols, and the archive serves them for any suite in that workspace.
See :ref:`package-repositories`.

You need a repository and a successful publish before clients can resolve
symbols.  Create those with :ref:`create-package-repository` and upload
packages as usual (:ref:`dput-ng`).

Prerequisites
-------------

* A Debusine workspace with a suite that has published binaries (and thus
  related :artifact:`debian:debug-symbols` items).
* Builds that produced ``-dbgsym`` packages via :task:`Sbuild` (normal for
  Debian packaging when automatic dbgsym generation is enabled, although
  only when building compiled code).
* A debuginfod-capable client.  Debian's ``gdb`` package is enough for the
  steps below.
* The archive base URL, the same one you would use in APT URIs, for
  example ``https://deb.debusine.debian.net/debian/my-workspace/``.

Set the debuginfod URL
----------------------

Debuginfod clients read the ``DEBUGINFOD_URLS`` environment variable: a
space-separated list of archive root URLs.  Use the Debusine archive root
(scope and workspace), not a suite path and not a ``dists/`` URL.  Include
the base distribution's debuginfod server as well, so gdb can also resolve
symbols for libraries such as glibc:

.. code-block:: console

    $ export DEBUGINFOD_URLS="https://deb.debusine.debian.net/debian/my-workspace/ https://debuginfod.debian.net/"

To make that permanent for your user, add the same line to ``~/.bashrc``,
``~/.profile``, or another shell startup file.

:manpage:`gdb(1)` appends ``buildid/<build-id>/debuginfo`` to each base URL.
One Debusine entry covers every suite in that archive.

Private workspaces
~~~~~~~~~~~~~~~~~~

Downloading from a private workspace requires the viewer role and HTTP Basic
Authentication (user name and user token as the password), the same as APT
access.  See :ref:`package-repositories`.

Debug with gdb
--------------

.. code-block:: console

    $ gdb /path/to/stripped/binary

When gdb needs debug information, it queries ``DEBUGINFOD_URLS``.

Source code while debugging
---------------------------

Debusine does not provide source files via debuginfod.  Unpack or install
the matching source package locally (or point gdb at a source tree with
``directory``) if you need source listing and stepping through source
lines.

Limitations
-----------

* Source files are not served over debuginfod (the same practical limitation
  as ``debuginfod.debian.net`` for many Debian packages); use local sources
  as above.
* DWZ supplement files from ``-dbgsym`` packages are not ingested yet; some
  compressed debug information may be incomplete.
