nordisk/dwarves

holger build target — for idiots (zero-knowledge walkthrough)

Class: guide (beginner) · sibling: design · guide.

The one-sentence version

holger ships as three different programs built from the same code, and dwarves (the build robot) has a recipe that builds all three at once.

Why three programs?

holger is an artifact registry. It runs in very different places, so it comes in three sizes:

• embedded — the tiniest one, for locked-down/edge boxes. Binary: holger-embedded.
• mini — a small read-only server for airgapped/red-zone networks. Binary: holger-mikro.
• full — the everything-on server that talks to other registries. Binary: holger-full.

Same source, three "recipes" (Cargo features), three named executables.

Who does what?

Think of two people:

• dwarves is the foreman. It knows the recipe: "build these three, in this way." It does not swing the hammer.
• nornir-build-thing is the builder. It actually runs cargo build and hands back the finished programs plus a receipt (a provenance attestation).

The foreman never picks up the hammer himself — that would be duplicating the builder's job (against the reuse law). He just points at holger's own list of the three sizes and says "build each of these."

Where is holger's list?

holger writes down its three sizes in a file: holger/.nornir/build-variants.toml. dwarves reads that file. It does not invent the list — it trusts holger's.

The safe check (no waiting for a build)

Building three programs is slow. So dwarves has a fast check that just makes sure the recipe still lines up with holger's list — without building anything:

$ dwarves holger-build ../holger
... 3 tier(s), 3 resolved, 0 missing ...
  ✓ embedded → bin holger-embedded ...
  ✓ mini     → bin holger-mikro ...
  ✓ full     → bin holger-full ...

"3 resolved, 0 missing" means the recipe still points at real programs. If holger ever renamed or removed a size, you'd see ✗ ... UNWIRED and the check would fail (exit 1) — so nobody can quietly break the build recipe.

Same check, but on a server far away (--server)

You can run the exact same check against a forge server running somewhere else — just add --server <address>:

$ dwarves --server 127.0.0.1:7900 holger-build /srv/holger
... 3 tier(s), 3 resolved, 0 missing ...

It phones the server (over gRPC, with your token), the server does the resolving on its own copy of holger, and you get the same printout and the same exit code. Handy when the holger checkout lives on the build machine, not your laptop.

The real build (when you want the actual programs)

Add --real (or run it on the forge server): now the builder wakes up and runs the three cargo builds for real, producing holger-embedded, holger-mikro, and holger-full. That part is slow and is skipped in the quick check on purpose.

Remember

• Three programs, one source.
• dwarves plans; nornir-build-thing builds.
• The quick check proves the plan without compiling anything.