Add hashmake, and the builtins a build description needs

[janstrakowski]

hashmake is a build tool whose build files are HashedBuild programs. A hashmake.hb evaluates to a dependency graph; every node is an ordinary function from its prerequisites to the artifact it builds, and .needs maps a local alias to the target producing it, so a build function receives exactly { alias -> artifact } and never a path.

The tool itself is deliberately small — find the build file, evaluate it, order the graph, refuse cycles, call each node. It has no cache of its own. Incremental rebuilds come from the language: a node wraps its work in cached (§15), whose key is the code plus the values it reads, and a File is its content (§3). There are no timestamps anywhere in this.

odin build tools/hashmake -out:hashmake
cd examples/hashmake && ../../hashmake

That vendors cJSON as a pinned submodule, finds its three .c files by listing the directory rather than naming them, compiles each with clang, links them, and runs the result.

What this needed from the language

Four things were missing, and the first three were the reason it could not be written before:

• exec { .cmd, .args, .inputs, .outputs, .stdin } → { .status, .stdout, .stderr, .outputs }. The command runs in a fresh scratch directory holding nothing but its inputs, and the declared outputs come back as values, never paths. That shape exists to make caching correct rather than as a convenience: §15's key excludes anything an expression reads at run time, so a thinner exec — one that ran a command in a directory and let the caller loadfile the result afterwards — would be silently wrong under cached, answering with the first run's bytes forever. A non-zero exit is not a failure; it is .status, so a build can check it and show .stderr. Gated by a new ctx.permissions.exec, not folded into io.
• fold { .table, .init, .step } — the one general traversal. There are no loops and recursion cannot reach a Table's entries, so the language could not process a collection at all; map, filter and appending are now a line or two of HashedBuild each. It visits in ascending key order, not entry order, which is what makes a sequence fold by index and two Tables that compare equal fold to the same answer.
• textlen / textslice — codepoints, not bytes. Deliberately the primitives: endswith, the thing a build actually wants, is four lines on top of them, and is how the C sources get filtered.
• listdir <dirFile> — names only, sorted byte-wise. Resolves half of §16's own TODO.

Containment

exec being sandboxed while loadfile "…" still resolved anywhere was half a guarantee, so this closes it. ctx.dir is a handle to the directory a run is rooted at, and a path written without a handle is now governed by a permission:

permission	loadfile "x" resolves
anypath	anywhere, as before — granted at the root, so nothing existing changes
workdir	contained to ctx.dir: .., an absolute path, an outward symlink and a .. written behind a . are all refused, and . resolves to ctx.dir rather than through it
neither	refused — only the { .dir, .path } forms work

Both spellings of a handle-less path share one resolver, so the guarantee cannot hold for loadfile "x" and not for createfile { .path }. hashmake drops anypath before evaluating a build file, so a hashmake.hb cannot read the rest of the machine; --allow-any-path opts back out.

ctx.dir is its own type rather than a directory File, and this is forced rather than chosen. §15 puts the whole ctx into every cache key and §3 hashes a directory File over its contents — a File there would put every byte of the project tree into every entry, so editing any one file would invalidate all of them, which is the exact opposite of what a content-addressed build wants. It hashes as a bare tag, like ctx.cache. What is read through it are ordinary Files that still hash by content, so nothing is given up.

Measured, not asserted

On this checkout, building cJSON:

• cold build compiles three sources;
• warm run: 27 ms, nothing rebuilt;
• editing one source adds exactly two cache entries — that object and the link, not the two untouched objects;
• undoing the edit returns to a hit, at 27 ms, because the key is content and not a timestamp. A timestamp-based tool rebuilds here.

The graph rules are enforced rather than documented: a cycle is reported in full (a -> b -> c -> a) before anything is built, a .needs naming a target that does not exist is a clean error, and nothing may depend on a target that produced no artifact — which is what makes the run node's "produces no artifact" a rule rather than a convention.

Verification

• odin test src — 253 passing, up from 231.
• scripts/wasi_smoke.sh — 31 examples agree native-vs-WASI. WASI cannot start a process, and core:os's backend answers .Unsupported, so exec there reports "running a program is not available on this target" rather than a missing program — no fs_*-style three-way split was needed.
• scripts/editor_keys_test.py (pty), and scripts/playground_browser_test.py against a real Chromium. The playground manifest now skips the vendored checkout: a submodule is one gitlink entry in git ls-files, not its contents, so reading it as a file failed outright.
• The hashmake end-to-end build, plus new CI steps asserting a second build reuses every entry (by counting entries, not wall-clock) and that a cycle is refused.

Five examples with asserted values, and unit tests for what an example structurally cannot show — a denied or malformed call is fatal (§8/§16), so an example that tripped one would end rather than evaluate to anything.

CI is green on all five jobs, Windows included. That was the one target I could not exercise locally, and it found a real problem on the first run: a test of mine asserted ctx.dir's hashing by comparing against sha256 (loadfile "."), which hashes the entire checkout — .git and the submodule's internals included — and the Windows runner cannot open everything in there. It now asserts the property directly, on two constructed handles that must hash alike, which is both the right test and one that reads nothing. The same run caught running-a-program.hb missing from playground_browser_test.py's skip list, which is separate from wasi_smoke.sh's; both now carry a comment pointing at the other.

Worth a second opinion

• ctx.dir as its own type is the largest design decision here (rationale above).
• fold's key ordering, and that it cannot stop early.
• File gained is_executable — not hashed (§3 hashes no permission bit), but it is a change to a core value type. Without it a linked binary stops being runnable after a round trip through the cache, which is exactly what the run node does.
• The root context now names exec and anypath explicitly; behaviour is unchanged, but context-permissions.hb's documented value grew accordingly.
• Smaller calls: exec's .outputs takes regular files only; its scratch lives under the cache directory; a .cmd containing / resolves against that scratch.

import is still unimplemented, so a build description cannot yet span files.

🤖 Generated with Claude Code

https://claude.ai/code/session_01R8FUURkLC3b5axnRKvKUfM