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>
