From 60327320015bcf527a6a3ba76ebc171a2a23baa0 Mon Sep 17 00:00:00 2001
From: "Jeffrey C. Ollie" <jeff@ocjtech.us>
Date: Wed, 20 Aug 2025 09:03:48 -0500
Subject: [PATCH] contributing: add some notes about running valgrind

---
 CONTRIBUTING.md | 41 +++++++++++++++++++++++++++++++++++++++++
 flake.nix       | 13 +++++++++++++
 2 files changed, 54 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 880dc37d9..a525b5d54 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -133,6 +133,47 @@ pull request will be accepted with a high degree of certainty.
 
 See the [Contributor's Guide](po/README_CONTRIBUTORS.md) for more details.
 
+## Checking for Memory Leaks
+
+While Zig does an amazing job of finding and preventing memory leaks,
+Ghostty uses many third-party libraries that are written in C. Improper usage
+of those libraries or bugs in those libraries can cause memory leaks that
+Zig cannot detect by itself.
+
+### On Linux
+
+On Linux the recommended tool to check for memory leaks is Valgrind. We supply
+a file containing suppressions for false positives and known leaks in 3rd party
+libraries. The recommended way to run Valgrind is:
+
+```
+zig build -Dcpu=baseline -Doptimize=Debug
+valgrind \
+  --leak-check=full \
+  --num-callers=50 \
+  --suppressions=valgrind.supp \
+  ./zig-out/bin/ghostty
+```
+
+> [!NOTE]
+>
+> `-Dcpu=baseline` may not be needed depending on your CPU, but Valgrind cannot
+> deal with some instructions on certain newer CPUs so using `-Dcpu=baseline`
+> doesn't hurt.
+
+Any leaks found by Valgrind should be investigated.
+
+If you use Nix, you can use the following commands to run Valgrind so that you
+don't need to look up the Valgrind invocation every time:
+
+```
+nix develop
+nix run .#valgrind -- --config-default-files=true
+```
+
+You can add any Ghostty CLI arguments after the `--` and they will be passed to
+the invocation of Ghostty.
+
 ## Input Stack Testing
 
 The input stack is the part of the codebase that starts with a
diff --git a/flake.nix b/flake.nix
index 7cf58b27c..1c36b64ac 100644
--- a/flake.nix
+++ b/flake.nix
@@ -94,6 +94,19 @@
             x11-gnome = runVM ./nix/vm/x11-gnome.nix;
             x11-plasma6 = runVM ./nix/vm/x11-plasma6.nix;
             x11-xfce = runVM ./nix/vm/x11-xfce.nix;
+            valgrind = let
+              script = pkgs.writeShellScript "valgrind" ''
+                zig build -Dcpu=baseline -Doptimize=Debug
+                valgrind \
+                  --leak-check=full \
+                  --num-callers=50 \
+                  --suppressions=valgrind.supp \
+                  ./zig-out/bin/ghostty "$@"
+              '';
+            in {
+              type = "app";
+              program = "${script}";
+            };
           };
         }
         # Our supported systems are the same supported systems as the Zig binaries.