build-support: add new hooks

[drupol]

Hello everyone,

During the holidays, I spent some time packaging Python packages and noticed that some of them require a valid and mutable home directory to build or function properly.

Currently, the default behavior of the Nix stdenv is to set the HOME environment variable to /homeless-shelter, a read-only directory. While this approach is consistent, it can cause issues for packages that expect a writable home directory.

After performing a treewide search in nixpkgs, I found approximately 500 instances where export HOME is used (rg -c "export HOME" | wc -l) and 300 where export PATH is used (rg -c "export PATH" | wc -l). These repetitive patterns inspired me to propose a solution adhering to the DRY principle.

I created custom hooks, tmpdirAsHomeHook, which sets up a mutable home directory automatically when added to nativeBuildInputs or another appropriate place. Additionally, addBinToPath, which modifies the PATH environment variable to include bin/ if available.

I’d appreciate your feedback on this approach and have a few questions:

1. Do you think this would be a valuable addition to nixpkgs?
2. Regarding naming, I’m considering renaming tmpdirAsHomeHook to mutableHomeDirHook for better clarity. What do you think?
3. In the hooks, I use the line addEnvHooks "$targetOffset" addBinToPath. I’m not entirely confident about the best way to implement this. Could you provide some guidance?

Thanks for taking the time to review this. I look forward to hearing your thoughts and suggestions!

Best regards

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.

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/request-for-comments-adding-two-new-hooks/58282/1

[xiaoxiangmoe]

Will this hook also be avaliable in preConfig or some thing like this?

Here is some example:

nixpkgs/pkgs/by-name/af/affine/package.nix

Line 109 in 1a685a9

export HOME="$NIX_BUILD_TOP"

nixpkgs/pkgs/by-name/af/affine/package.nix

Line 156 in 1a685a9

export HOME="$NIX_BUILD_TOP"

[drupol]

Will this hook also be avaliable in preConfig or some thing like this?

Here is some example:

nixpkgs/pkgs/by-name/af/affine/package.nix

Line 109 in 1a685a9

export HOME="$NIX_BUILD_TOP"

nixpkgs/pkgs/by-name/af/affine/package.nix

Line 156 in 1a685a9

export HOME="$NIX_BUILD_TOP"

It can actually be added to any phase hooks, so yeah.

[hsjobeki]

I like the Idea overall.
I also have two feedback Points:

• This could be two PRs.
• For my taste the amount of documentation is not enough. Especially i wouldn like to know stuff that happens internally, like what value is. $HOME set to and when?

[drupol]

• This could be two PRs.

While I'm all for splitting PR, make sure that they have a clear scope, I really don't understand why I would need to split this one. The scope is clear, even the commits are correctly split. So I'm sorry but no, I won't split this PR in two.

• For my taste the amount of documentation is not enough. Especially i wouldn like to know stuff that happens internally, like what value is. $HOME set to and when?

OK I will improve it.

[drupol]

Planning to merge this tomorrow morning, feel free to raise your voice if you believe it is a bad idea.

[K900]

I'd like to see some examples of packages helped by these hooks, at the very least.

[drupol]

I'd like to see some examples of packages helped by these hooks, at the very least.

Here's some Github search where it would be used:

• addBinToPathHook: https://github.com/search?q=repo%3ANixOS%2Fnixpkgs%20export%20PATH%3D%24out%2Fbin%3A%24PATH&type=code
• writableTmpDirAsHomeHook: https://github.com/search?q=repo%3ANixOS%2Fnixpkgs+export+HOME%3D&type=code

[K900]

This should probably at least explicitly mention it's adding $out/bin and not $sourceRoot/bin or whatever. Honestly, this is my big concern with this hook: it's not immediately obvious what exactly it does, and the thing it does comes with a bunch of weird caveats (what if there are multiple outputs? what if the binaries are in sbin? etc).

[drupol]

Thank you, I just updated the documentation. Let me know if this resolves this feedback.

[SuperSandro2000]

Shouldn't we log something if the directory doesn't exist?

[GaetanLepage]

This has been changed since then: https://github.com/NixOS/nixpkgs/pull/378110/files#diff-d390481be231cb8f7d3eaf4cbc0cd6580b5e469d9c3ac6c5a91a8c9fa62f3799

[drupol]

It hasn't been suggested during the month this PR has been opened, so no.
That said, while implementing that hook this morning, I had an issue because of that if condition. I removed it in 62d4ca6

[SuperSandro2000]

If we name the hook "writable" shouldn't it also call chmod +w or so to make sure it is writable? Right now with the wrong umask it isn't

[drupol]

It wasn't needed so far, but it could be done in a future PR.

[SuperSandro2000]

Why is that a hidden directory and not just home?

[drupol]

It has been suggested to name it as such, I don't really have any preference.

[nixpkgs-ci]

Backport failed for release-24.11, because it was unable to cherry-pick the commit(s).

Please cherry-pick the changes locally and resolve any conflicts.

git fetch origin release-24.11
git worktree add -d .worktree/backport-370869-to-release-24.11 origin/release-24.11
cd .worktree/backport-370869-to-release-24.11
git switch --create backport-370869-to-release-24.11
git cherry-pick -x 87521c59b636ae9073c58bd549b4cdc334a3dc28 f8110737aeedf8ba92ea46a0b1d2d298843d7c06

[bjornfor]

I worry that this will break when run under nix-shell. Can we use something other than $NIX_BUILD_TOP please? (Or define a new env var for where the build actually happens, which is also valid in nix-shell?)

[bjornfor]

Well, break nix-shell and use of the keepBuildTree setup hook, as per the linked issue above.

[MattSturgeon]

Is there a sane way that writableTmpDirAsHomeHook could be configured to only affect certain phases?

E.g. if I wanted a writable HOME for the build phase, but still wanted to use /homeless-shelter for other phases.

Or a better example, if I only wanted the check phase to be affected, effectively:

preCheck = ''
  export HOME="$NIX_BUILD_TOP/.home"
'';
postCheck = ''
  export HOME=/homeless-shelter
'';

[bjornfor]

preCheck = ''
  export HOME="$NIX_BUILD_TOP/.home"
'';

Please use something other than $NIX_BUILD_TOP, because it breaks under nix-shell and with the keepBuildTree setup hook. See #189691.

[MattSturgeon]

Please use something other than $NIX_BUILD_TOP, because it breaks under nix-shell and with the keepBuildTree setup hook. See #189691.

That really wasn't the relevant part of my question. You've already made your point in #370869 (comment), maybe we should consider opening another PR where we can discuss moving away from NIX_BUILD_TOP?

My question was whether we could extend the writableTmpDirAsHome hook such that it only affects specific phases. My preCheck and postCheck were purely demonstrative examples of one way it could be done without this hook.