From 55fe4ee4f35d7d587bd1c5f5b4adca6ce05a0027 Mon Sep 17 00:00:00 2001
From: Michael <50352631+michaelvanstraten@users.noreply.github.com>
Date: Fri, 1 Nov 2024 20:42:34 +0100
Subject: [PATCH] doc/manual: Add 'Debugging Nix' section (#11637)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* doc/manual: Add 'Debugging Nix' section

This commit adds a new 'Debugging Nix' section to the Nix manual. It provides instructions on how to build Nix with debug symbols and how to debug the Nix binary using debuggers like `lldb`.

Co-authored-by: Jörg Thalheim <Mic92@users.noreply.github.com>
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
---
 doc/manual/source/SUMMARY.md.in            |  1 +
 doc/manual/source/development/debugging.md | 62 ++++++++++++++++++++++
 2 files changed, 63 insertions(+)
 create mode 100644 doc/manual/source/development/debugging.md

diff --git a/doc/manual/source/SUMMARY.md.in b/doc/manual/source/SUMMARY.md.in
index eef7d189c..d7c312ae7 100644
--- a/doc/manual/source/SUMMARY.md.in
+++ b/doc/manual/source/SUMMARY.md.in
@@ -121,6 +121,7 @@
 - [Development](development/index.md)
   - [Building](development/building.md)
   - [Testing](development/testing.md)
+  - [Debugging](development/debugging.md)
   - [Documentation](development/documentation.md)
   - [CLI guideline](development/cli-guideline.md)
   - [JSON guideline](development/json-guideline.md)
diff --git a/doc/manual/source/development/debugging.md b/doc/manual/source/development/debugging.md
new file mode 100644
index 000000000..ce623110b
--- /dev/null
+++ b/doc/manual/source/development/debugging.md
@@ -0,0 +1,62 @@
+# Debugging Nix
+
+This section shows how to build and debug Nix with debug symbols enabled.
+
+## Building Nix with Debug Symbols
+
+In the development shell, set the `mesonBuildType` environment variable to `debug` before configuring the build:
+
+```console
+[nix-shell]$ export mesonBuildType=debugoptimized
+```
+
+Then, proceed to build Nix as described in [Building Nix](./building.md).
+This will build Nix with debug symbols, which are essential for effective debugging.
+
+## Debugging the Nix Binary
+
+Obtain your preferred debugger within the development shell:
+
+```console
+[nix-shell]$ nix-shell -p gdb
+```
+
+On macOS, use `lldb`:
+
+```console
+[nix-shell]$ nix-shell -p lldb
+```
+
+### Launching the Debugger
+
+To debug the Nix binary, run:
+
+```console
+[nix-shell]$ gdb --args ../outputs/out/bin/nix
+```
+
+On macOS, use `lldb`:
+
+```console
+[nix-shell]$ lldb -- ../outputs/out/bin/nix
+```
+
+### Using the Debugger
+
+Inside the debugger, you can set breakpoints, run the program, and inspect variables.
+
+```gdb
+(gdb) break main
+(gdb) run <arguments>
+```
+
+Refer to the [GDB Documentation](https://www.gnu.org/software/gdb/documentation/) for comprehensive usage instructions.
+
+On macOS, use `lldb`:
+
+```lldb
+(lldb) breakpoint set --name main
+(lldb) process launch -- <arguments>
+```
+
+Refer to the [LLDB Tutorial](https://lldb.llvm.org/use/tutorial.html) for comprehensive usage instructions.