Document -dbg-packages; #420540

git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@4650 313b444b-1b9f-4f58-a734-7bb04f332e8d

diff --git a/debian/changelog b/debian/changelog
index cd0321796633b4f2245bfbe3d2e276d8ecf4c69b..612a174b8ba25541fda07e05462146cb9fb2a629 100644 (file)
--- 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 <aba@gluck.debian.org>  Sat, 16 Jun 2007 11:41:41 -0600
 

diff --git a/developers-reference.sgml b/developers-reference.sgml
index ef971d84040496c08bd577fb4e34d5d41ff231e6..65597b3277a2f7ed2ab22d351cdd0875291904f8 100644 (file)
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -7,7 +7,7 @@
   <!ENTITY % dynamicdata  SYSTEM "dynamic.ent" > %dynamicdata;
 
   <!-- CVS revision of this document -->
-  <!ENTITY cvs-rev "$Revision: 1.318 $">
+  <!ENTITY cvs-rev "$Revision: 1.319 $">
 
   <!-- if you are translating this document, please notate the CVS
        revision of the original developer's reference in cvs-en-rev -->
@@ -5011,6 +5011,56 @@ build process.
        </p>
        </sect2>
     </sect1>
+    <sect1 id="bpp-dbg">
+        <heading>Best practices for debug packages</heading>
+       <p>
+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.
+       <p>
+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.
+       <p>
+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 <file>/usr/lib/debug/<em>path</em></file>,
+where <em>path</em> is the path to the executable or library. For example,
+debugging symbols for <file>/usr/bin/foo</file> go in
+<file>/usr/lib/debug/usr/bin/foo</file>, and
+debugging symbols for <file>/usr/lib/libfoo.so.1</file> go in
+<file>/usr/lib/debug/usr/lib/libfoo.so.1</file>.
+       <p>
+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. <manref name="objcopy" section="1"> explains in detail how this
+works.
+       <p>
+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.
+       <p>
+Note that the Debian package should depend on the package that it
+provides debugging symbols for, and this dependency should be versioned.
+For example:
+
+<example>
+Depends: libfoo-dbg (= ${binary:Version})
+</example>
 
 
       </sect>