From 3e083986baccbe62c841277682ae135a2b1bab1b Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Fri, 4 Oct 2024 12:41:51 +0200 Subject: [PATCH 1/7] 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`. Fixes #11502 --- doc/manual/source/SUMMARY.md.in | 1 + doc/manual/source/development/debugging.md | 61 ++++++++++++++++++++++ 2 files changed, 62 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 eef7d189cbb..d7c312ae783 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 00000000000..ba0593055cd --- /dev/null +++ b/doc/manual/source/development/debugging.md @@ -0,0 +1,61 @@ +# Debugging Nix + +This section provides instructions on how to build and debug Nix with debug +symbols enabled. It assumes you are using Nix with the [`flakes`] and +[`nix-command`] experimental features enabled. + +[`flakes`]: @docroot@/development/experimental-features.md#xp-feature-flakes +[`nix-command`]: @docroot@/development/experimental-features.md#xp-nix-command + +## Building Nix with Debug Symbols + +First, ensure you have set up the development environment as described in the +[building documentation](./building.md). + +In the development shell, set the `mesonBuildType` environment variable to +`debug` before configuring the build: + +```console +[nix-shell]$ export mesonBuildType=debug +``` + +Then, configure and build Nix: + +```console +[nix-shell]$ mesonConfigurePhase +[nix-shell]$ ninjaBuildPhase +``` + +This will build Nix with debug symbols, which are essential for effective +debugging. + +## Debugging the Nix Binary + +### Installing a Debugger + +Install your preferred debugger within the development shell. For example, to +install `lldb`: + +```console +[nix-shell]$ nix shell nixpkgs#lldb +``` + +### Launching the Debugger + +To debug the Nix binary you just built: + +```console +[nix-shell]$ lldb -- ./subprojects/nix/nix +``` + +### Using the Debugger + +Inside `lldb`, you can set breakpoints, run the program, and inspect variables: + +```lldb +(lldb) breakpoint set --name main +(lldb) process launch -- +``` + +Refer to the [LLDB Tutorial](https://lldb.llvm.org/use/tutorial.html) for +comprehensive usage instructions. From 91f1c1ebf6e655ac6f11f96ca356754a17f6735b Mon Sep 17 00:00:00 2001 From: Michael <50352631+michaelvanstraten@users.noreply.github.com> Date: Fri, 1 Nov 2024 12:08:20 +0100 Subject: [PATCH 2/7] Update doc/manual/src/development/debugging.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jörg Thalheim --- doc/manual/source/development/debugging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/manual/source/development/debugging.md b/doc/manual/source/development/debugging.md index ba0593055cd..25b6b4b48b0 100644 --- a/doc/manual/source/development/debugging.md +++ b/doc/manual/source/development/debugging.md @@ -16,7 +16,7 @@ In the development shell, set the `mesonBuildType` environment variable to `debug` before configuring the build: ```console -[nix-shell]$ export mesonBuildType=debug +[nix-shell]$ export mesonBuildType=debugoptimized ``` Then, configure and build Nix: From f3e9c235c95d45f7eb3ac90d4ef40eba58a8d126 Mon Sep 17 00:00:00 2001 From: Michael <50352631+michaelvanstraten@users.noreply.github.com> Date: Fri, 1 Nov 2024 12:23:48 +0100 Subject: [PATCH 3/7] Update doc/manual/src/development/debugging.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jörg Thalheim --- doc/manual/source/development/debugging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/manual/source/development/debugging.md b/doc/manual/source/development/debugging.md index 25b6b4b48b0..1fcb09c5eda 100644 --- a/doc/manual/source/development/debugging.md +++ b/doc/manual/source/development/debugging.md @@ -23,7 +23,7 @@ Then, configure and build Nix: ```console [nix-shell]$ mesonConfigurePhase -[nix-shell]$ ninjaBuildPhase +[nix-shell]$ ninjaInstallPhase ``` This will build Nix with debug symbols, which are essential for effective From ba63f19dd29850d2dae481cde04c2a4fb563a88a Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Fri, 1 Nov 2024 18:20:14 +0100 Subject: [PATCH 4/7] Use newline for each sentence --- doc/manual/source/development/debugging.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/manual/source/development/debugging.md b/doc/manual/source/development/debugging.md index 1fcb09c5eda..89ba9a2f8e6 100644 --- a/doc/manual/source/development/debugging.md +++ b/doc/manual/source/development/debugging.md @@ -1,8 +1,9 @@ # Debugging Nix This section provides instructions on how to build and debug Nix with debug -symbols enabled. It assumes you are using Nix with the [`flakes`] and -[`nix-command`] experimental features enabled. +symbols enabled. +It assumes you are using Nix with the [`flakes`] and [`nix-command`] +experimental features enabled. [`flakes`]: @docroot@/development/experimental-features.md#xp-feature-flakes [`nix-command`]: @docroot@/development/experimental-features.md#xp-nix-command From 518759668ebd8339eea51212d1f68bfdfa6a0746 Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Fri, 1 Nov 2024 18:20:43 +0100 Subject: [PATCH 5/7] Recomend gdb by default for linux --- doc/manual/source/development/debugging.md | 29 +++++++++++++++++++--- 1 file changed, 25 insertions(+), 4 deletions(-) diff --git a/doc/manual/source/development/debugging.md b/doc/manual/source/development/debugging.md index 89ba9a2f8e6..8925b58f257 100644 --- a/doc/manual/source/development/debugging.md +++ b/doc/manual/source/development/debugging.md @@ -34,8 +34,13 @@ debugging. ### Installing a Debugger -Install your preferred debugger within the development shell. For example, to -install `lldb`: +Install your preferred debugger within the development shell. + +```console +[nix-shell]$ nix shell nixpkgs#gdb +``` + +For macOS systems, use `lldb`: ```console [nix-shell]$ nix shell nixpkgs#lldb @@ -43,7 +48,13 @@ install `lldb`: ### Launching the Debugger -To debug the Nix binary you just built: +To debug the Nix binary you just run: + +```console +[nix-shell]$ gdb --args ./subprojects/nix/nix +``` + +#### On macOS: ```console [nix-shell]$ lldb -- ./subprojects/nix/nix @@ -51,7 +62,17 @@ To debug the Nix binary you just built: ### Using the Debugger -Inside `lldb`, you can set breakpoints, run the program, and inspect variables: +Inside the debugger, you can set breakpoints, run the program, and inspect variables. + +```gdb +(gdb) break main +(gdb) run +``` + +Refer to the [GDB Documentation](https://www.gnu.org/software/gdb/documentation/) for +comprehensive usage instructions. + +#### Using LLDB (macOS): ```lldb (lldb) breakpoint set --name main From 367b1cd718be2f0dec71ed0f1aab59615a0c5cbe Mon Sep 17 00:00:00 2001 From: Michael van Straten Date: Fri, 1 Nov 2024 18:34:19 +0100 Subject: [PATCH 6/7] Point to output after rebase --- doc/manual/source/development/debugging.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/manual/source/development/debugging.md b/doc/manual/source/development/debugging.md index 8925b58f257..ecf3fd1f22c 100644 --- a/doc/manual/source/development/debugging.md +++ b/doc/manual/source/development/debugging.md @@ -51,13 +51,14 @@ For macOS systems, use `lldb`: To debug the Nix binary you just run: ```console -[nix-shell]$ gdb --args ./subprojects/nix/nix +[nix-shell]$ gdb --args ../outputs/out/bin/nix + ``` #### On macOS: ```console -[nix-shell]$ lldb -- ./subprojects/nix/nix +[nix-shell]$ lldb -- ../outputs/out/bin/nix ``` ### Using the Debugger From f612e55d0bef174918be8839131c6c2cf0575886 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Fri, 1 Nov 2024 19:34:17 +0100 Subject: [PATCH 7/7] simplify text, also no need for experimental features --- doc/manual/source/development/debugging.md | 48 ++++++---------------- 1 file changed, 13 insertions(+), 35 deletions(-) diff --git a/doc/manual/source/development/debugging.md b/doc/manual/source/development/debugging.md index ecf3fd1f22c..ce623110b36 100644 --- a/doc/manual/source/development/debugging.md +++ b/doc/manual/source/development/debugging.md @@ -1,61 +1,41 @@ # Debugging Nix -This section provides instructions on how to build and debug Nix with debug -symbols enabled. -It assumes you are using Nix with the [`flakes`] and [`nix-command`] -experimental features enabled. - -[`flakes`]: @docroot@/development/experimental-features.md#xp-feature-flakes -[`nix-command`]: @docroot@/development/experimental-features.md#xp-nix-command +This section shows how to build and debug Nix with debug symbols enabled. ## Building Nix with Debug Symbols -First, ensure you have set up the development environment as described in the -[building documentation](./building.md). - -In the development shell, set the `mesonBuildType` environment variable to -`debug` before configuring the build: +In the development shell, set the `mesonBuildType` environment variable to `debug` before configuring the build: ```console [nix-shell]$ export mesonBuildType=debugoptimized ``` -Then, configure and build Nix: - -```console -[nix-shell]$ mesonConfigurePhase -[nix-shell]$ ninjaInstallPhase -``` - -This will build Nix with debug symbols, which are essential for effective -debugging. +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 -### Installing a Debugger - -Install your preferred debugger within the development shell. +Obtain your preferred debugger within the development shell: ```console -[nix-shell]$ nix shell nixpkgs#gdb +[nix-shell]$ nix-shell -p gdb ``` -For macOS systems, use `lldb`: +On macOS, use `lldb`: ```console -[nix-shell]$ nix shell nixpkgs#lldb +[nix-shell]$ nix-shell -p lldb ``` ### Launching the Debugger -To debug the Nix binary you just run: +To debug the Nix binary, run: ```console [nix-shell]$ gdb --args ../outputs/out/bin/nix - ``` -#### On macOS: +On macOS, use `lldb`: ```console [nix-shell]$ lldb -- ../outputs/out/bin/nix @@ -70,15 +50,13 @@ Inside the debugger, you can set breakpoints, run the program, and inspect varia (gdb) run ``` -Refer to the [GDB Documentation](https://www.gnu.org/software/gdb/documentation/) for -comprehensive usage instructions. +Refer to the [GDB Documentation](https://www.gnu.org/software/gdb/documentation/) for comprehensive usage instructions. -#### Using LLDB (macOS): +On macOS, use `lldb`: ```lldb (lldb) breakpoint set --name main (lldb) process launch -- ``` -Refer to the [LLDB Tutorial](https://lldb.llvm.org/use/tutorial.html) for -comprehensive usage instructions. +Refer to the [LLDB Tutorial](https://lldb.llvm.org/use/tutorial.html) for comprehensive usage instructions.