Setting up to debug ANGLE with GDB (on Linux)

ANGLE is an EGL/GLES2 implementation on top of other graphics APIs. It is mainly used in systems that lack a native GLES2/GLES3 driver and in some browsers for example Chromium. As recently, I’ve used it for some browsers related work in Igalia‘s WebKit team (more on that coming soon) and had to set it up for debugging with GDB, I’d like to share the few extra settings and the configuration I’ve used to be able to use GDB and step inside the ANGLE API calls to examine the underlying driver API calls, when possible, while I was experimenting with ANGLE-based test programs.

1. Environment (skip if you are using proprietary drivers)

As I’ve mentioned in my previous post on building WebKit, when I need to debug a browser’s or browser engine’s graphics, I am doing so in a machine with open source mesa drivers, and I build mesa myself to be able to see all the graphics API errors, assertions etc with GDB.

If you are using proprietary drivers you don’t need this set up!

So, I am using the following directory tree for my projects:

and as you can guess in the first I store the sources and in the second the installation directories, something like that:

So, before anything else I’ve built libdrm and mesa with installation directory my install directory above (you can see the EGL, GL, GLES2, etc directories under include) and then I’ve downloaded the ANGLE source code following these instructions:

Then in a terminal I’ve set up the following environment variables (I do that with a script):

on Intel I am using some extra flags from mesa website:

2. Build instructions (modifications)

There are build instructions for building ANGLE here but I didn’t follow them so closely because I needed some extra settings, I’ll explain below. My steps:

Step 1: depot_tools

I’ve set up the depot tools following the instructions here.
Then, I checked that they are in my path ($PATH).
Running the script of section 1 exports the PATH to contain the depot_tools path.

Step 2: getting the source code

I’ve checked out the code:

* should be used with python2 not python3! (strings differ!).
* gclient sync the first time or gclient update when it’s not the first run

Step 3: installing dependencies

The first time I ran it on (a Debian-based) Linux I also ran the script:
This script, installs some required packages using apt from repos.

Step 4: configuring/building angle

ANGLE uses the gn tool to generate the ninja files. You can run:
gn args out/Debug to set the configuration arguments.

I first tried to compile ANGLE using the default gn arguments but I couldn’t get GDB to step into the ANGLE functions. The main problem was that the debugging symbols are by default redirected in separate files where GDB can’t find them.

I’ve finally used the following combination of gn args to be able to use them as usual:

Let’s see the more important ones:

  • strip_debug_info is required to avoid the debugging symbols redirection to other files!
  • use_dwarf5 is set to false because dwarf5 is not fully supported on GDB and there were errors when I was trying to step into many stack levels (I think false is the default value though)
  • symbol_level is set to 2 because I needed debugging symbols
  • supports_llvm might not be required to be false, I just found that gcc worked well with ANGLE, and so I disabled it.

after that I ran:
ninja -C out/Debug -jN, (where N is the number of processors), to build ANGLE in angle/out/Debug directory.

3. GDB settings

Building ANGLE using the args above was not enough for GDB to find the dynamically loaded ANGLE functions of my programs. As I hadn’t installed ANGLE in any of the system directories or the directory I use for all custom installations (see LD_LIBRARY_PATH in section 1), I needed to make GDB aware of where the ANGLE libraries, whose calls I would dynamically open at execution, were located.

Before setting the paths I made GDB aware that my example program that uses ANGLE is a safe path to load… I’ve edited my global ~/.gdbinit to contain this line:
add-auto-load-safe-path /home/eleni/igalia/code/<my_angle_program>/.gdbinit

Then, I edited the program’s gdbinit and added the line:
set directories /home/eleni/igalia/code/angle/out/Debug

to tell GDB to include ANGLE’s directory in its known directories.
After that I could set a break point in each ANGLE call’s line and step into the call like with every other call.


If you are using CCLS (I am using it with Vim) then you might want a compile_commands.json. You can generate one from gn with this command:

└─ $ β–Ά gn args out/Debug/ --export-compile-commands


[1]: ANGLE build instructions
[2]: GDB source path documentation
[3]: GN reference

See you next time!

Leave a Reply

Your email address will not be published. Required fields are marked *