# AArch64 Rust host toolchain

This Phase 8 checkpoint packages the official Rust 1.93.0
`aarch64-unknown-linux-musl` host compiler, Cargo, and target standard library
as an immutable Binarrow filesystem image. All three January 22, 2026 Rust
distribution archives are pinned by SHA-256. Downloads, extracted components,
the roughly 580 MiB stripped image, and every cache stay under the repository's
ignored `.tmp` directory.

Prerequisites:

- Zig 0.16.0
- `llvm-objcopy`
- the repository Rust toolchain
- `curl`, `make`, `tar`, and `shasum`

Build and run the host-tool and source-to-ELF verification:

```sh
toolchains/rust-musl/build.sh
toolchains/rust-musl/verify.sh
toolchains/rust-musl/verify-browser.sh
```

Rust's host tools expect `libgcc_s.so.1`; the package produces that
compatibility DSO from the PIC LLVM `libunwind.a` distributed in the official
musl standard-library component, selected Zig compiler-rt builtins, and the
frame-registration compatibility entry points required by the bundled LLD.
The guest musl loader resolves the driver, compiler proc-macro DSOs, libc,
unwind runtime, and linker.

The verifier first checks rustc's exact version, then compiles a checked-in
`no_std` source file with one codegen unit and panic abort. It invokes the
packaged LLD over the persisted object and finally runs the static ELF, which
prints `guest rustc hello` and exits 42. All object, linker, and filesystem
snapshots remain under `.tmp`.

The Cargo checkpoint uses a locked project with the pure-Rust `itoa` crate
from crates.io. The host build script fetches that exact lockfile into the
repository-local Cargo home. The verifier then packs only the selected crate
archive, sparse-index entry, and registry configuration into a separate guest
overlay. Guest Cargo resolves and extracts the dependency with `--offline
--locked`; it has no network fallback. The resulting target directory is
exported with the project snapshot, a second verbose build must report both
crates as `Fresh`, and the executable from each snapshot must print `guest
cargo dependency hello` and exit 42. The project also runs a minimal guest
`build.rs`, persists its generated `OUT_DIR` source, and includes that source
in the final executable.

The browser verifier imports the completed Cargo workspace, uses guest Cargo
to clean its target directory, and starts a real cold rebuild. It terminates
the active Worker while that build is running, waits for the replacement
Worker, and checks that the committed OPFS snapshot was not replaced. Partial
compiler output therefore cannot replace the last completed workspace.

This checkpoint supports locked, pure-Rust dependencies that compile for the
packaged `aarch64-unknown-linux-musl` host and minimal target-local build
scripts that use the supported process, pipe, environment, and filesystem
surface. The Rust-only toolchain installs compatibility guards for common
native compilers, native discovery/build tools, shells, and host-probing tools.
If a build script invokes one, it exits with a stable `binarrow compatibility
error` explaining which compatibility tier was exceeded instead of surfacing
an ambiguous missing-program error. The verifier executes representatives of
both guard classes through the same guest `execve` path used by build scripts.

Procedural macros, host-probing build scripts, native library discovery, C/C++
compilation, and dependencies that require network access are not yet part of
the compatibility contract. The intentionally minimal registry overlay is a
fixture for deterministic offline resolution, not a general registry mirror.

Rustc's bounded cooperative thread topology includes its signal waiter,
compiler worker, nested helpers, and coordinator/worker pair. Futex wait/wake,
thread IDs, final artifact copying, and compiler/linker memory requirements are
covered without exposing host threads. General-purpose guest threading remains
outside this checkpoint.