docs(primops): document functions in primops.cc

WIP

Change-Id: I99eb29f3bdc4f1f6aefb5add61b3167e939cd09f
Signed-off-by: Christina Sørensen <christina@cafkafk.com>
This commit is contained in:
Christina Sørensen 2024-09-11 16:24:21 +02:00
parent c14486ae8d
commit 6247f78b3d
Signed by: cafkafk
GPG key ID: 26C542FD97F965CE

View file

@ -254,6 +254,21 @@ static void import(EvalState & state, const PosIdx pos, Value & vPath, Value * v
static RegisterPrimOp primop_scopedImport(PrimOp {
.name = "scopedImport",
.arity = 2,
.args = {"scope", "path"},
.doc = R"(
Imports a *path* with a given attrset *scope* injected.
This is conceptually equivalent to `import path`, where the
contents of path get's wrapped in a `with scope`.
> **Note**
>
> Scoped import has some *nasty* performance implications, since it
> disables the parse/eval cache.
`scopedImport` is generally considered an operation to avoid, unless
there are exceptional reasons to justify its usage.
)",
.fun = [](EvalState & state, const PosIdx pos, Value * * args, Value & v)
{
import(state, pos, *args[1], args[0], v);
@ -814,6 +829,33 @@ static void prim_addErrorContext(EvalState & state, const PosIdx pos, Value * *
static RegisterPrimOp primop_addErrorContext(PrimOp {
.name = "__addErrorContext",
.arity = 2,
.args = {"s", "expr"},
.doc = R"(
Adds additional error message *s* to the trace of *expr* on failure.
This is useful for giving addition information on failure. For example,
```nix
builtins.addErrorContext "This error is intentional" (assert false; 10)
```
will throw a stack trace like this:
```
error:
while calling the 'addErrorContext' builtin
at «string»:1:1:
1| builtins.addErrorContext "This error is intentional" (assert false; 10)
| ^
This error is intentional
error: assertion 'false' failed
at «string»:1:55:
1| builtins.addErrorContext "This error is intentional" (assert false; 10)
|
```
)",
.fun = prim_addErrorContext,
});
@ -1423,6 +1465,44 @@ drvName, Bindings * attrs, Value & v)
static RegisterPrimOp primop_derivationStrict(PrimOp {
.name = "derivationStrict",
.arity = 1,
.args = {"derivation"},
.doc = R"(
derivationStrict takes an attrSet *derivation* and turns it into
a *set* representing a derivation.
`derivationStrict` construct (as a unobservable side effect) a Nix
derivation expression that performs the derivation described by the
argument set.
Returns the original set extended with the following attributes:
`outPath' containing the primary output path of the derivation; `drvPath'
containing the path of the Nix expression; and `type' set to `derivation'
to indicate that this is a derivation.
For instance,
```nix
builtins.derivationStrict {
name = "foo";
builder = "/bin/sh";
args = [ ];
system = "x86_64-linux";
outputs = ["foo"];
}
```
evaluates to
```nix
{
drvPath = "/nix/store/rm2qi6fdyryhrzm1l3r0y70zgg811fmf-foo.drv";
foo = "/nix/store/x22z6v41yzkj4qs2m8j1wkcy4gjznmw2-foo-foo";
}
```
builtins.derivation is technically an internal wrapper around
builtins.derivationStrict.
)",
.fun = prim_derivationStrict,
});
@ -2511,6 +2591,33 @@ static void prim_unsafeGetAttrPos(EvalState & state, const PosIdx pos, Value * *
static RegisterPrimOp primop_unsafeGetAttrPos(PrimOp {
.name = "__unsafeGetAttrPos",
.arity = 2,
.args = {"s", "set"}
.doc = R"(
Searches *set* for the location of attribute *s*, where *s* is a string.
The output is an attrSet consisting of column, line, and file where a
match is found. For instance, to find the location of `stdenvNoCC` in
nixpkgs:
```nix
builtins.unsafeGetAttrPos "stdenvNoCC" pkgs
````
which will output,
```nix
{
column = 20;
file = "/nix/store/w7wryrbg7r3sl31fcd74yw2kva42nlw9-source/pkgs/top-level/stage.nix";
line = 148;
}
```
> **Note**
>
> The position given isn't always excact, hence it should not be relied
> on beyond manually finding things.
)",
.fun = prim_unsafeGetAttrPos,
});