Expand documentation for experimental-features
Adds examples and additional information to the `impure-derivations`, `recursive-nix`, and `no-url-literals` experimental feature documentation.
This commit is contained in:
Noah Snelson
parent
53d0836347
commit
8a7790f46a
1 changed files with 97 additions and 14 deletions
|
|
@ -17,9 +17,9 @@ constexpr std::array<ExperimentalFeatureDetails, 11> xpFeatureDetails = {{
|
|||
.tag = Xp::CaDerivations,
|
||||
.name = "ca-derivations",
|
||||
.description = R"(
|
||||
Allow derivations to be content-addressed in order to prevent rebuilds
|
||||
when changes to the derivation do not result in changes to the
|
||||
derivation's output. See
|
||||
Allow derivations to be content-addressed in order to prevent
|
||||
rebuilds when changes to the derivation do not result in changes to
|
||||
the derivation's output. See
|
||||
[__contentAddressed](@docroot@/language/advanced-attributes.md#adv-attr-__contentAddressed)
|
||||
for details.
|
||||
)",
|
||||
|
|
@ -28,17 +28,36 @@ constexpr std::array<ExperimentalFeatureDetails, 11> xpFeatureDetails = {{
|
|||
.tag = Xp::ImpureDerivations,
|
||||
.name = "impure-derivations",
|
||||
.description = R"(
|
||||
Allows derivations to produce non-fixed outputs by setting the `__impure`
|
||||
derivation attribute to `true`. See [these release
|
||||
notes](../release-notes/rl-2.8.md) for an example.
|
||||
Allow derivations to produce non-fixed outputs by setting the
|
||||
`__impure` derivation attribute to `true`. An impure derivation can
|
||||
have differing outputs each time it is built.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
derivation {
|
||||
name = "impure";
|
||||
builder = /bin/sh;
|
||||
__impure = true; # mark this derivation as impure
|
||||
args = [ "-c" "read -n 10 random < /dev/random; echo $random > $out" ];
|
||||
system = builtins.currentSystem;
|
||||
}
|
||||
```
|
||||
|
||||
Each time this derivation is built, it can produce a different
|
||||
output (as the builder outputs random bytes to `$out`). Impure
|
||||
derivations also have access to the network, and only fixed-output
|
||||
or other impure derivations can rely on impure derivations. Finally,
|
||||
an impure derivation cannot also be
|
||||
[content-addressed](#xp-feature-ca-derivations).
|
||||
)",
|
||||
},
|
||||
{
|
||||
.tag = Xp::Flakes,
|
||||
.name = "flakes",
|
||||
.description = R"(
|
||||
Enable flakes. See the manual entry for
|
||||
[`nix flake`](../command-ref/new-cli/nix3-flake.md) for details.
|
||||
Enable flakes. See the manual entry for [`nix
|
||||
flake`](../command-ref/new-cli/nix3-flake.md) for details.
|
||||
)",
|
||||
},
|
||||
{
|
||||
|
|
@ -53,18 +72,82 @@ constexpr std::array<ExperimentalFeatureDetails, 11> xpFeatureDetails = {{
|
|||
.tag = Xp::RecursiveNix,
|
||||
.name = "recursive-nix",
|
||||
.description = R"(
|
||||
Allow Nix derivations to call Nix in order to recursively build derivations.
|
||||
See [this
|
||||
commit](https://github.com/edolstra/nix/commit/1a27aa7d64ffe6fc36cfca4d82bdf51c4d8cf717)
|
||||
for more info.
|
||||
Allow derivation builders to call Nix, and thus build derivations
|
||||
recursively.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
with import <nixpkgs> {};
|
||||
|
||||
runCommand "foo"
|
||||
{
|
||||
buildInputs = [ nix jq ];
|
||||
NIX_PATH = "nixpkgs=${<nixpkgs>}";
|
||||
}
|
||||
''
|
||||
hello=$(nix-build -E '(import <nixpkgs> {}).hello.overrideDerivation (args: { name = "recursive-hello"; })')
|
||||
|
||||
mkdir -p $out/bin
|
||||
ln -s $hello/bin/hello $out/bin/hello
|
||||
''
|
||||
```
|
||||
|
||||
An important restriction on recursive builders is disallowing
|
||||
arbitrary substitutions. For example, running
|
||||
|
||||
```
|
||||
nix-store -r /nix/store/kmwd1hq55akdb9sc7l3finr175dajlby-hello-2.10
|
||||
```
|
||||
|
||||
in the above `runCommand` script would be disallowed, as this could
|
||||
lead to derivations with hidden dependencies or breaking
|
||||
reproducibility by relying on the current state of the Nix store. An
|
||||
exception would be if
|
||||
`/nix/store/kmwd1hq55akdb9sc7l3finr175dajlby-hello-2.10` were
|
||||
already in the build inputs or built by a previous recursive Nix
|
||||
call.
|
||||
)",
|
||||
},
|
||||
{
|
||||
.tag = Xp::NoUrlLiterals,
|
||||
.name = "no-url-literals",
|
||||
.description = R"(
|
||||
Disallows unquoted URLs as part of the Nix language syntax. See [RFC
|
||||
45](https://github.com/NixOS/rfcs/pull/45) for more info.
|
||||
Disallow unquoted URLs as part of the Nix language syntax. The Nix
|
||||
language allows for URL literals, like so:
|
||||
|
||||
```
|
||||
$ nix repl
|
||||
Welcome to Nix 2.15.0. Type :? for help.
|
||||
|
||||
nix-repl> http://foo
|
||||
"http://foo"
|
||||
```
|
||||
|
||||
But enabling this experimental feature will cause the Nix parser to
|
||||
throw an error when encountering a URL literal:
|
||||
|
||||
```
|
||||
$ nix repl --extra-experimental-features 'no-url-literals'
|
||||
Welcome to Nix 2.15.0. Type :? for help.
|
||||
|
||||
nix-repl> http://foo
|
||||
error: URL literals are disabled
|
||||
|
||||
at «string»:1:1:
|
||||
|
||||
1| http://bar
|
||||
| ^
|
||||
|
||||
```
|
||||
|
||||
While this is currently an experimental feature, unquoted URLs are
|
||||
being deprecated and their usage is discouraged.
|
||||
|
||||
The reason is that, as opposed to path literals, URLs have no
|
||||
special properties that distinguish them from regular strings, URLs
|
||||
containing parameters have to be quoted anyway, and unquoted URLs
|
||||
may confuse external tooling.
|
||||
)",
|
||||
},
|
||||
{
|
||||
|
|
|
|||
Loading…
Reference in a new issue