Introduction

Debug packages contain debug symbols and usually are named <package>-dbg. They are useful if program crashes and you want to generate stack trace which contains information about functions where it crashed.

dbgsym packages

If you use debhelper/9.20151219 or newer in Debian, it will generate debug symbol packages (as <package>-dbgsym) for you with no additional changes to your source package. These packages are not available from the main archive. Please fetch these from debian-debug or snapshot.debian.org.

If you want to transition from a former -dbg package to a -dbgsym package you might want to look into the dh_strip's switch --dbgsym-migration=pkgname-dbg (<< currentversion~)' switch.

-dbgsym packages have the same component as the regular mirror (e.g. "main"), but they exists in a separate "archive". In fact, the suites are also different ("unstable" vs. "unstable-debug"). Basically, the "X-debug" suite works like an "overlay" to the suite "X" (similar to how experimental needs "unstable" to be useful). For that reason, packages in "unstable" cannot depend on packages in "unstable-debug". This means that -dbg packages must not be transitioned to a dummy package depending on -dbgsym. When transitioning to the new system, just drop the -dbg package.

Configuration for creating a debug package

The information below is obsolete. You should prefer automatic debug symbol packages.

Package control entry

Add a binary package stanza to debian/control, describing the debug package. An example:

Package: giblib1-dbg
Architecture: any
Section: debug
Priority: extra
Depends:
    giblib1 (= ${binary:Version}),
    ${misc:Depends}
Description: debugging symbols for giblib1
 giblib is a library of handy stuff. Contains an imlib2 wrapper to avoid the
 context stuff, doubly-linked lists and font styles.
 .
 This package contains the debugging symbols for giblib1.

Debhelper dependency

To use the dh_strip options as described below, you will need to build using debhelper version 5 or later. Set the Build-Depends in debian/control like this:

Build-Depends:
    ...
    debhelper (>= 5),
    ...

Selectively strip debugging symbols

The build process needs to selectively strip debugging symbols from binaries, but retain them for use in the debug packages.

Stripping the binary files is usually done by the debhelper dh_strip program, which defaults to discarding the debugging symbols. You will need to have dh_strip invoked with the --dbg-package=foo option to place the debugging symbols under /usr/lib/debug/ in the named package.

Debhelper < 7

Note: v7 has been released in April 2008!

If using debhelper earlier than version 7 , you will have explicit calls to dh_strip in your debian/rules. Change the call to look like:

binary-arch: build install
        ...
        dh_strip --dbg-package=giblib1-dbg
        ...

Debhelper >= 7

Debhelper version 7 aggregates long sequences of individual ‘dh_foo’ commands into the dh command, so you will probably not have an explicit dh_strip call. Instead, you will need to override the default invocation of dh_strip.

To allow for simpler overrides of individual debhelper commands, set your Build-Depends field to depend on a minimum debhelper version of 7.0.50 in debian/control:

Build-Depends:
    ...
    debhelper (>= 7.0.50),
    ...

Then add the following rule to debian/rules:

.PHONY: override_dh_strip
override_dh_strip:
        dh_strip --dbg-package=giblib1-dbg

If you want to create more than one debug package, you need to do,

        dh_strip -pfoo --dbg-package=foo-dbg
        dh_strip -pbar --dbg-package=bar-dbg

Additional provisions

If you use dh automated install and you have only one binary package except the new -dbg package, make sure that the files that were previously automatically installed to debian/giblib1 are still installed there, e.g. by adding an override:

override_dh_auto_install:
        dh_auto_install --destdir=debian/giblib1

In that situation, it is also possible to make the debug package's documentation in /usr/share/doc/giblib1-dbg/ a symlink to /usr/share/doc/giblib1 using

override_dh_installdocs:
        dh_installdocs --link-doc=giblib1

CDBS

If you use CDBS, then just add the line:

DEB_DH_STRIP_ARGS := --dbg-package=giblib1-dbg


CategoryDeveloper CategoryDebugging CategoryPackaging