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:
|
1 2 3 4 |
night:[eleni]~/igalia$ tree -d -L 1 . ├── code └── install |
and as you can guess in the first I store the sources and in the second the installation directories, something like that:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
night:[eleni]~/igalia/install$ tree -d -L 2 . ├── bin ├── include │ ├── EGL │ ├── GL │ ├── GLES │ ├── GLES2 │ ├── GLES3 │ ├── KHR │ ├── libdrm │ ├── libkms │ ├── wpe-1.0 │ ├── wpe-fdo-1.0 │ └── wpe-webkit-1.0 ├── lib │ ├── pkgconfig │ ├── wpe-webkit-1.0 │ └── x86_64-linux-gnu ├── libexec │ └── wpe-webkit-1.0 └── share ├── drirc.d ├── glvnd ├── libdrm ├── man └── vulkan |
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):
|
1 2 3 4 5 6 7 8 9 10 11 |
#!/bin/bash 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\] ' PS1="[isolated] $PS1" export PATH=$PATH:$HOME/igalia/install/bin:~/igalia/code/depot_tools export LD_LIBRARY_PATH=$HOME/igalia/install/lib:$HOME/igalia/install/lib/x86_64-linux-gnu:$HOME/igalia/code/angle/out/Debug export XDG_DATA_DIRS=$XDG_DATA_DIRS:$HOME/igalia/install/share export LIBGL_DRIVERS_PATH=$HOME/igalia/install/lib/x86_64-linux-gnu/dri/ export MESA_DEBUG=1 export EGL_LOG_LEVEL=info export CFLAGS="-O0 -ggdb" export CXXFLAGS="-O0 -ggdb" |
on Intel I am using some extra flags from mesa website:
https://docs.mesa3d.org/envvars.html
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:
|
1 2 3 4 5 |
git clone https://chromium.googlesource.com/angle/angle cd angle python2 scripts/bootstrap.py gclient sync git checkout master |
Notes:
* 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:
./build/install-build-deps.sh
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:
|
1 2 3 4 5 6 7 8 9 |
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 symbolssupports_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 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.
4. CCLS
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
Links
[1]: ANGLE build instructions
[2]: GDB source path documentation
[3]: GN reference
See you next time!
