doc: Improve fetchClosure documentation

This commit is contained in:
Robert Hensing 2023-06-05 16:25:22 +02:00
parent 32c69e2b17
commit 50de11d662
3 changed files with 55 additions and 15 deletions

View file

@ -2,5 +2,7 @@
- [`nix-channel`](../command-ref/nix-channel.md) now supports a `--list-generations` subcommand - [`nix-channel`](../command-ref/nix-channel.md) now supports a `--list-generations` subcommand
- The function [`builtins.fetchClosure`](../language/builtins.md#builtins-fetchClosure) can now fetch input-addressed paths in [pure mode](../command-ref/conf-file.md#conf-pure-eval).
- Nix now allows unprivileged/[`allowed-users`](../command-ref/conf-file.md#conf-allowed-users) to sign paths. - Nix now allows unprivileged/[`allowed-users`](../command-ref/conf-file.md#conf-allowed-users) to sign paths.
Previously, only [`trusted-users`](../command-ref/conf-file.md#conf-trusted-users) users could sign paths. Previously, only [`trusted-users`](../command-ref/conf-file.md#conf-trusted-users) users could sign paths.

View file

@ -1502,6 +1502,8 @@ static RegisterPrimOp primop_storePath({
in a new path (e.g. `/nix/store/ld01dnzc-source-source`). in a new path (e.g. `/nix/store/ld01dnzc-source-source`).
Not available in [pure evaluation mode](@docroot@/command-ref/conf-file.md#conf-pure-eval). Not available in [pure evaluation mode](@docroot@/command-ref/conf-file.md#conf-pure-eval).
See also [`builtins.fetchClosure`](#builtins-fetchClosure).
)", )",
.fun = prim_storePath, .fun = prim_storePath,
}); });

View file

@ -202,40 +202,76 @@ static RegisterPrimOp primop_fetchClosure({
.name = "__fetchClosure", .name = "__fetchClosure",
.args = {"args"}, .args = {"args"},
.doc = R"( .doc = R"(
Fetch a Nix store closure from a binary cache, rewriting it into Fetch a Nix store closure from a binary cache.
content-addressed form. For example,
```nix This function can be used in three ways:
builtins.fetchClosure {
fromStore = "https://cache.nixos.org";
fromPath = /nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1;
toPath = /nix/store/ldbhlwhh39wha58rm61bkiiwm6j7211j-git-2.33.1;
}
```
fetches `/nix/store/r2jd...` from the specified binary cache, - Fetch any store path and rewrite it to a fully content-addressed store path. Example:
```nix
builtins.fetchClosure {
fromStore = "https://cache.nixos.org";
fromPath = /nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1;
toPath = /nix/store/ldbhlwhh39wha58rm61bkiiwm6j7211j-git-2.33.1;
}
```
- Fetch a content-addressed store path.
```nix
builtins.fetchClosure {
fromStore = "https://cache.nixos.org";
fromPath = /nix/store/ldbhlwhh39wha58rm61bkiiwm6j7211j-git-2.33.1;
}
```
- Fetch an [input-addressed store path](@docroot@/glossary.md#gloss-input-addressed-store-object) as is. This depends on user configuration, which is less preferable.
```nix
builtins.fetchClosure {
fromStore = "https://cache.nixos.org";
fromPath = /nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1;
inputAddressed = true;
}
```
**Rewriting a store path**
This first example fetches `/nix/store/r2jd...` from the specified binary cache,
and rewrites it into the content-addressed store path and rewrites it into the content-addressed store path
`/nix/store/ldbh...`. `/nix/store/ldbh...`.
If `fromPath` is already content-addressed, or if you are By rewriting the store paths, you can add the contents to any store without requiring that you or perhaps your users configure any extra trust.
allowing input addressing (`inputAddressed = true;`), then `toPath` may be
omitted.
To find out the correct value for `toPath` given a `fromPath`, To find out the correct value for `toPath` given a `fromPath`,
you can use `nix store make-content-addressed`: you can use [`nix store make-content-addressed`](@docroot@/command-ref/new-cli/nix3-store-make-content-addressed.md):
```console ```console
# nix store make-content-addressed --from https://cache.nixos.org /nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1 # nix store make-content-addressed --from https://cache.nixos.org /nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1
rewrote '/nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1' to '/nix/store/ldbhlwhh39wha58rm61bkiiwm6j7211j-git-2.33.1' rewrote '/nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1' to '/nix/store/ldbhlwhh39wha58rm61bkiiwm6j7211j-git-2.33.1'
``` ```
This function is similar to `builtins.storePath` in that it Alternatively, you may set `toPath = ""` and find the correct `toPath` in the error message.
**Not rewriting**
`toPath` may be omitted when either
- `fromPath` is already content-addressed, or
- `inputAddressed = true;` is set.
Fetching an [input addressed path](@docroot@/glossary.md#gloss-input-addressed-store-object) is not recommended because it requires that the source be trusted by the Nix configuration.
**`builtins.storePath`**
This function is similar to [`builtins.storePath`](#builtins-storePath) in that it
allows you to use a previously built store path in a Nix allows you to use a previously built store path in a Nix
expression. However, it is more reproducible because it requires expression. However, it is more reproducible because it requires
specifying a binary cache from which the path can be fetched. specifying a binary cache from which the path can be fetched.
Also, the default requirement of a content-addressed final store path Also, the default requirement of a content-addressed final store path
avoids the need for users to configure [`trusted-public-keys`](@docroot@/command-ref/conf-file.md#conf-trusted-public-keys). avoids the need for users to configure [`trusted-public-keys`](@docroot@/command-ref/conf-file.md#conf-trusted-public-keys).
**Experimental feature**
This function is only available if you enable the experimental This function is only available if you enable the experimental
feature `fetch-closure`. feature `fetch-closure`.
)", )",