Table Of Contents

Previous topic

“Gotchas” and FAQs

Next topic

Working with the testsuite

This Page

Debugging GCC

The gcc binary is actually a relatively small “driver” program, which parses some command-line options, and then invokes one or more other programs to do the real work.

Consider compiling a simple hello world C program:

#include <stdio.h>

int main (int argc, const char *argv[])
   printf ("Hello world\n");
   return 0;

to generate an a.out binary:

$ gcc hello.c
$ ./a.out
Hello world

Internally, the driver will invoke cc1 (the C compiler), which converts the .c code to a .s assembler file. Assuming this succeeds the driver will typically then invoke as (the assembler), then the linker.

Given that, how do we debug the C compiler? The easier way is to add -wrapper gdb,--args to the gcc command-line:

# Invoke "cc1" (and "as", etc) under gdb:
$ gcc hello.c -wrapper gdb,--args

The gcc driver will then invoke cc1 under gdb, and you can set breakpoints, and step through the code.


If you ever need to debug the driver itself, you can simply run it under gdb in the normal way:

# Invoke the "gcc" driver under gdb:
$ gdb --args gcc hello.c

I find myself doing this much less frequently than the -wrapper gdb,--args invocation for debugging cc1 though.

You can invoke other debugging programs this way, for example, valgrind:

# Invoke "cc1" (and "as", etc) under valgrind:
$ gcc hello.c -wrapper valgrind


For good results under valgrind, it’s best to configure your build of gcc with --enable-valgrind-annotations, which automatically suppresses various known false positives.

Support scripts for gdb

The source tree contains two support scripts that significantly improve the debugging experience within gdb, but some setup is required.

gcc/configure (from automatically generates a .gdbinit within the gcc subdirectory of the build directory, and when run by gdb.

This should be automatically detected and run by gdb. However, you may see a message from gdb of the form:

"path-to-build/gcc/.gdbinit" auto-loading has been declined by your `auto-load safe-path'
as a protection against untrustworthy python scripts. See

The fix is to mark the paths of the build/gcc directory as trustworthy. An easy way to do so is by adding the following to your ~/.gdbinit script:

add-auto-load-safe-path /absolute/path/to/build/gcc

for the build directories for your various checkouts of gcc.

If it’s working, you should see the message:

Successfully loaded GDB hooks for GCC

as gdb starts up.

The generated .gdbinit script loads two files:

  1. gcc/ contains useful commands in gdb‘s own language, sets up useful breakpoints, and skipping of some very heavily-used inline functions.
  2. gcc/ injects useful Python code into gdb, for pretty-printing important data types.

See the links above for more information.