kh-loader 0.1.5

Kakehashi Mach-O loader and process environment setup
Documentation

Kakehashi

Userspace macOS ARM64 → Linux aarch64 translation layer (CLI-first, no JIT).

Load Darwin Mach-O on Linux aarch64, map a freestanding libSystem, translate BSD syscalls, and run real guests (clang probes, 7-Zip 7zz, threads).

Live execution Linux aarch64 (bare metal, VM, Colima/Docker)
Dry-load / inspect Any host (including macOS)
Design reference docs/

Crates

Crate Role
kakehashi Binary kh (install this)
kh-loader Mach-O parse, map, execute
kh-runtime Memory, traps, BSD syscalls, bottle; embeds freestanding libSystem.B.dylib
kh-libsystem Source for that dylib (aarch64-apple-darwin only; not a Linux host crate)

The guest dylib is vendored at crates/kh-runtime/resources/libSystem.B.dylib and compiled into the runtime with include_bytes!. Publishing kh-runtime ships the dylib; end users do not need a separate download.

Requirements

  • Rust 1.97+
  • Linux aarch64 for live kh run / kh trace
  • Page sizes: 4 KiB (containers) and 16 KiB (Asahi-class)
  • Optional: curl/wget + tar for kh install 7zip

Install

cargo install kakehashi
# or from a checkout: cargo install --path crates/kh-cli

kh bottle ensure          # embeds libSystem into the bottle
kh install 7zip           # optional: Darwin 7zz → guest /usr/local/bin/7zz
kh run 7zz -- a /tmp/demo.7z ./README.md

Bottle layout

Default root: ~/.local/share/kakehashi/bottle/ (override with KAKEHASHI_DATA_DIR / KAKEHASHI_ROOT).

Host Guest
…/bottle/ /
…/usr/local/bin/7zz /usr/local/bin/7zz
…/usr/lib/libSystem.B.dylib /usr/lib/libSystem.B.dylib
…/Volumes/linux/… /Volumes/linux/… → host FS

Performance (honest)

Kakehashi runs guest code natively on the CPU. The tax is the syscall boundary (TLS switch, alt stack, NEON save/restore, Rust dispatch) × how chatty the guest is — not an instruction emulator.

Measured gap

On Ubuntu aarch64 bare-metal (UTM), multi-file 7zz archive (-t7z -m0=lzma2 -mx=5 -mmt=4, ~8k files / ~240 MiB tree):

native Linux 7zz Darwin 7zz under kh ratio
wall ~22.5 s ~118 s ~×5.2

On compression-heavy, few-file samples the gap is often much smaller (~×1.1–1.2). The large multi-file gap is dominated by path walk + per-syscall boundary, not “wrong LZMA”.

Hypercall is on by default for all guest threads. Opt out with KAKEHASHI_HYPERCALL=0 only for debug (residual svc→brk / SIGTRAP).

Why ~×5 is still useful in CI

The product goal for CI is not “as fast as native macOS,” but run Darwin CLI/tools on cheap Linux aarch64 runners instead of scarce, expensive macOS capacity.

GitHub Actions hosted runners (private-repo overage rates, USD per minute; see Actions runner pricing):

Runner Per-minute rate
Linux 2-core arm64 $0.005
Linux 2-core x64 $0.006
macOS 3–4 core (M1/Intel) $0.062
macOS larger (e.g. 12-core / M2 Pro) $0.077–$0.102

macOS standard is roughly ×10–×12 the Linux arm64 minute rate before any wall-time difference. Even if a job runs ×5 slower under kh on Linux arm64 than the same work on a macOS runner, billable cost can still be lower because the macOS minute is an order of magnitude more expensive (illustrative: 5 × $0.005 ≈ $0.025 vs 1 × $0.062). Public-repo free minutes and self-hosted Linux amplify that further; macOS hosted capacity also tends to queue longer and (on GitLab SaaS) is Premium/Ultimate / beta-gated.

When macOS runners still win: GUI, codesign/notarization, Xcode UI tests, or any workload that is not a pure CLI Darwin binary under freestanding libSystem.

Gates, not benches: CI correctness is cargo test / smoke / 7zz -mmt=4, not “match native wall clock.” Perf work is tracked in docs/roadmap.md.

Quick start (Docker / Colima on Apple Silicon)

docker build -t kakehashi:dev -f Dockerfile.dev .
docker run --rm -v "$PWD":/src -w /src kakehashi:dev \
  cargo test --workspace --exclude kh-libsystem

# Full smoke (build + clippy + test + micro run)
./scripts/docker-smoke.sh

Build

cargo build -p kakehashi --release
cargo test --workspace --exclude kh-libsystem
cargo clippy --workspace --exclude kh-libsystem --all-targets -- -D warnings

# Maintainers: refresh embed after freestanding ABI changes
cargo build -p kh-libsystem --release --target aarch64-apple-darwin
./scripts/stage-libsystem.sh   # → crates/kh-runtime/resources/libSystem.B.dylib

libSystem discovery: --libsystem → KAKEHASHI_LIBSYSTEM → paths next to kh → crate resources/ → embedded bytes in kh-runtime.

Testing map

Goal Command Artifacts
Unit tests cargo test --workspace --exclude kh-libsystem terminal
Docker smoke ./scripts/docker-smoke.sh ends with smoke ok
Fixtures kh run --expect-code … tests/fixtures/… see tests/fixtures/README.md
Clang probes kh run --root tests/fixtures/bottle tests/clang-probe/puts_hello stdout hello
Real Darwin 7zz ./scripts/docker-7zz.sh … host .tmp/kh-out/
Fair CPU bench ./scripts/bench-fair-local.sh host .tmp/kh-bench-fair/

.tmp/, .kh/, and target/ are gitignored.

Guest path ↔ host path (Docker helpers)

Bottle bridges the Linux FS as /Volumes/linux/…:

Guest path Host
/Volumes/linux/src/README.md <repo>/README.md
/Volumes/linux/out/demo.7z <repo>/.tmp/kh-out/demo.7z (durable; default for docker-7zz.sh)
/Volumes/linux/tmp/… container /tmp/… — gone after docker run --rm
./scripts/docker-7zz.sh a /Volumes/linux/out/demo.7z /Volumes/linux/src/README.md
ls -lh .tmp/kh-out/demo.7z

Multi-thread correctness gate (Linux aarch64 / Docker):

KAKEHASHI_HYPERCALL=1 ./scripts/docker-7zz.sh a -t7z -m0=lzma2 -mx=5 -mmt=4 \
  /Volumes/linux/out/mt.7z /Volumes/linux/src/README.md
./scripts/docker-7zz.sh t /Volumes/linux/out/mt.7z

Scripts

Script Purpose
scripts/stage-libsystem.sh Build product → crates/kh-runtime/resources/
scripts/install-linux.sh Local build + install kh + bottle ensure
scripts/docker-smoke.sh Smoke suite inside Dockerfile image
scripts/docker-7zz.sh Darwin 7zz under kh (outputs → .tmp/kh-out)
scripts/bench-fair-local.sh Native vs kh compress (artifacts → .tmp/kh-bench-fair)

License

LGPL-3.0-only. See LICENSE.txt and NOTICE.

This project is not derived from Darling. Do not vendor proprietary Apple SDKs or blobs.