Debugging

Resources

This article provides general advice on how to enable debugging.

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 sys-devel/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.

Create two files in /etc/portage/env:

FILE /etc/portage/env/debugsyms

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

FILE /etc/portage/env/installsources

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:

FILE /etc/portage/package.env

category/some-package debugsyms
category/some-library debugsyms installsources

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

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

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"
FEATURES="nostrip"

Troubleshooting

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 compession ratio.

sys-devel/dwz can also be used to optimize debugging info size, although Portage does not yet have dwz integration (tracked in bug #906368).

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

External resources