From: Johan Malm <jgm323@gmail.com>
Date: Thu, 26 May 2022 20:51:17 +0000 (+0100)
Subject: CONTRIBUTING.md: add notes on debugging
X-Git-Url: https://git.mdlowis.com/?a=commitdiff_plain;h=48e787ba102f042521a2e6ffb753dda6d08e1f14;p=proto%2Flabwc.git

CONTRIBUTING.md: add notes on debugging
---

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2ee15d82..6f6b5d81 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,6 +2,41 @@
 
 ## How to Contribute
 
+## Debugging
+
+There is no one-way-fits-all method for debugging, so you have to use your antennae and do some dective work.
+
+This section contains some approachies which may prove useful.
+
+If the compositor crashes, a good starting point is to produce a backtrace by building with ASAN/UBSAN:
+
+```
+meson -Db_sanitzise=address,undefined build/
+ninja -C build/
+```
+
+Get debug log with `labwc -d`. The log can be directed to a file with `labwc -d 2>log.txt`
+
+To see what is happening on the wayland protocol for a specific client, run it with environment variable `WAYLAND_DEBUG` set to 1, for example:
+
+```
+WAYLAND_DEBUG=1 foot
+```
+
+To see what the compositor is doing on the protocol run `labwc` nested (i.e. start labwc from a terminal in another instance of labwc or some other compositor) with `WAYLAND_DEBUG=server`. This filters out anything from clients.
+
+For wayland clients, you can get a live view of some useful info using [wlhax](https://git.sr.ht/~kennylevinsen/wlhax).
+
+If you think you've got a damage issue, you can run labwc like this: `WLR_SCENE_DEBUG_DAMAGE=highlight labwc` to get a visual indication of damage regions.
+
+For some types of bugs, it might be useful to find out which mesa driver (.so) you are using. This can be done with:
+
+```
+EGL_LOG_LEVEL=debug labwc 2>&1 | grep MESA-LOADER
+```
+
+You can also get some useful system info with [drm_info](https://github.com/ascent12/drm_info)
+
 ## Packaging
 
 Some distributions carry labwc in their repositories or user repositories.