stdenv: add no-broken-symlinks hook

[ConnorBaker]

Adds a setup hook which checks for broken symlinks; a symlink is considered broken if it's dangling (target doesn't exist) or reflexive (it refers to itself).

In my experience, outputs with broken symlinks are generally errors, and so we should provide a hook which can catch and report them.

By setting allowDanglingSymlinks or allowReflexiveSymlinks the hook can be configured to allow symlinks with non-existent targets or symlinks which are reflexive, respectively.

The hook can be disabled entirely by setting dontCheckForBrokenSymlinks.

Things done

• Built on platform(s)
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• For non-Linux: Is sandboxing enabled in nix.conf? (See Nix manual)
  • sandbox = relaxed
  • sandbox = true
• Tested, as applicable:
  • NixOS test(s) (look inside nixos/tests)
  • and/or package tests
  • or, for functions and "core" functionality, tests in lib/tests or pkgs/test
  • made sure NixOS tests are linked to the relevant packages
• Tested compilation of all packages that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage
• Tested basic functionality of all binary files (usually in ./result/bin/)
• 25.05 Release Notes (or backporting 24.11 and 25.05 Release notes)
  • (Package updates) Added a release notes entry if the change is major or breaking
  • (Module updates) Added a release notes entry if the change is significant
  • (Module addition) Added a release notes entry if adding a new NixOS module
• Fits CONTRIBUTING.md.

---

Add a 👍 reaction to pull requests you find important.

[K900]

Conceptually LGTM, bash looks roughly OK and I don't trust myself to comment any further than that. Has anyone tried running the data on the number of broken symlinks in the current Hydra outputs?

[philiptaron]

As with @K900, this looks good to me in theory and I support the idea that a dangling or reflexive symlink is more often than not a bug.

I'd love a test. Could you write a few using testBuildFailure, showing:

1. Reflexive symlink fails
2. Dangling symlink fails
3. They don't fail if dontCheckForBrokenSymlinks is specified.

[nix-owners]

The PR's base branch is set to staging, but 4 commits from the master branch are included. Make sure you know the right base branch for your changes, then:

• If the changes should go to the master branch, change the base branch to master
• If the changes should go to the staging branch, rebase your PR onto the merge base with the staging branch:

  # git rebase --onto $(git merge-base upstream/staging HEAD) $(git merge-base upstream/master HEAD)
  git rebase --onto eac5f2caf93e16315194c6227cab4937af4b74e3 db0f0fb937b73c4585444925e17446726836a405
  git push --force-with-lease

[ConnorBaker]

Added docs and tests, force-pushed and rebased!

@K900 and @philiptaron would you mind taking another look?

[K900]

LGTM, should we get this a Hydra jobset, or do we just send it to staging? CC @vcunat.

[philiptaron]

Requesting change for the tests of relative symlinks, especially the error case due to interpolation.

The rest of the suggestions and thoughts are not blocking.

With regard to merge target, I favor staging rather than the work of setting up a special Hydra jobset, just on the grounds that we think these are generally bugs. If we get a swath of brokenness, we can revert this and we'll be fine, as I see it.

[ConnorBaker]

Quick tip for testing:

( PREFIX="$PWD#legacyPackages.x86_64-linux.tests.stdenv.hooks.no-broken-symlinks"; nix eval --json "$PREFIX" | jq --arg prefix "$PREFIX" -cr 'paths(strings) | join(".") | $prefix + "." + .' | nix build --keep-going --no-link --print-out-paths --stdin )

[ConnorBaker]

All feedback addressed! @philiptaron if you're happy, please feel free to merge :)

[philiptaron]

Looks good, let's see how it tastes in staging. (All tests.stdenv pass.)