Kakehashi
Userspace macOS ARM64 → Linux aarch64 translation layer. CLI-first, no JIT, no instruction emulator.
It loads Darwin Mach-O binaries on Linux, maps a freestanding libSystem,
translates BSD syscalls at the guest–host boundary, and runs real tools
natively on aarch64.
Live execution (kh run) |
Linux aarch64 only (bare metal, UTM, Colima/Docker) |
| Dry-load / inspect | Any host (including macOS) |
| Design docs | docs/ |
Quick start
# or from a checkout:
Relative paths use the host CWD of kh. Guest /Volumes/linux/… maps to
the host root (/ → host /).
What works
Verified on Docker/Colima and UTM (Linux aarch64). Guest code runs as native ARM64; the runtime only intervenes at syscalls, threads, and faults.
7-Zip
# Multi-thread correctness gate:
curl
Details: docs/curl.md.
Apple git (CLT)
Milestone met (G0–G8): local repos, HTTPS/SSH clone and push, large remotes (Wine full history, llvm shallow, …).
Details: docs/git.md.
Apple clang (CLT)
Milestone met (G0–G5 + LTO): --version, compile, multi-file link with modern
ld, -flto, and run of the produced Mach-O under kh.
# Multi-file driver link + run product under kh (see docs/clang.md)
Same install as git: kh install xcode-tools. Details: docs/clang.md.
Not claimed yet
Full curl feature surface, real Apple Security.framework, git LFS/svn, GUI,
codesign, full macOS app stack. Multi‑GiB monorepo clones under a fixed wall
budget are best-effort. Nested clang/ld processes still pay a start tax
(process model), not a correctness gap.
How it works (short)
- Resolve the bottle (guest FS root + freestanding
libSystem.B.dylib). - Load Mach-O + dylibs; bind symbols; wire the BSD hypercall into the runtime.
- Jump to
LC_MAIN; guest ARM64 runs natively. - Syscalls / helpers / pthread create-exit cross into
kh-runtimeand back.
Not derived from Darling. No proprietary Apple blobs in-tree. Clean-room process:
docs/legal-method.md.
Crates
| Crate | Role |
|---|---|
kakehashi |
Binary kh (install this) |
kh-loader |
Mach-O parse, map, bind, execute |
kh-runtime |
Memory, traps, BSD syscalls, bottle, threads; embeds libSystem.B.dylib |
kh-libsystem |
Freestanding dylib source (aarch64-apple-darwin only) |
kh-xcrun |
Clean-room guest xcrun (CLT helper) |
kh-libsystem layout
Source mirrors Darwin surfaces (single product dylib, not multi-dylib link):
crates/kh-libsystem/src/
core/ # syscalls, errno, heap, process, host helpers
dylib/ # libsystem_c, pthread, libcurl, libc++, libz, …
frameworks/ # CoreFoundation, Security, CoreServices (soft)
After freestanding ABI changes:
Requirements
- Rust 1.88+
- Linux aarch64 for live
kh run/kh trace - Page sizes: 4 KiB (containers) and 16 KiB (Asahi-class)
Performance (honest)
Guest code runs natively. Cost is boundary × crossings (TLS, alt stack, NEON, dispatch), not an emulator.
Multi-file 7zz (mx=5 mmt=4, ~14.5k files / ~309 MiB) on bare-metal aarch64:
about ×1.24 vs native Linux 7zz. Nested Apple clang still pays process-start
tax per -cc1/ld hop; load path has been optimized, wall is not macOS parity.
CI goal is correctness on cheap Linux arm64, not wall-clock parity with macOS.
See docs/roadmap.md.
Develop / test
| Goal | Command |
|---|---|
| Unit + clippy | cargo test / clippy (exclude kh-libsystem) |
| Docker smoke | ./scripts/docker-smoke.sh |
| Darwin tools | ./scripts/docker-kh.sh 7zz|curl|git|clang -- … |
| Stage libSystem | ./scripts/stage-libsystem.sh |
Artifacts under host .tmp/ (gitignored). Guest /Volumes/linux/out/… maps to
.tmp/kh-out/ via Docker helpers.
License
Apache-2.0 — LICENSE.txt, NOTICE.
Contributing: CONTRIBUTING.md. Architecture and milestones:
docs/.