Improve build output to use shared dependencies and better output path

[3esmit]

Summary

Fixes #211

• Add make build-programs as the repo-level command for building every RISC
  Zero guest program binary.
• Build amm, ata, stablecoin, token, and twap_oracle in one Docker
  BuildKit build with shared Cargo git, registry, and target cache mounts.
• Package each raw guest ELF into the deployable RISC Zero .bin format and
  export only those final program binaries into target/guest/.
• Keep per-program guest target/ directories out of the checkout output; stale
  per-program guest targets are removed when make build-programs writes the
  root-level binaries.
• Add .dockerignore entries so local target directories and .git are not
  sent into the Docker build context.
• Document the shared build path, output locations, and cache/image override
  environment variables.

Build Output

make build-programs writes deployable program binaries to:

target/guest/<program>.bin

The exported directory contains only the five deployable .bin files. It does
not export raw guest ELFs, deps, .fingerprint, incremental state, or other
per-program RISC Zero target-tree artifacts.

The shared BuildKit caches are keyed by RISC0_BUILD_CACHE_ID and stored in
Docker BuildKit cache storage. By default the cache ID prefix is:

lez-programs-risc0-guests

The cache mounts are:

• ${RISC0_BUILD_CACHE_ID}-cargo-git
• ${RISC0_BUILD_CACHE_ID}-cargo-registry
• ${RISC0_BUILD_CACHE_ID}-target

Benchmarks

Clean full guest build across all programs:

• old per-guest build: 217.78s
• shared BuildKit build: 70.94s
• improvement: 146.84s faster, 67.43% less wall time, 3.07x speedup

Ignored workspace build output:

• old per-guest output: 953,390,236 bytes (927M du -sh)
• shared-output build: 1,687,512 bytes (1.7M du -sh)
• saved: 951,702,724 bytes (907.61 MiB)
• reduction: 99.82%
• old output is 564.97x larger than the shared-output build

Most of the old checkout footprint is duplicated dependency output:

• old docker/deps total: 952,769,542 bytes (908.63 MiB)
• shared-output docker/deps total: none exported to the checkout
• shared-output branch stores reusable deps in Docker BuildKit cache instead,
  keyed by RISC0_BUILD_CACHE_ID

BuildKit-cache:

• current shared build used fresh cache mounts totaling about 1.431GB:
  128.4MB cargo git cache, 293.3MB cargo registry cache, and 1.009GB
  shared target cache
• current shared build exported 1,687,512 bytes (1.7M du -sh) into the
  checkout
• old per-guest cache measurement reached 11.4GB cache plus 759.3MB exported
  output before a repeated Cargo/libgit2 fetch hang prevented completing the
  final guest in an isolated builder
• using the full old checkout output size with that partial cache gives a lower
  bound of 12.35GB required by main versus about 1.432GB required by this
  branch for the fresh cache mounts plus exported output
• observed lower bound: shared build is at least 10.92GB smaller when counting
  BuildKit cache mounts plus exported output

Compatibility checks:

• spel inspect accepts the generated target/guest/<program>.bin outputs for
  all programs.
• target/guest/ata.bin from make build-programs matched the
  cargo risczero build output byte-for-byte in a SHA-256 check.

[Copilot]

Pull request overview

This PR introduces a repo-level, shared-cache Docker BuildKit pipeline for building and packaging all RISC Zero guest programs, producing only deployable .bin artifacts in a single consistent output directory (target/guest/).

Changes:

• Adds make build-programs to build all guest programs via a shared BuildKit build (scripts/build-guests.sh + scripts/build-guests.Dockerfile).
• Introduces a new risc0-packager tool to convert each built guest ELF into a deployable RISC Zero .bin.
• Updates ignore rules and documentation to reflect the new shared-build output paths and reduced checkout footprint.

Reviewed changes

Copilot reviewed 8 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tools/risc0-packager/src/main.rs	Adds a CLI tool to package guest ELFs into RISC Zero .bin binaries.
tools/risc0-packager/Cargo.toml	Defines the new risc0-packager crate and dependencies.
scripts/build-guests.sh	New top-level build script driving a single BuildKit build and exporting target/guest/*.bin.
scripts/build-guests.Dockerfile	New Dockerfile building all guests with shared BuildKit caches and exporting only packaged .bin outputs.
Makefile	Adds build-programs target to standardize the guest build entrypoint.
CLAUDE.md	Documents the new build flow and output locations for guest binaries.
Cargo.toml	Adds tools/risc0-packager to the workspace members.
Cargo.lock	Locks dependencies for the new risc0-packager crate.
.gitignore	Simplifies ignores by removing per-guest target/ entries (root target/ already covers them).
.dockerignore	Excludes local build output and VCS metadata from Docker build context.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 11 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 11 changed files in this pull request and generated no new comments.

[3esmit]

@vpavlin Requested your opinion, since @jimmy-claw submitted a PR to risk zero regarding BulidKit.