fetchClosure: Interleave the examples in the docs
This commit is contained in:
parent
537e8beb77
commit
b4b02d084f
|
@ -211,52 +211,42 @@ static RegisterPrimOp primop_fetchClosure({
|
||||||
.name = "__fetchClosure",
|
.name = "__fetchClosure",
|
||||||
.args = {"args"},
|
.args = {"args"},
|
||||||
.doc = R"(
|
.doc = R"(
|
||||||
Fetch a store path [closure](@docroot@/glossary.md#gloss-closure) from a binary cache.
|
Fetch a store path [closure](@docroot@/glossary.md#gloss-closure) from a binary cache, and return the store path as a string with context.
|
||||||
|
|
||||||
This function can be used in three ways:
|
This function can be invoked in three ways, that we will discuss in order of preference.
|
||||||
|
|
||||||
- Fetch any store path and rewrite it to a fully content-addressed store path.
|
**Fetch a 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.
|
|
||||||
|
|
||||||
Example:
|
Example:
|
||||||
|
|
||||||
```nix
|
```nix
|
||||||
builtins.fetchClosure {
|
builtins.fetchClosure {
|
||||||
fromStore = "https://cache.nixos.org";
|
fromStore = "https://cache.nixos.org";
|
||||||
fromPath = /nix/store/ldbhlwhh39wha58rm61bkiiwm6j7211j-git-2.33.1;
|
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.
|
This is the simplest invocation, and it does not require the user of the expression to configure [`trusted-public-keys`](@docroot@/command-ref/conf-file.md#conf-trusted-public-keys) to ensure their authenticity.
|
||||||
|
|
||||||
Example:
|
If your store path is [input addressed](@docroot@/glossary.md#gloss-input-addressed-store-object) instead of content addressed, consider the other two invocations.
|
||||||
|
|
||||||
```nix
|
**Fetch any store path and rewrite it to a fully content-addressed store path**
|
||||||
builtins.fetchClosure {
|
|
||||||
fromStore = "https://cache.nixos.org";
|
|
||||||
fromPath = /nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1;
|
|
||||||
inputAddressed = true;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Rewriting a store path**
|
Example:
|
||||||
|
|
||||||
This first example fetches `/nix/store/r2jd...` from the specified binary cache,
|
```nix
|
||||||
|
builtins.fetchClosure {
|
||||||
|
fromStore = "https://cache.nixos.org";
|
||||||
|
fromPath = /nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1;
|
||||||
|
toPath = /nix/store/ldbhlwhh39wha58rm61bkiiwm6j7211j-git-2.33.1;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
This 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...`.
|
||||||
|
|
||||||
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.
|
Like the previous example, no extra configuration or privileges are required.
|
||||||
|
|
||||||
To find out the correct value for `toPath` given a `fromPath`,
|
To find out the correct value for `toPath` given a `fromPath`,
|
||||||
use [`nix store make-content-addressed`](@docroot@/command-ref/new-cli/nix3-store-make-content-addressed.md):
|
use [`nix store make-content-addressed`](@docroot@/command-ref/new-cli/nix3-store-make-content-addressed.md):
|
||||||
|
@ -268,20 +258,25 @@ static RegisterPrimOp primop_fetchClosure({
|
||||||
|
|
||||||
Alternatively, set `toPath = ""` and find the correct `toPath` in the error message.
|
Alternatively, set `toPath = ""` and find the correct `toPath` in the error message.
|
||||||
|
|
||||||
**Not rewriting**
|
**Fetch an input-addressed store path as is**
|
||||||
|
|
||||||
`toPath` may be omitted when either
|
Example:
|
||||||
- `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.
|
```nix
|
||||||
|
builtins.fetchClosure {
|
||||||
|
fromStore = "https://cache.nixos.org";
|
||||||
|
fromPath = /nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1;
|
||||||
|
inputAddressed = true;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
It is possible to fetch an [input-addressed store path](@docroot@/glossary.md#gloss-input-addressed-store-object) and return it as is.
|
||||||
|
However, this is the least preferred way of invoking `fetchClosure`, because it requires that the input-addressed paths are trusted by the Nix configuration.
|
||||||
|
|
||||||
**`builtins.storePath`**
|
**`builtins.storePath`**
|
||||||
|
|
||||||
This function is similar to [`builtins.storePath`](#builtins-storePath) in that it
|
`fetchClosure` is similar to [`builtins.storePath`](#builtins-storePath) in that it allows you to use a previously built store path in a Nix expression.
|
||||||
allows you to use a previously built store path in a Nix
|
However, `fetchClosure` is more reproducible because it specifies a binary cache from which the path can be fetched.
|
||||||
expression. However, it is more reproducible because it requires
|
|
||||||
specifying a binary cache from which the path can be fetched.
|
|
||||||
Also, using content-addressed store paths does not require users to configure [`trusted-public-keys`](@docroot@/command-ref/conf-file.md#conf-trusted-public-keys) to ensure their authenticity.
|
Also, using content-addressed store paths does not require users to configure [`trusted-public-keys`](@docroot@/command-ref/conf-file.md#conf-trusted-public-keys) to ensure their authenticity.
|
||||||
)",
|
)",
|
||||||
.fun = prim_fetchClosure,
|
.fun = prim_fetchClosure,
|
||||||
|
|
Loading…
Reference in a new issue