Module realize 

Import-from-derivation: realize a derivation output mid-eval via a binary-installed hook (the pure evaluator owns no build pipeline). Import-from-derivation (IFD): realize a derivation’s output mid-eval.

When eval coerces a derivation to a path for a filesystem read (import, readFile, readDir, pathExists, builtins.path) and the derivation’s outPath is not yet materialized on disk, cppnix realizes it — building or substituting the derivation during evaluation — so the read can proceed. This is import-from-derivation; sui must do the same to compute drvPaths whose graph reads a built output (e.g. the darwin toplevel importing ishou.stylix-fonts, itself a runCommand derivation).

Why a hook, not an inline builder

sui-eval is a pure, synchronous library crate: it owns no store handle, no tokio runtime, and no build sandbox. The realize pipeline (Substitutor + LocalBuilder over an open_rw store) lives in the sui binary, is async, and needs privileged store writes. Wiring that pipeline into the evaluator would invert the dependency graph (sui-eval → sui-build → sandbox) and force a tokio runtime + privileged store into every pure eval.

Instead the binary installs a realize hook — a thread-local callback the evaluator invokes with (drv_path, out_path) at the exact moment a derivation output is demanded on disk. The binary’s hook opens the store, substitutes-then-builds the closure, and returns once the output exists. sui-eval stays pure; orchestration stays in the binary. This mirrors the INPUT_SOURCE_MAP thread-local in path.rs (fetched-input redirect) — same separation-of-concerns pattern, one layer up (a build, not a read-redirect).

Byte-parity invariant

The realize hook changes no value the evaluator observes: the drvPath and outPath are computed by the module fixpoint before realize runs, and are already byte-correct against nix (the marquee darwin roots proved this). Realize only makes the bytes at that already-correct outPath present on disk. Because the drvPath is byte-identical to nix, the realized output is byte-identical to nix (same drv ⇒ same output path ⇒ same content). If no hook is installed, IFD degrades to the pre-existing ENOENT — never a wrong answer.

Structs

RealizeHookGuard

RAII guard restoring the prior realize hook when dropped.

Functions

has_realize_hook

Whether a realize hook is installed on this thread.

install_realize_hook

Install a realize hook for the current thread. Returns a guard that removes the hook (restoring any previous one) when dropped — so a scoped install (e.g. one CLI eval) does not leak into unrelated thread reuse.

realize_output

Realize a derivation output mid-eval so a subsequent filesystem read of out_path succeeds.

Type Aliases

RealizeFn

The realize callback: given a derivation’s .drv path and its expected output store path, materialize that output on disk (substitute or build the closure) and return Ok(()) once the output path exists. On failure returns a human-readable error string (surfaced as an eval IoError).