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 needs Linux aarch64 (bare metal, VM, or Colima/Docker).
kh inspect and kh run --dry-load work on any host (including macOS).
Crates (crates.io)
| Crate | Role |
|---|---|
kakehashi |
Binary kh (install this) |
kh-loader |
Mach-O parse, map session, execute |
kh-runtime |
Memory, traps, BSD syscalls, bottle; embeds freestanding libSystem.B.dylib |
kh-libsystem |
Source for that dylib (build for aarch64-apple-darwin; not a Linux host crate) |
The freestanding guest dylib is vendored at
crates/kh-runtime/resources/libSystem.B.dylib and compiled into the runtime
with include_bytes!. Publishing kh-runtime to crates.io therefore 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+tarforkh install 7zip
Install (global, updatable)
# crates.io:
# From a git checkout (dev):
# Update later:
Prepare a bottle (macOS-like root). Freestanding libSystem is embedded — no separate dylib path required:
# → installs embedded libSystem.B.dylib into the bottle
# Optional: install Darwin 7-Zip into the bottle at a *real* macOS path
# → guest /usr/local/bin/7zz = {bottle}/usr/local/bin/7zz
# same as:
Bottle layout mirrors macOS (/usr/local/bin, /usr/lib, /Volumes/linux → host /, …).
Paths under the bottle are guest absolute paths after translation.
| Host (default) | Guest |
|---|---|
~/.local/share/kakehashi/bottle/ |
/ |
…/bottle/usr/local/bin/7zz |
/usr/local/bin/7zz |
…/bottle/usr/lib/libSystem.B.dylib |
/usr/lib/libSystem.B.dylib |
…/bottle/Volumes/linux/… |
/Volumes/linux/… → host FS |
Override with KAKEHASHI_DATA_DIR / KAKEHASHI_CONFIG_DIR / KAKEHASHI_ROOT.
Quick start (Docker / Colima on Apple Silicon)
# Dev image + unit tests
# Full smoke image (build + clippy + test + micro run)
# or: ./scripts/docker-smoke.sh
Build
# Host CLI + runtime (on Linux aarch64, or inside the Docker image above)
# Guest libSystem (maintainers: refresh crates.io embed after API changes)
# → dist/guest/libSystem.B.dylib
# → crates/kh-runtime/resources/libSystem.B.dylib (commit before publish)
Bottle (macOS-like root for the guest)
# or override with a just-built tree:
Discovery for libSystem: --libsystem → KAKEHASHI_LIBSYSTEM → paths next
to kh → dist/guest/ / target/… / crate resources/ → embedded bytes
in kh-runtime.
Guest tools (kh install)
Packages are installed into the bottle at conventional macOS locations
(not into a random host cache). List: kh install list.
Testing map (what to run, where results land)
| Goal | Command | Where to look |
|---|---|---|
| Unit tests | cargo test --workspace --exclude kh-libsystem |
terminal pass/fail |
| Full Docker smoke | ./scripts/docker-smoke.sh |
terminal; ends with smoke ok |
| Synthetic fixtures | kh run --expect-code … tests/fixtures/… |
stdout + exit code (see tests/fixtures/README.md) |
| Clang probes | kh run --root tests/fixtures/bottle tests/clang-probe/puts_hello |
stdout hello (see tests/clang-probe/README.md) |
Real guest 7zz |
./scripts/docker-7zz.sh … |
host .tmp/kh-out/ (default) |
| Fair CPU bench | ./scripts/bench-fair-local.sh |
host .tmp/kh-bench-fair/ |
All of .tmp/, .kh/, and target/ are gitignored. Nothing important is
hidden only inside a throwaway container without a copy-out step.
Guest path ↔ host path (Docker helpers)
When kh runs in Docker, the bottle bridges the Linux filesystem as
/Volumes/linux/…:
| You pass to the guest | Actually on the host |
|---|---|
/Volumes/linux/src/README.md |
<repo>/README.md (repo bind-mount) |
/Volumes/linux/out/demo.7z |
<repo>/.tmp/kh-out/demo.7z (durable, default for docker-7zz.sh) |
/Volumes/linux/src/.tmp/foo.7z |
<repo>/.tmp/foo.7z (also durable) |
/Volumes/linux/tmp/….7z |
container /tmp/… — gone after docker run --rm |
Try it
# Any host — map only
# Linux aarch64 live (fixtures + clang probes)
Example guest: 7-Zip
7-Zip is only an optional installed tool (first real-world target), not the product focus.
Docker helper (dev loop; uses embedded libSystem unless you staged a rebuild):
Regenerate synthetic fixtures:
Fair bench (native Linux 7zz vs kh + Darwin 7zz)
One random blob on container-local /tmp (not Virtio-FS), then both
compressors write archives that are copied to the host so you can inspect
them.
SIZE_MB=64 MMT=1
KAKEHASHI_HYPERCALL=0
Where the files are (host)
.tmp/kh-bench-fair/ ← override with KH_BENCH_OUT=
README.txt how to re-check without re-running
summary.txt timings, ratio, archive=ok lines
native.log kh.log compressor stdout
bin/7zz Linux aarch64 7zz (downloaded once)
artifacts/
native.7z from host Linux 7zz
kh.7z from Darwin 7zz under kh
*.sha256 sizes.txt checksums + byte sizes
verify-native.txt verify-kh.txt full `7zz t` output
run-meta.txt size / mx / mmt / hypercall / nproc
Re-verify yourself
Test archive integrity with any 7-Zip:
# macOS: brew install sevenzip → 7zz
# or reuse the Linux binary the bench downloaded (Linux aarch64 host / same Docker image):
Guest Darwin 7zz and Linux 7zz are different binaries — compare
hypercall vs KAKEHASHI_HYPERCALL=0 for path overhead, not absolute
“native × N” across product versions.
Performance knobs
- Freestanding hypercall is on by default for the main guest thread
(no
SIGTRAPon the I/O hot path). Opt out withKAKEHASHI_HYPERCALL=0. - Guest worker threads use
svc→brkby default (7zz MT NEON compression is green there). Experimental full-worker hypercall:KAKEHASHI_HYPERCALL_WORKERS=1(still SEGV under-mmt>1 -mx>0). - Worker
pthread_joincompletion is published from the host stack afterbsdthread_terminate.
Scripts
| Script | Purpose |
|---|---|
scripts/stage-libsystem.sh |
Build product → dist/guest/ and crates/kh-runtime/resources/ (crates.io embed) |
scripts/install-linux.sh |
Local cargo build + install kh + bottle ensure |
scripts/docker-smoke.sh |
Reproducible smoke suite inside Dockerfile image |
scripts/docker-7zz.sh |
Interactive/ad-hoc Darwin 7zz under kh (outputs → .tmp/kh-out) |
scripts/bench-fair-local.sh |
Timed 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.