Debugging tips

Either if you are interested in helping refine down a bug or are developing for the project, this page documents some useful debugging knowledge for tracking down problems.

Checked builds

By default when using build.sh or buildall.sh, you will get a free build - aka, optimised with debug symbols stripped (or should be anyway).

To retain this information for more useful stack traces, pass the -d switch to produce a checked build. eg. build.sh -d shared/shell

Of course, it's useful to have this for all components, so in that case you should compile the project with buildall.sh -d . You will notice that the output will end up in chk/ rather than the usual fre/ (and post-install, running winver you will see (Debug) at the end of the build string).

gdb and debuginfod

I use gdb for debugging the project, it's pretty straight forward to use. If you're new, as an example of debugging explorer, do:

gdb explorer
(you are now in gdb's shell)
run

When you're done, quit.

debuginfod

On some distros like Fedora, you might get prompted about debuginfod - I would recommend accepting this because it will give you detailed stack trace and source map information for other libraries like GLib and WNCK etc. with no extra effort. Other distros like Debian, you'll need to install debuginfod yourself usually.

Cheatsheet

Some of the more common stuff:

• bt for backtrace
• up, down to move through the stack, up # where # is a number of frames to move
• break x set breakpoint, x can be a source file like icnvwbeh.c:251
• print x C-like statement to dump vars, like print *event
• continue, step, next resume execution, step into, step over respectively

Tracing against third-party libraries

Some bugs require a deeper dive into the libraries being called, like WNCK or GTK. In those cases, it's useful to compile and locally install debug builds of these libraries, and launch programs with them in use for additional tracing.

GTK3

Sometimes it can be unclear from GTK documentation why something has blown up or simply isn't working. In fact... the documentation on actually compiling GTK3 with debug options seems to be out of date funnily enough. This is my process for getting tracing out of GTK3:

• Clone down GTK from upstream git clone https://gitlab.gnome.org/GNOME/gtk
• Check what version of GTK you're on locally
  • Eg. for Debian, do apt list --installed | grep gtk-3 and see that it's something like 3.24.38
• Checkout the tag for that version, eg. git checkout 3.24.38
• Compile and install a debug build (slightly modified steps from GTK's INSTALL.md):
  • meson setup -Ddebug=true _build
    • Reconfigure existing build dir with meson setup --reconfigure -Ddebug=true _build
    • Double check the paths it says it's gonna use as an install dir, ensure they are pointing at /usr/local!
  • meson compile -C _build
  • sudo meson install -C _build
• Now run the program using the locally installed libs via LD_LIBRARY_PATH
  • Eg. LD_LIBRARY_PATH=/usr/local/lib/x86_64-linux-gnu GTK_DEBUG=actions explorer

Have a look at this page for GTK_DEBUG options for the various scopes: https://docs.gtk.org/gtk3/running.html#environment-variables

Testing for memory leaks - ASan

Any incoming code changes need to be ran through ASan to capture any potential memory leak bugs.

Because some third-party libraries may leak (intentionally or otherwise), it is worth defining suppressions to hide these and focus on bugs that are fixable within this codebase:

leak:libfontconfig.so

(NTS: Probably worth adding Chromium / GTK WebKit libs here because they also blast ASan output)

Note that some targets have ASan disabled - distros that use musl (Alpine Linux and Void Linux (musl variant)) and FreeBSD. See: https://github.com/rozniak/xfce-winxp-tc/blob/master/packaging/cmake-inc/common/CMakeLists.txt

With the suppressions config written somewhere, run a program like so:

LSAN_OPTIONS=suppressions=/home/coolguy/supp.txt explorer