From febf6dc086823a0945820d6d99b07ecd42b32a54 Mon Sep 17 00:00:00 2001 From: aba Date: Sat, 16 Jun 2007 19:15:43 +0000 Subject: [PATCH] Document -dbg-packages; #420540 git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@4650 313b444b-1b9f-4f58-a734-7bb04f332e8d --- debian/changelog | 1 + developers-reference.sgml | 52 ++++++++++++++++++++++++++++++++++++++- 2 files changed, 52 insertions(+), 1 deletion(-) diff --git a/debian/changelog b/debian/changelog index cd03217..612a174 100644 --- a/debian/changelog +++ b/debian/changelog @@ -9,6 +9,7 @@ developers-reference (3.3.9) unstable; urgency=low * Debconf error templates no longer discouraged. Thanks, Christian Perrier. Closes: #427832 * Keyring now uses RT. Closes: #428846 + * Document -dbg-packages within BPs. Thanks, Joey Hess. Closes: #420540 -- Andreas Barth Sat, 16 Jun 2007 11:41:41 -0600 diff --git a/developers-reference.sgml b/developers-reference.sgml index ef971d8..65597b3 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -7,7 +7,7 @@ %dynamicdata; - + @@ -5011,6 +5011,56 @@ build process.

+ + Best practices for debug packages +

+A debug package is a package with a name ending in "-dbg", that contains +additional information that gdb can use. Since Debian binaries are +stripped by default, debugging information, including function names and +line numbers, is otherwise not available when running gdb on Debian binaries. +Debug packages allow users who need this additional debugging information to +install it, without bloating a regular system with the information. +

+It is up to a package's maintainer whether to create a debug package or +not. Maintainers are encouraged to create debug packages for library +packages, since this can aid in debugging many programs linked to a +library. In general, debug packages do not need to be added for all +programs; doing so would bloat the archive. But if a maintainer finds +that users often need a debugging version of a program, it can be +worthwhile to make a debug package for it. Programs that are core +infrastructure, such as apache and the X server are also good candidates +for debug packages. +

+Some debug packages may contain an entire special debugging build of a +library or other binary, but most of them can save space and build time +by instead containing separated debugging symbols that gdb can find and +load on the fly when debugging a program or library. The convention in +Debian is to keep these symbols in /usr/lib/debug/path, +where path is the path to the executable or library. For example, +debugging symbols for /usr/bin/foo go in +/usr/lib/debug/usr/bin/foo, and +debugging symbols for /usr/lib/libfoo.so.1 go in +/usr/lib/debug/usr/lib/libfoo.so.1. +

+The debugging symbols can be extracted from an object file using +"objcopy --only-keep-debug". Then the object file can be stripped, and +"objcopy --add-gnu-debuglink" used to specify the path to the debugging +symbol file. explains in detail how this +works. +

+The dh_strip command in debhelper supports creating debug packages, and +can take care of using objcopy to separate out the debugging symbols for +you. If your package uses debhelper, all you need to do is call +"dh_strip --dbg-package=libfoo-dbg", and add an entry to debian/control +for the debug package. +

+Note that the Debian package should depend on the package that it +provides debugging symbols for, and this dependency should be versioned. +For example: + + +Depends: libfoo-dbg (= ${binary:Version}) + -- 2.30.2