From Gentoo Wiki
Jump to:navigation Jump to:search
Debugging symbols are unrelated to USE=debug! The 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.

Don't strip symbols

As a first step, you may want to keep symbols in Executable and Linkable Format (ELF) files by the nostrip FEATURE.

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

Install debugging information

To install debugging information you can use the splitdebug feature. Furthermore, to install the source code you can activate the installsources feature which in turn requires the dev-util/debugedit. These features are integrated so they provide you with an environment where sys-devel/gdb can find both the debugging information and the sources and lets you fully use its interactive debugging features.

If nostrip is in the default FEATURES, splitdebug won't do anything, so disable it for debug-packages.

CFLAGS="${CFLAGS} -ggdb3"
FEATURES="${FEATURES} splitdebug compressdebug -nostrip"
FEATURES="${FEATURES} installsources"
root #emerge --ask dev-util/debugedit sys-devel/gdb

Then you can activate those new "environments" for packages you need the sources and/or debug info:

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

Now, if you debug program with gdb it will find the sources and debugging infos.

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.
= 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


  1. If /usr/src doesn't appear, check for any errors in build log.
  2. dev-util/debugedit (as of doesn't seem to support dwarf5 yet, so replacing -ggdb3 with -gdwarf-4 can help. Though adds the support.


Valgrind often needs debug information of the c-library to perform function redirection. For this, create the package debug environment described above and apply it for sys-libs/glibc.

root #FEATURES="splitdebug" emerge --oneshot sys-libs/glibc

You should also stop stripping symbols for all packages to get meaningful backtraces.

You may have an extended debugging experience if you also activate debug symbols for the program you want to check (for local projects, build them with -Og -ggdb).


It is possible that valgrind refuses to launch with an error containing the following.

valgrind:  A must-be-redirected function                        
valgrind:  whose name matches the pattern:      strlen          
valgrind:  in an object with soname matching: 

In this case, you need to add -fno-builtin-strlen to CFLAGS for glibc:

CFLAGS="${CFLAGS} -fno-builtin-strlen"
sys-libs/glibc strlen

See also