Debugging

From Gentoo Wiki
Jump to:navigation Jump to:search
Resources

This article provides general advice on how to enable debugging symbols and information.

Note
Debugging symbols are unrelated to USE=debug! This USE flag is usually for enabling assertions and other debug code paths within packages, it's very possible that they will result in failures even when everything works fine.

Installing debugging information for packages

Debug information is stripped by default to save space. This article explains how to enable it either selectively (preferred) or globally (expensive).

Note
Files will be larger with debug symbols:
CODE Comparison of Filesizes
## (debug symbols stripped)
3140 bytes
## (debug symbols enabled)
6374 bytes
## (-ggdb flag enabled)
19552 bytes

Per-package

Portage has several related feature flags:

  • To install debugging information, use the splitdebug feature.
  • To install the source code, activate the installsources feature, which requires dev-util/debugedit .

These features are integrated to provide an environment where dev-debug/gdb can find both the debugging information and the sources, allowing full use of its interactive debugging functionality.

If nostrip is in the default FEATURES, splitdebug won't do anything, so disable it when using splitdebug.

Note
See Project:Quality Assurance/Backtraces for where splitdebug symbols end up (typically /usr/lib/debug).

Setup

Create two files in /etc/portage/env: 

CFLAGS="${CFLAGS} -ggdb3"
CXXFLAGS="${CXXFLAGS} -ggdb3"
LDFLAGS="${LDFLAGS} -ggdb3"
# nostrip is disabled here because it negates splitdebug
FEATURES="${FEATURES} splitdebug compressdebug -nostrip"

FEATURES="${FEATURES} installsources"
root #emerge --ask dev-util/debugedit dev-debug/gdb

Then configure packages as required to use the newly-created environment (env) snippets above, depending on whether the source code and/or debugging symbols are needed: 

# Example package where you only want debug symbols
category/some-packagedebugsyms
# Example package where you want debug symbols and nice source lines in the debugger
# If in doubt, choose this one!
category/some-librarydebugsymsinstallsources

Now rebuild the package(s) that were configured in /etc/portage/package.env to get debug symbols:

root #emerge --ask --oneshot category/some-package category/some-library

Example of it working

Now, when debugging a program with gdb, it will find the sources and debugging information.

CODE Example gdb session for debugging dev-util/radare2 
% gdb --args r2 /bin/ls
Reading symbols from r2...Reading symbols from /usr/lib64/debug//usr/bin/radare2.debug...done.
done.
= gdb>> break main
Breakpoint 1 at 0x2e70: file radare2.c, line 372.
= gdb>> run
Starting program: /usr/bin/r2 /bin/ls
Breakpoint 1, main (argc=2, argv=0x7fffffffdd98, envp=0x7fffffffddb0) at radare2.c:372
372 int main(int argc, char **argv, char **envp) {
= gdb>> ...etc

Gdb finds debug symbols using the paths specified by Separate Debug Files and the .gnu_debuglink section of the ELF binary (try objdump -g <file>).

The file containing debug symbols must be readable for the user running the debugger. Often debug symbols are readable only to root. If for example you are debugging as a non-privileged user (say, because the program runs under X, and you are not running a privileged X server), you may need to adjust permissions:

root #chmod a+r /usr/lib/debug/...

Don't strip symbols globally

It's also possible to keep debugging information for Executable and Linkable Format (ELF) files via the nostrip FEATURE. This will lead to larger binaries on the system and may impact startup times slightly, as the debug information is stored within the main executable.

That way, all functions in the code will keep their name and sys-devel/gdb can then show names in a backtrace instead of function addresses only.

FILE /etc/portage/make.confKeep all ELF symbols in each binary
# Warning: if doing this system wide, a lower level of debug information like -g may be more appropriate
# to save memory during builds and disk space.
CFLAGS="${CFLAGS} -ggdb3"
CXXFLAGS="${CXXFLAGS} -ggdb3"
LDFLAGS="${LDFLAGS} -ggdb3"
FEATURES="nostrip"

Troubleshooting

  1. If /usr/src doesn't appear, check for any errors in build log.

Compression

FEATURES="compressdebug" enables compression of debug symbols in Portage. This may make loading debug info in gdb and such a bit slower but is worth it for most where the disk space saving is valuable. The default compression algorithm is zlib.

Newer versions of the toolchain can use zstd if configured for a better compression ratio.

sys-devel/dwz can also be used to optimize debugging info size with >=sys-apps/portage-3.0.62 with FEATURES="dedupdebug".

Valgrind

See Valgrind, a dynamic analysis tool which detects memory errors and memory leaks.

Eclass debugging

To enable eclass debugging, set the following in /etc/portage/make.conf:

FILE /etc/portage/make.conf
ECLASS_DEBUG_OUTPUT=on

See also

External resources