Bug#907665: developers-reference: Section 6.7.9 about dbg packages outdated
Source: developers-reference
Severity: normal
Tags: patch
As we now have Automatic Debug Symbol package, I think most of the
section could be deleted and replaced to the references on the Wiki.
The attached patch does that…
--
tobi
-- System Information:
Debian Release: buster/sid
APT prefers unstable
APT policy: (500, 'unstable'), (500, 'testing'), (500, 'stable'), (1, 'experimental')
Architecture: amd64 (x86_64)
Kernel: Linux 4.17.0-3-amd64 (SMP w/8 CPU cores)
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), LANGUAGE=en_US:en (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled
diff --git a/best-pkging-practices.dbk b/best-pkging-practices.dbk
index 6f05ece..6a85f23 100644
--- a/best-pkging-practices.dbk
+++ b/best-pkging-practices.dbk
@@ -1795,58 +1795,32 @@ it in its official location).
<section id="bpp-dbg">
<title>Best practices for debug packages</title>
+
<para>
-A debug package is a package with a name ending in -dbg, that contains
-additional information that <command>gdb</command> can use. Since Debian binaries are stripped by
-default, debugging information, including function names and line numbers, is
-otherwise not available when running <command>gdb</command> on Debian binaries. Debug packages
-allow users who need this additional debugging information to install it,
-without bloating a regular system with the information.
-</para>
-<para>
-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.
-</para>
-<para>
-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 <command>gdb</command> can find and load on the fly
-when debugging a program or library. The convention in Debian is to keep these
-symbols in <filename>/usr/lib/debug/<replaceable>path</replaceable></filename>, where
-<replaceable>path</replaceable> is the path to the executable or library. For
-example, debugging symbols for <filename>/usr/bin/foo</filename> go in
-<filename>/usr/lib/debug/usr/bin/foo</filename>, and debugging symbols for
-<filename>/usr/lib/libfoo.so.1</filename> go in
-<filename>/usr/lib/debug/usr/lib/libfoo.so.1</filename>.
-</para>
-<para>
-The debugging symbols can be extracted from an object file using
-<command>objcopy --only-keep-debug</command>. Then the object file can be stripped,
-and <command>objcopy --add-gnu-debuglink</command> used to specify the path
-to the debugging symbol file.
-<citerefentry> <refentrytitle>objcopy</refentrytitle> <manvolnum>1</manvolnum>
-</citerefentry> explains in detail how this works.
-</para>
-<para>
-The <command>dh_strip</command> command in <systemitem role="package">debhelper</systemitem> supports creating debug
-packages, and can take care of using <command>objcopy</command> to separate
-out the debugging symbols for you. If your package uses <systemitem role="package">debhelper</systemitem>, all you
-need to do is call <command>dh_strip --dbg-package=libfoo-dbg</command>, and
-add an entry to <filename>debian/control</filename> for the debug package.
+A debug package is a package that contains additional information that
+<command>gdb</command> can use. Since Debian binaries are stripped by
+default, debugging information, including function names and line
+numbers, is otherwise not available when running <command>gdb</command>
+on Debian binaries. Debug packages allow users who need this additional
+debugging information to install it, without bloating a regular system
+with the information.
</para>
+
<para>
-Note that the debug package should depend on the package that it provides
-debugging symbols for, and this dependency should be versioned. For example:
+Previously is was up to a package's maintainer whether to create a debug
+package or not. You can still find those manually generated debug
+packages, whose package names generally ended with -dbg.
+
+However, since end of 2015 manually generating dbg packages are
+depreciated and has been replaced largely by automatic debug symbol
+generation, which will generate packages with names ending with -dbgsym.
+
+If you want to migrate your legacy -dbg package, please read
+<ulink url="https://wiki.debian.org/AutomaticDebugPackages";> here </ulink>,
+if you want to use the dbgsym packages, you can find instructions
+<ulink url="https://wiki.debian.org/HowToGetABacktrace";> here </ulink>.
+
</para>
-<screen>
-Depends: libfoo (= ${binary:Version})
-</screen>
</section>
<section id="bpp-meta">
<title>Best practices for meta-packages</title>
Reply to: