[READ-ONLY] Mirror of https://github.com/crutchcorn/binarrow. An experimental browser runtime for AArch64 Linux ELF executables
binarrow docs rust-compatibility.md
3.2 kB · 63 lines
Markdown
at main

Rust and Cargo compatibility #

The Phase 8 checkpoint packages the official Rust 1.93.0 aarch64-unknown-linux-musl host tools and standard library. Generated toolchains, registry data, build outputs, and snapshots stay in the repository's ignored .tmp directory.

Verified behavior #

  • Dynamically linked guest rustc and Cargo start through the packaged musl loader and report their expected versions.
  • Rustc compiles a checked-in freestanding no_std source file, and packaged LLD links the persisted object into a static AArch64 ELF.
  • Cargo resolves a checksum-locked itoa 1.0.18 dependency from a minimal crates.io sparse-index and crate-archive overlay with --offline --locked.
  • Cargo extracts registry archives and applies their modification times through utimensat without host filesystem access.
  • Cargo compiles and executes the fixture's std-using build.rs child. The script reads OUT_DIR, writes a generated Rust source file, and emits a cargo:rerun-if-changed directive through Cargo's stdout protocol.
  • The project, registry sources, dependency outputs, and incremental target directory survive deterministic filesystem snapshot export and restore.
  • A second verbose Cargo build reports both itoa and the fixture binary as Fresh. Executables from both build snapshots print guest cargo dependency hello and exit 42.

Run the reproducible verifier after building the toolchain:

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

The build script is the only networked stage. It checksum-pins the official Rust distribution and fetches the fixture's committed lockfile into .tmp/cargo-home. The verifier runs its host-side preparation offline, packs only the selected registry records, and gives guest Cargo no network service.

Compatibility policy #

The verified dependency tier is a locked, pure-Rust crate that compiles for the packaged AArch64 musl host without its own build script. The root package may use a single Rust build.rs process for filesystem-based code generation and Cargo stdout directives, as covered by the fixture. A crate belongs to this tier only after the same offline build, build-script execution, cache replay, and resulting-ELF checks pass. Registry resolution alone is not a compatibility claim.

The following remain unverified and outside the current support contract:

  • procedural-macro dependencies built as part of a project;
  • native library discovery and linking;
  • C, C++, assembly, or other compiler invocations from dependencies;
  • build scripts that spawn additional tools, probe the host, or require capabilities beyond the verified environment, output-file, and stdout protocol subset;
  • package-index access or dependency downloads from inside the guest; and
  • general-purpose guest threading beyond rustc's covered cooperative topology.

Cargo may emit a nonfatal warning that it cannot save global-cache last-use data because SQLite advisory locks are not implemented. This does not affect locked dependency resolution or artifact reuse; the verifier treats actual resolution, compilation, or freshness failures as fatal.