From 3a8726f953de345ea37e312a504aa56fc5f321fa Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Thu, 1 May 2025 17:13:49 +0100
Subject: [PATCH] Notes on using gdb

... because I always forget how to do this, and it takes me ages to remember.
---
 docs/SUMMARY.md |  3 ++-
 docs/gdb.md     | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 48 insertions(+), 1 deletion(-)
 create mode 100644 docs/gdb.md

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 316602e..e476b2f 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -2,10 +2,11 @@
 
 - [Introduction](../README.md)
 
-# Build
+# Build/Debug
 
 - [Native Node modules](native-node-modules.md)
 - [Windows requirements](windows-requirements.md)
+- [Using gdb](gdb.md)
 
 # Distribution
 
diff --git a/docs/gdb.md b/docs/gdb.md
new file mode 100644
index 0000000..471cd24
--- /dev/null
+++ b/docs/gdb.md
@@ -0,0 +1,46 @@
+# Using gdb against Element-Desktop
+
+Occasionally it is useful to be able to connect to a running Element-Desktop
+with [`gdb`](https://sourceware.org/gdb/), or to analayze a coredump. For this,
+you will need debug symbols.
+
+1. If you don't already have the right version of Element-Desktop (eg because
+   you are analyzing someone else's coredump), download and unpack the tarball
+   from https://packages.element.io/desktop/install/linux/. If it was a
+   nightly, your best bet may be to download the deb from
+   https://packages.element.io/debian/pool/main/e/element-nightly/ and unpack
+   it.
+2. Figure out which version of Electron your Element-Desktop is based on. The
+   best way to do this is to figure out the version of Element-Desktop, then
+   look at
+   [`yarn.lock`](https://github.com/element-hq/element-desktop/blob/develop/yarn.lock)
+   for the corresponding version. There should be an entry starting
+   `electron@`, and under it a `version` line: this will tell you the version
+   of Electron that was used for that version of Element-Desktop.
+
+3. Go to [Electron's releases page](https://github.com/electron/electron/releases/)
+   and find the version you just identified. Under "Assets", download
+   `electron-v<version>-linux-x64-debug.zip` (or, the -debug zip corresponding to your
+   architecture).
+
+4. The debug zip has a structure like:
+
+    ```
+    .
+    ├── debug
+    │   ├── chrome_crashpad_handler.debug
+    │   ├── electron.debug
+    │   ├── libEGL.so.debug
+    │   ├── libffmpeg.so.debug
+    │   ├── libGLESv2.so.debug
+    │   └── libvk_swiftshader.so.debug
+    ├── LICENSE
+    ├── LICENSES.chromium.html
+    └── version
+    ```
+
+    Take all the contents of `debug`, and copy them into the Element-Desktop directory,
+    so that `electron.debug` is alongside the `element-desktop-nightly` executable.
+
+5. You now have a thing you can gdb as normal, either as `gdb --args element-desktop-nightly`, or
+   `gdb element-desktop-nightly core`.