vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(gotchas): document nixSrc stable-docs-drv approach

Browse source
This commit is contained in:
atlas 2026-07-04 14:08:39 +02:00 • committed by mara
commit 500c50745b
1 changed files with 34 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

39
docs/gotchas.md
View file

@ -323,11 +323,10 @@ connects to the compositor at `127.0.0.1:<vnc_port>`.
## Nix options reference (`nix/docs/default.nix`)
`pkgs.nixosOptionsDoc` over two evaluated module trees:
`hostEval` (a stub NixOS system loading `self.nixosModules.default`
with every hyperhive subsystem `mkForce false` so heavy build
inputs stay out of the eval) and `agentEval` (reuses the already-evaluated
`agent-base` container config so the per-agent options tree is
identical to what a real agent container sees).
`hostEval` (a stub NixOS system loading `hive-c0re.nix` with every
hyperhive subsystem `mkForce false` so heavy build inputs stay out of
the eval) and `agentEval` (evaluates `agent-base.nix` fresh for the
per-agent options tree).
Three output trees consumed by `flake.nix`, all **markdown**:
@ -356,3 +355,33 @@ Host options live entirely under `services.hyperhive.*`. The
options tree picks up everything under that root — picking against
stray roots produces an empty tree and renders the host page as
template chrome with no `<h2>` headers.
### Docs drv stability: `nixSrc` + stub overlay
Naively, the docs evaluation depends on `self` (the flake's store path),
so every commit — even Rust-only or frontend-only changes — produces new
docs drv hashes. The remote builder must rebuild docs from scratch for
every PR branch, and if its store is full the build fails with a cached
failure that blocks CI for the whole branch.
The fix (`nix/docs/default.nix`):
1. **`nixSrc`** — `builtins.path` on the `nix/` directory, wrapped in
`builtins.unsafeDiscardStringContext` to strip `self`'s store-path
context. The resulting store path is content-addressed from the nix/
file contents only. Docs drvs only change when a `.nix` file changes.
2. **`docsStubOverlay`** — replaces `self.overlays.default` with stub
packages (`pkgs.emptyFile` / `pkgs.emptyDirectory`) for the docs eval.
`nixosOptionsDoc` renders `defaultText` for all package options anyway;
the stubs prevent attribute-missing eval errors without pulling in the
Rust or frontend build closure.
3. Both `hostEval` and `agentEval` are evaluated from `nixSrc` paths
(not `self`), so the docs drv dependency chain ends at `nixSrc`.
Why `builtins.unsafeDiscardStringContext`? The path string
`toString self + "/nix"` carries `self`'s string context, which would
make `builtins.path` include `self` as a build dependency even after
content-addressing the directory. Discarding the context makes the
resulting `nixSrc` truly independent of `self`'s store path.