docs: fix description of how NIX_PATH / nix-path interact

[CyberShadow]

If nix-path is set in nix.conf, the environment variable is always ignored.

Motivation

I was confused by this incorrect fact in the documentation, and I'm submitting a correction.

Context

I was trying to set up NixOS without channels. Setting nix.channel.enable = false; causes nix.settings.nix-path to be set to "", which I thought wouldn't change much, but it actually effectively globally configures Nix to always ignore NIX_PATH in the environment.

Some related issues I've found:

• Broken NIX_PATH tracking issue #9574
• nix-channel: do not set empty nix-path when disabling channels nixpkgs#273170
• os.environ["NIX_PATH"] = self.nixpkgs_path() silently get ignored when nix-path is set in nix.conf Mic92/nixpkgs-review#343
• Restore NIX_PATH taking precedence over nix-path #7871 (obsoletes this PR, but seems stalled)

Priorities and Process

Add 👍 to pull requests you find important.

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

[fricklerhandwerk]

The described behavior is essentially a bug. The desired behavior is documented in #7772 and #9066. We can of course merge the change, but we probably should at least note that it's a bug and not indented to stay that way.

#7871 is probably correct, except for the merge conflicts and being very hard to read and follow. I reviewed it yesterday and considered updating and untangling it, but currently we can't even properly test the default behavior of search paths on a fresh vanilla Linux because the infrastructure simply isn't mature enough to just add the test cases. I took a stab at it after inspecting all the related code, and it will need a few focused sessions to get it done. I don't have that sort of time, but maybe someone else wants to help out?

The only place where we even assume a regular Linux is in the exactly one installer test there is. I think we should check what we can leverage from https://github.com/numtide/nix-vm-test to make the setup more legible and flexible, but I'd want to study the complete code before adopting anything. Given we will need to cover the configuration combinatorics programmatically, we'll also have to figure out how to still run the test suite quickly enough. (We may want to get rid of GitHub Actions entirely, eventually, see a brief note on a recent related discussion.)

There is always the option to make a quick fix and cross fingers, but I'm really tired of inadvertently introducing more regressions because the testing situation leaves so much to be desired. I'd rather fix the root causes first, and for me that's testing, code readability, and documentation (interfaces, self-contained usage examples, and design decisions).

@roberth @Ericson2314 what do you think? Note the bug in documentation? So far we had an unwritten and not explicitly agreed-upon policy to keep bugs in the issue tracker.

[roberth]

@fricklerhandwerk I appreciate your thoroughness, but do we really a "vanilla Linux" test setup for this? Wouldn't a NixOS VM test with like three configurations cover this? The testScript can tweak the environment and arguments easily.

Given we will need to cover the configuration combinatorics programmatically, we'll also have to figure out how to still run the test suite quickly enough.

This is the trouble with black box testing. The solution is to not treat it as a black box, because it isn't. It's ok to use some knowledge about the system to select a manageable set of combinations of parameters for a given set of test cases, and only test those.
Brute forcing it doesn't help anyone, because you need to be able to test in your development cycle without relying on a build farm to perform a whole bunch of redundant tests. It might catch low single digit % more bugs, but would slow us down by a larger amount, leaving us with less time to actually solve problems.

what do you think? Note the bug in documentation?

We could make an exception to the unwritten rule. It's a long standing bug. We already make an exception for some long standing design bugs that users can opt in to. Maybe it's not the same, but one instance is just a precedent, not a pattern. We can judge this on a case by case basis.
Do make clear that it's a bug.

[nixos-discourse]

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

https://discourse.nixos.org/t/2024-07-03-nix-team-meeting-minutes-158/49097/1

[roberth]

This has been fixed in Nix 2.24, but it is risky to backport #11079 because it's a fairly significant change in behavior. Perhaps this documentation could be backported instead?

[roberth]

Suggested change

	Due to a bug, it overrides the [`NIX_PATH` environment variable](@docroot@/command-ref/env-common.md#env-NIX_PATH) when set.
	Due to a bug in Nix versions ≥2.13 and <2.24, `nix-path` overrides the [`NIX_PATH` environment variable](@docroot@/command-ref/env-common.md#env-NIX_PATH) when set.

[CyberShadow]

Done, thanks!

[fricklerhandwerk]

Yeah I guess backporting the docs is easier than backporting the fix.