Since Nix on the other hand doesn’t install packages in “global” locations like /usr/bin but in package-specific directories, the risk of incomplete dependencies is greatly reduced.
This is correct and makes sense.
But
This is because tools such as compilers don’t search in per-packages directories such as /nix/store/5lbfaxb722zp…-openssl-0.9.8d/include, so if a package builds correctly on your system, this is because you specified the dependency explicitly. This takes care of the build-time dependencies.
This doesn’t make sense. Earlier sentence specifies that in Nix installs packages in individual cryptographically hashed directories. But then it states that ..compilers don't search in per-packages directories.
Is this a documentation error or am I interpreting it badly?
I think the point the author is trying to make here is that the compiler will not ‘spontaneously’ look in /nix/store/5lbfaxb722zp…-openssl-0.9.8d/include, it will only look there if you’ve specified that path explicitly.
How could we make that more clear? The smallest change would be to add “by default” before “, so if a package …” - would that help? or would a bigger change be better?
This is because tools such as compilers don’t search in per-packages …
Reads like building on the previous sentence, where docs is saying that Nix installs packages in package-specific directories.
However, your explanation shows that this sentence is adding the further context.
Maybe re-word it like,
Since Nix on the other hand doesn’t install packages in “global” locations like /usr/bin but in package-specific directories, the risk of incomplete dependencies is greatly reduced. Further, the tools such as compilers don’t search in per-packages directories such as /nix/store/5lbfaxb722zp…-openssl-0.9.8d/include, without you specifying the dependency explicitly. This takes care of the build-time dependencies.