7.3 Installing Debugging Files

Program binaries, as produced by the GCC compilers for instance, are typically written in the ELF format, with a section containing debugging information. Debugging information is what allows the debugger, GDB, to map binary code to source code; it is required to debug a compiled program in good conditions.

The problem with debugging information is that is takes up a fair amount of disk space. For example, debugging information for the GNU C Library weighs in at more than 60 MiB. Thus, as a user, keeping all the debugging info of all the installed programs is usually not an option. Yet, space savings should not come at the cost of an impediment to debugging—especially in the GNU system, which should make it easier for users to exert their computing freedom (see GNU Distribution).

Thankfully, the GNU Binary Utilities (Binutils) and GDB provide a mechanism that allows users to get the best of both worlds: debugging information can be stripped from the binaries and stored in separate files. GDB is then able to load debugging information from those files, when they are available (see Separate Debug Files in Debugging with GDB).

The GNU distribution takes advantage of this by storing debugging information in the lib/debug sub-directory of a separate package output unimaginatively called debug (see Packages with Multiple Outputs). Users can choose to install the debug output of a package when they need it. For instance, the following command installs the debugging information for the GNU C Library and for GNU Guile:

guix package -i glibc:debug guile:debug

GDB must then be told to look for debug files in the user’s profile, by setting the debug-file-directory variable (consider setting it from the ~/.gdbinit file, see Startup in Debugging with GDB):

(gdb) set debug-file-directory ~/.guix-profile/lib/debug

From there on, GDB will pick up debugging information from the .debug files under ~/.guix-profile/lib/debug.

In addition, you will most likely want GDB to be able to show the source code being debugged. To do that, you will have to unpack the source code of the package of interest (obtained with guix build --source, see Invoking guix build), and to point GDB to that source directory using the directory command (see directory in Debugging with GDB).

The debug output mechanism in Guix is implemented by the gnu-build-system (see Build Systems). Currently, it is opt-in—debugging information is available only for those packages whose definition explicitly declares a debug output. This may be changed to opt-out in the future, if our build farm servers can handle the load. To check whether a package has a debug output, use guix package --list-available (see Invoking guix package).