diff --git a/doc/manual/expressions/advanced-attributes.xml b/doc/manual/expressions/advanced-attributes.xml index 07b0d97d3..e1fbe6291 100644 --- a/doc/manual/expressions/advanced-attributes.xml +++ b/doc/manual/expressions/advanced-attributes.xml @@ -325,12 +325,23 @@ big = "a very long string"; allowSubstitutes - If this attribute is set to + + If this attribute is set to false, then Nix will always build this derivation; it will not try to substitute its outputs. This is useful for very trivial derivations (such as writeText in Nixpkgs) that are cheaper to - build than to substitute from a binary cache. + build than to substitute from a binary cache. + + You need to have a builder configured which satisfies + the derivation’s system attribute, since the + derivation cannot be substituted. Thus it is usually a good idea + to align system with + builtins.currentSystem when setting + allowSubstitutes to false. + For most trivial derivations this should be the case. + +