Debugging

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

<syntaxhighlight lang="bash">FEATURES="nostrip"</syntaxhighlight>

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.

FILE /etc/portage/env/debugsyms

<syntaxhighlight lang="bash">CFLAGS="${CFLAGS} -ggdb"
CXXFLAGS="${CXXFLAGS} -ggdb"
FEATURES="${FEATURES} splitdebug compressdebug -nostrip"</syntaxhighlight>

FILE /etc/portage/env/installsources

<syntaxhighlight lang="bash">FEATURES="${FEATURES} installsources"</syntaxhighlight>

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:

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

Valgrind

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

Troubleshooting

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:   ld-linux-x86-64.so.2

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

FILE /etc/portage/env/strlen

<syntaxhighlight lang="bash">CFLAGS="${CFLAGS} -fno-builtin-strlen"</syntaxhighlight>