diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in index eef7d189c..d7c312ae7 100644 --- a/doc/manual/src/SUMMARY.md.in +++ b/doc/manual/src/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/src/development/debugging.md b/doc/manual/src/development/debugging.md new file mode 100644 index 000000000..ba0593055 --- /dev/null +++ b/doc/manual/src/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.