5.6 Debugging failing Nix builds

A package compiles for an hour, fails, you change one line, and wait another hour for the next error. This lesson shows the debugging tools Nix gives you for failing builds: --keep-failed, --debug, the NIX_DEBUG variable, and a hook that lets you log into the sandbox itself. Each one answers a different question, and you see all of them on a build with a deliberately injected failure.

In this video

• Keeping the build directory after a failure, so you can inspect the files exactly as the crash left them
• Finding out which phase a silent, seemingly stuck build is hanging in
• Making the compiler and linker wrappers verbose: every flag, include folder, and link path that really reaches the tools, gold for linker errors and missing headers
• The breakpoint hook: freezing a failed build and attaching a shell inside the still running sandbox to poke around
• A plain bash trick for when you need to watch the build script variable by variable

After this lesson

The next time a build fails deep inside its phases, you stop rereading logs and guessing. You inspect the leftovers, attach to the sandbox, and rerun steps by hand until you find it.

Links:

• https://nixos.org/manual/nixpkgs/stable/#var-stdenv-NIX_DEBUG
• https://nixos.org/manual/nixpkgs/stable/#breakpointhook