vercel-labs--zerolang/skill-data/builds.md

name, description

name	description
builds	Build, run, target, and profile Zero programs.

Zero Builds

Use this when an agent needs to run, build, cross-build, inspect artifacts, or explain target support for a Zero program.

Inputs

Most build commands accept one of these graph-backed inputs:

• a direct .graph or .program-graph artifact
• a package directory containing zero.toml or zero.json
• a direct path to zero.toml or zero.json

When both manifests are present in the same package root, Zero uses zero.toml. Prefer one checked-in manifest unless testing precedence.

For packages, normal check, build, run, test, size, and mem commands compile from the checked-in zero.graph store. When the .0 source projection was edited, those commands refresh the stale store from source first and note it on stderr; set ZERO_STALE=fail to make staleness an error (RGP008) instead. They never rewrite .0 files. Use zero verify-projection when CI or review needs projection drift to fail, and zero export only when a human-readable projection needs regeneration. When already inside a package, omit the input and commands default to the current directory.

Run

Use zero run for the host development loop:

zero run
zero run -- input.txt
zero run examples/hello.graph
zero run examples/cli-file.graph -- input.txt

Arguments after -- are passed to the Zero program.

Build

Use zero build when the user asks for an artifact. It is the normal command for executables, object files, LLVM IR, cross-target artifacts, and CI outputs. Use direct emitters. The removed generated-C backend is not a fallback path.

zero build --emit exe --out .zero/out/app
zero build --emit obj --out .zero/out/app.o
zero build --emit exe examples/hello.graph --out .zero/out/hello
zero build --emit obj examples/hello.graph --out .zero/out/hello.o

Use LLVM only when the request is explicit. LLVM is experimental: it is not the default backend and not release eligible. Textual IR is inspectable with --emit llvm-ir; host executable builds require a ready clang toolchain. LLVM currently lowers scalar code, direct calls, branches, loops, primitive fixed arrays, byte views, readonly strings, and primitive std.mem helpers:

zero build --backend llvm --emit llvm-ir examples/hello.graph --out .zero/out/hello.ll
zero build --backend llvm --emit exe examples/hello.graph --out .zero/out/hello-llvm
zero run --backend llvm examples/hello.graph

Use --json when a tool will read exact build fields:

zero build --json --target linux-musl-x64 examples/memory-package

Useful JSON fields include artifact, sizeBytes, toolchain, releaseTargetContract, selected target facts, linker flavor, and sysroot status.

Graph Inputs

When an agent is authoring a repository graph package, patch the package graph and use normal build/run commands. They compile from zero.graph and do not require .0 projections to exist:

zero patch --op 'addMain'
zero run
zero build --out .zero/out/app

Use zero export when humans need checked-in .0 projections. After a human edits a projection, the next graph-store compile refreshes the store automatically, or run zero import to refresh it explicitly. zero status reports the active store format.

Build, run, test, size, and mem commands maintain a derived final-MIR cache in the native cache, keyed by graph hash, compiler version, target, emit kind, and backend request. Agents should not patch .zmir files; JSON outputs report cache reuse in a mappedFinalMir row.

If another tool hands you a standalone .program-graph, normal zero build and zero run can validate it as an interchange artifact. Do not create a standalone graph artifact for the ordinary package loop; use the package path so the compiler reads zero.graph directly.

Targets

Inspect target names and capability facts before cross-building:

zero targets
zero check --target linux-musl-x64 examples/memory-package
zero inspect --target linux-musl-x64 examples/memory-package

Hosted APIs such as process args, environment, filesystem, net, and proc are target-gated. A non-host target may reject code that checks on the host.

Profiles

Common profile names are debug, dev, release-fast, release-small, tiny, and audit.

zero build --profile release-small examples/hello.graph
zero size --profile tiny examples/hello.graph

Use zero size to explain retained functions, sections, literals, runtime shims, imports, debug metadata, and optimization hints. Add --json when a tool needs exact fields. Use zero size --backend llvm when the question is specifically about the explicit LLVM backend; the report includes LLVM target triple, optimization level, retained runtime/helper facts, toolchain readiness, and direct-vs-LLVM comparison rows.

Troubleshooting

• zero doctor checks host and target readiness.
• zero doctor --json reports llvmToolchain readiness for explicit LLVM host builds.
• LLVM JSON facts include backendLifecycle so tools can distinguish explicit experimental readiness from release support.
• BLD003 means an old backend flag was requested; remove it.
• BLD004 with backendBlocker.backend: "llvm" means the selected LLVM artifact, target, command, MIR subset, or clang toolchain is not ready.
• Missing sysroot facts identify the required ZERO_SYSROOT_* variable.
• Unsupported targets fail explicitly instead of silently choosing another backend.