Kakehashi: An Experimental macOS-on-Linux ARM64 Translation Layer

Kakehashi is a specialized userspace translation layer designed to execute macOS ARM64 binaries on Linux aarch64 systems. It operates as a CLI-first tool and notably avoids the use of a Just-In-Time (JIT) compiler.

🛠️ Core Mechanism

The project achieves binary compatibility by:

Loading Darwin Mach-O files on a Linux aarch64 host.
Mapping a freestanding version of libSystem.
Translating BSD syscalls to their Linux equivalents.
Running actual guest applications (e.g., curl, 7zz, and clang probes).

🚀 Getting Started

Installation

You can install Kakehashi via Rust's package manager:

Install Rust 1.88+
Run cargo install kakehashi (or cargo install --path crates/kh-cli --force from source)
Initialize the environment: kh bottle ensure

Deploying Guest Binaries

Use the kh install command to fetch Darwin binaries into the "bottle":

kh install 7zip  # Installs Darwin 7zz to /usr/local/bin/7zz
kh install curl  # Installs Darwin curl to /usr/local/bin/curl

Note: Relative paths for -o / archives are resolved against the host's current working directory (CWD). The system handles O_CREAT via auto-mkdir.

The Bridge: The path /Volumes/linux/ within the bottle acts as a portal to the host's root directory (/).

🧪 Execution Examples

1. 7-Zip (`7zz`)

Kakehashi supports multi-threaded compression, which serves as a critical correctness gate.

Action	Command
Check Version	`kh run 7zz -- --help`
Create Archive	`kh run 7zz -- a demo.7z README.md`
Test Archive	`kh run 7zz -- t demo.7z`
Extract	`kh run 7zz -- x -o./out demo.7z`
Multi-thread	`kh run 7zz -- a -t7z -m0=lzma2 -mx=5 -mmt=4 mt.7z README.md`

Docker Integration: Use ./scripts/docker-7zz.sh for automated tests. For hypercall testing, use: KAKEHASHI_HYPERCALL=1 ./scripts/docker-7zz.sh a -t7z ...

2. curl

Testing ranges from basic banners to complex HTTPS requests.

Basic: kh run curl -- --version
HTTP GET: kh run curl -- -sS -o .tmp/kh-out/body http://example.com/
HTTPS (SSL): kh run curl -- -sS -o .tmp/kh-out/https-body https://example.com/
- Requires OpenSSL + bottle CA bundle.
Failure Case: Requests to https://self-signed.badssl.com/ should return a non-zero exit code.

⚠️ Current Status & Limitations

Kakehashi is an experimental project, not a finished product.

What is NOT yet supported:

~~Full Security.framework or CoreFoundation (stubs are used instead)~~
~~GUI Applications~~
~~Full git / Command Line Tools (CLT)~~
~~Code signing~~
~~Complete HTTP/3 or complex POST bodies in curl~~

Common Logs/Warnings:

ENOENT(openat) path=/etc/ssl/openssl.cnf: Harmless; OpenSSL uses the seeded CA bundle instead.
WARN … skip dylib …: Occurs when Apple frameworks are missing from the bottle.
unresolved strong symbol: Only an issue if the symbol is hit during the "happy path."

🏗️ Technical Architecture

Crate Breakdown

The project is split into several Rust crates:

Crate	Responsibility
`kakehashi`	The primary CLI binary.
`kh-loader`	Handles Mach-O parsing, mapping, and execution.
`kh-runtime`	Manages memory, traps, and BSD syscalls; embeds `libSystem.B.dylib`.
`kh-libsystem`	The source for the dylib (compiled only on `aarch64-apple-darwin`).

Implementation Detail: The guest dylib is stored at crates/kh-runtime/resources/libSystem.B.dylib and integrated into the runtime using the include_bytes! macro.

System Requirements

OS: Linux aarch64 (Bare metal, VM, or Docker/Colima).
Memory Page Sizes: Supports $4\text{ KiB}$ (standard containers) and $16\text{ KiB}$ (Asahi Linux).
Dependencies: curl/wget and tar for binary installation.

Bottle File Structure

The default root is ~/.local/share/kakehashi/bottle/ (configurable via KAKEHASHI_ROOT).

Host Path	Guest Path
`.../bottle/usr/local/bin/7zz`	`/usr/local/bin/7zz`
`.../bottle/usr/local/bin/curl`	`/usr/local/bin/curl`
`.../bottle/usr/lib/libSystem.B.dylib`	`/usr/lib/libSystem.B.dylib`

Next Milestone: Implementing git via kh install xcode-tools.