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:
night:[eleni]~/igalia$ tree -d -L 1
and as you can guess in the first I store the sources and in the second the installation directories, something like that:
night:[eleni]~/igalia/install$ tree -d -L 2
│ ├── EGL
│ ├── GL
│ ├── GLES
│ ├── GLES2
│ ├── GLES3
│ ├── KHR
│ ├── libdrm
│ ├── libkms
│ ├── wpe-1.0
│ ├── wpe-fdo-1.0
│ └── wpe-webkit-1.0
│ ├── pkgconfig
│ ├── wpe-webkit-1.0
│ └── x86_64-linux-gnu
│ └── wpe-webkit-1.0
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: https://chromium.googlesource.com/angle/angle/+/HEAD/doc/DevSetup.md.
Then in a terminal I’ve set up the following environment variables (I do that with a script):
PS1='\[\033[0;32m\]\[\033[0m\033[0;32m\]\u\[\033[0;36m\] @ \[\033[0;36m\]\h \w\[\033[0;32m\]$(__git_ps1)\n\[\033[0;32m\]└─\[\033[0m\033[0;32m\] \$\[\033[0m\033[0;32m\] ▶\[\033[0m\] '
export CFLAGS="-O0 -ggdb"
export CXXFLAGS="-O0 -ggdb"
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
Step 2: getting the source code
I’ve checked out the code:
git clone https://chromium.googlesource.com/angle/angle
git checkout master
bootstrap.py 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:
use_debug_fission = false
strip_debug_info = false
enable_iterator_debugging = false
is_debug = true
use_dwarf5 = false
enable_dsyms = true
symbol_level = 2
dcheck_always_on = true
supports_llvm = false
Let’s see the more important ones:
strip_debug_infois required to avoid the debugging symbols redirection to other files!
use_dwarf5is 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_levelis set to 2 because I needed debugging symbols
supports_llvmmight 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
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:
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
See you next time!