docs(primops): document functions in primops.cc
#1
1 changed files with 107 additions and 0 deletions
|
@ -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,
|
||||
});
|
||||
|
||||
|
|
Loading…
Reference in a new issue