doc/manual: Add 'Debugging Nix' section

[michaelvanstraten]

This PR 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.

Motivation

Currently, it's hard to get started with launching a debuggable instance of Nix. Building Nix with debug symbols requires knowledge of internal environment variables like mesonBuildType, which are not well-documented.

Context

Please see #11502.

Priorities and Process

Add 👍 to pull requests you find important.

The Nix maintainer team uses a GitHub project board to schedule and track reviews.

[edolstra]

FWIW, I use gdb, and if you're in a nix develop shell, you can just do

gdb --args nix ...

i.e. no need to give a full path to the nix binary.

[Mic92]

So meson actually installs it to /home/joerg/git/nix/out/bin which is not in PATH. But in that case we would also need to run ninjaInstallPhase. I think it makes sense that both build system choose different locations for our own sanity while we still have two and not put both in PATH. I actually prefer being explicit about the executable location, because it's less error prone for users following the tutorial. Let's say one person has exited the devshell to get a debugger and no longer has the PATH from it set, in that case they might run the debugger against the global installed nix, which is not good.

[michaelvanstraten]

Yes, I can confirm @Mic92 comment.

[michaelvanstraten]

I haven't figured out how to both debug the nix-daemon and nix when the debugging user is not the owner of /nix.

We could use the --store option to point to a local store but that would make debugging harder.

Is there a way to point nix to a different socket in terms of the daemon?

[Mic92]

I haven't figured out how to both debug the nix-daemon and nix when the debugging user is not the owner of /nix.

We could use the --store option to point to a local store but that would make debugging harder.

Is there a way to point nix to a different socket in terms of the daemon?

if you run as root than nix won't use the nix-daemon but will have similar privileges. This might be helpful for debugging. Otherwise, you would need to run two debugger sessions.
One that runs the nix-daemon as root and a second one with the actual command.
Debuggers are not very good at tracking multiple processes.

[michaelvanstraten]

if you run as root than nix won't use the nix-daemon but will have similar privileges.

Then the problem becomes that you can't reproduce the IPC interactions between the two.

[Mic92]

Usually you won't to need a debugger on both processes at the same time. You can just have the debugger on one process and than maybe verbose logging or strace on the other instance.

[michaelvanstraten]

Usually you won't to need a debugger on both processes at the same time. You can just have the debugger on one process and than maybe verbose logging or strace on the other instance.

I recently had the problem that the nix-daemon wasn't able to access an ssh key needed to access a remote builder. This was do to the fact that the key was password protected and the subprocess was not piped back to the nix client.

[ConnorBaker]

This PR has been very helpful as I've been working on #11767; I'd like to see it merged if that's at all possible.

[fricklerhandwerk]

I don't have the bandwidth to get into the semantics of the instructions, so no review on that aspect from me. Looks reasonable from a cursory glance though.

@michaelvanstraten Please use one line per sentence and resolve comments (shall the suggestions be applied?) and merge conflicts, then I'll hit the button.

[michaelvanstraten]

@fricklerhandwerk should all be resolved.

[fricklerhandwerk]

@michaelvanstraten thanks a lot. I have a few fixups, could you please allow reviewers to push to your PR branch?

[michaelvanstraten]

@fricklerhandwerk looks like it is enabled.

[fricklerhandwerk]

Hm, I get

To github.com:michaelvanstraten/nix.git
 ! [remote rejected]     michaelvanstraten/master -> michaelvanstraten/master (permission denied)
error: failed to push some refs to 'github.com:michaelvanstraten/nix.git'

Ah, maybe you inherited branch protection on your fork, and so I can't push to master specifically?

[michaelvanstraten]

Let me add you as a contributer.

[michaelvanstraten]

@fricklerhandwerk added you as a contributed at the fork.

[fricklerhandwerk]

Thanks everyone for your patience! @michaelvanstraten great addition to the documentation. Keep them coming. 🙂