Home / How it works
How rninja caches a build
rninja keeps ninja's fast build planner and adds two things ninja lacks: a cache that spans runs and machines, and a scheduler that keeps your cores busy. It executes the build.ninja you already have — nothing about your generator or CI changes.
// the pipeline, per action
build.ninja
│ parse (ninja semantics preserved)
▼
┌──────────────┐ hash inputs + cmd + env
│ action │ ───────────────┐
└──────────────┘ ▼
┌──────────────────┐
│ content hash │
└──────────────────┘
│ lookup
┌─────────────────┼──────────────────┐
▼ ▼ ▼
┌───────────┐ ┌──────────────┐ ┌────────────┐
│ sled local│ │ async-nng │ │ MISS → │
│ cache │ │ remote cache │ │ scheduler │
└───────────┘ │ (optional) │ └────────────┘
│ hit └──────────────┘ │ tokio
▼ ▼ ▼
reuse artifact pull artifact run toolchain
└─────────────────┴─────────► store (content-addressed) // a hit only fires when inputs, command, and environment all match.
The pipeline, step by step
Parse the build.ninja
rninja reads your existing build.ninja with standard ninja semantics — phony targets, restat, pools, and depfiles are all preserved. It executes the file your generator wrote; it never regenerates it.
Content-address each action
Every action is fingerprinted over its full inputs (source bytes, includes, generated headers), its command line, and the environment the rule observes. Identical inputs produce an identical hash.
Look up the cache
rninja checks the local sled-backed index for a matching action. If a remote cache is configured, it can pull the artifact over async-nng when the local store misses.
Schedule and build misses
On a miss, the tokio-driven scheduler runs the toolchain, keeping cores busy where stock ninja stalls. Outputs are tracked and never reordered against ninja semantics.
Store the result
The artifact is written into the content-addressed blob store and the index is updated — crash-safe at every step, so an interrupted build cannot corrupt the store.
The CLI
A thin, fast front end that speaks ninja's flags. It is what your scripts, Makefiles, and CI call — no new command to learn.
The cache
A content-addressed blob store indexed by sled. Crash-safe, local-first, and optionally backed by an async-nng remote peer.
The scheduler
A tokio async executor that keeps cores busy on the misses and accounts for IO contention in its ready queue.
Ready to try it?
The quickstart gets you from install to a cached build in a few minutes. Or see the full feature breakdown.