Userspace macOS ARM64 → Linux aarch64 トランスレーションレイヤー

Linux aarch64 アーキテクチャ上で Darwin Mach-O ビナリを実行し、自立型の

libSystem

clang probes

7-Zip 7zz

curl

概要

• 実行中の処理 (Live execution):
  • Linux aarch64（ベアメタル、VM、Colima/Docker など）
• 読み込み/検査のみ (Dry-load / inspect):
  • 任意のホスト（macOS を含む）
• 設計参照:

  docs/

動作確認済み機能

Docker/Colima および UTM (Linux aarch64) 環境で検証済み。一度インストールするだけで以下が利用可能です。

cargo install kakehashi
# またはチェックアウトしたリポジトリから:
cargo install --path crates/kh-cli --force

ボトル（Bottle）の管理

kh bottle ensure

ゲストアプリのインストール

kh install 7zip    # Darwin の 7zz → ゲスト環境 /usr/local/bin/7zz
kh install curl    # Darwin の curl → ゲスト環境 /usr/local/bin/curl

注意: 相対パス

-o

とアーカイブのパスは、

kh

プロセスが実行されているホストの現在作業ディレクトリ（CWD）に対して解決されます。親ディレクトリを独自に作成するか、

O_CREAT

の自動作成機能を利用してください。

• ボトルを通じて、

  /Volumes/linux/…

  はホストのルートディレクトリにブリッジされ、**

  / → /host

  **となります。

7-Zip (7zz) の使用方法

バージョン表示とヘルプ

kh run 7zz --
kh run 7zz -- --help

アーカイブの作成（現在のディレクトリ相対パス）

kh run 7zz -- a demo.7z README.md
kh run 7zz -- t demo.7z
kh run 7zz -- l demo.7z
kh run 7zz -- x -o./out demo.7z

マルチスレッド圧縮の検証（正しさゲート）

# マルチスレッドで圧縮する (-mmt=4)
kh run 7zz -- a -t7z -m0=lzma2 -mx=5 -mmt=4 mt.7z README.md
# 結果を確認
kh run 7zz -- t mt.7z
# 期待される動作: "Everything is Ok" の表示、終了コード 0

Docker 補助スクリプト

ホストの

.tmp/kh-out/

KAKEHASHI_HYPERCALL=1

./scripts/docker-7zz.sh --help
./scripts/docker-7zz.sh a /Volumes/linux/out/demo.7z /Volumes/linux/src/README.md
ls -lh .tmp/kh-out/demo.7z

# Hypercall 有効状態での圧縮テスト
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

curl の使用方法

バナー表示 (G1)

kh run curl -- --version

HTTP GET → ファイルへ保存 (G3 / G5)

親ディレクトリが存在しない場合は自動作成されます。

• 期待される動作: 終了コード 0、約 559 バイト、HTML が "Example Domain" を含む。

# ファイルへの保存
kh run curl -- -sS -o .tmp/kh-out/body http://example.com/
wc -c .tmp/kh-out/body
head -c 80 .tmp/kh-out/body; echo

# HTTP レスポンスを標準出力へ
kh run curl -- -sS http://example.com/ | head -c 80; echo

HTTPS GET (G4) — OpenSSL + Bottle CA

ホストまたは

curl.se

kh run curl -- -sS -o .tmp/kh-out/https-body https://example.com/
wc -c .tmp/kh-out/https-body

負のケース：不正な証明書

失敗する必要があります（

rc ≠ 0

kh run curl -- -sS -o /dev/null https://self-signed.badssl.com/; echo exit:$?

Docker 補助スクリプト

./scripts/docker-curl.sh --version
./scripts/docker-curl.sh -sS -o /Volumes/linux/out/body http://example.com/
./scripts/docker-curl.sh -sS -o /Volumes/linux/out/https-body https://example.com/
ls -lh .tmp/kh-out/body .tmp/kh-out/https-body

# トレースファーストプローブのログは → .tmp/kh-curl-probe/
./scripts/docker-curl-probe.sh --version

# オプション行列（大規模テスト）→ .tmp/kh-curl-options/
./scripts/docker-curl-options.sh tier1
./scripts/docker-curl-options.sh tier9-10
./scripts/docker-curl-options.sh all          # tier1..10 をすべて実行

複数回実行時の無害なノイズ

• kh: open fail ENOENT(openat) path=/etc/ssl/openssl.cnf

  — OpenSSL のオプション構成ファイル；HTTP/HTTPS はシードされた CA バンドルを通じて引き続き動作します。

• WARN … skip dylib … Security/CoreFoundation

  — ボトルに含まれていない Apple フレームワーク；ロードパスをカバーするための**ソフトステブ（スタブライブラリ）**が機能します。

• unresolved strong symbol; bound to named missing trampoline

  — ハッピーパス（正常な場合）では触られないシンボルです。

詳細とゲート:

docs/curl.md

プロジェクト構造と検証ゲート (Gates)

tests/clang-probe/

tests/fixtures/

kh bottle ensure

kh-libsystem

まだ製品としての保証ではありません

• curl の完全な機能セット（POST ボディ、プロキシ、HTTP/3 全体エンドツーエンド、全てのスキームなど）。
• 本物の Apple Security.framework。
• 含まれていないもの: git / CLT (Command Line Tools)、GUI アプリ、codesign など。
• 次の製品スライス:

  kh install xcode-tools

  を用いた

  git

  — 詳細は

  docs/git.md

  を参照。

ライブラリ（Crates）一覧

kh

libSystem.B.dylib

ゲスト用 dylib は

crates/kh-runtime/resources/libSystem.B.dylib

にベンダリングされ、コンパイル時に

include_bytes!

を使用して runtime に組み込まれます。

kh-runtime

を公開すると dylib が含まれるため、エンドユーザーは別途ダウンロードする必要はありません。

要件事項

• Rust: 1.88 以上
• ホスト: 実機実行 (

  kh run

  ) /

  kh trace

  には Linux aarch64が必要です
• ページサイズ: コンテナ用 4 KiB、Asahi クラス機器用 16 KiB
• オプション:

  kh install 7zip

  /

  kh install curl

  を行うために curl/wget + tar が望ましい

インストール手順

cargo install kakehashi
# またはチェックアウトしたリポジトリから: cargo install --path crates/kh-cli

kh bottle ensure
kh install 7zip
kh install curl

ボトルのレイアウト

• デフォルトルート:

  ~/.local/share/kakehashi/bottle/

• 上書き設定:

  KAKEHASHI_DATA_DIR

  または

  KAKEHASHI_ROOT

  を使用します。

ホストとゲストのパスマッピング

…/bottle/

/

…/usr/local/bin/7zz

/usr/local/bin/7zz

…/usr/local/bin/curl

/usr/local/bin/curl

…/usr/lib/libSystem.B.dylib

/usr/lib/libSystem.B.dylib

…/private/etc/ssl/cert.pem

/etc/ssl/cert.pem

…/Volumes/linux/…

/Volumes/linux/… → ホスト FS

パフォーマンスに関する正直な評価

Kakehashi はゲストコードを CPU でネイティブに実行します。課税されるのはシステムコール境界（TLS 切り替え、別スタック、NEON の保存/復元、Rust デスパッチなど）であり、ゲストがどれだけ頻繁にその境界を渡るかによって変動します。命令セットエミュレーターではありません。

測定結果のギャップ

Ubuntu aarch64 ベアメタル（UTM）環境において、複数ファイルを対象とした 7zz アーカイブ（

-t7z -m0=lzma2 -mx=5 -mmt=4

• 圧縮負荷が高くファイル数が少ないサンプルでは、ギャップははるかに小さくなることが多い (~×1.1–1.2)。
• 大規模なマルチファイルのギャップは、「間違った LZMA アルゴリズム」によるものではなく、パスウォークと各システムコール境界のコストが支配的です。
• Hypercall はデフォルトで全てのゲストスレッドに対して有効です。デバッグ用のみ

  KAKEHASHI_HYPERCALL=0

  で無効化してください（残存する

  svc→brk

  /

  SIGTRAP

  など）。

なぜ約×5 の遅さでも CI では有用なのか

CI における本製品の目標は「ネイティブ macOS と同じ速さ」ではなく、稀少かつ高価な macOS リソースの代わりに、安価な Linux aarch64 ランナー上で Darwin CLI ツールを実行することです。

GitHub Actions ホストランナー価格:

macOS の標準的な単価は、実時間差を考慮する前の Linux arm64 分当たりレートの約 ×10–×12 です。Linux arm64 ランナー上の kh 実行が、同じ作業を macOS ランナー上で行った場合と比較して約×5 遅いとしても、請求されるコストは依然として低くなる可能性があります（例：

5 × $0.005 ≈ $0.025

1 × $0.062

• macOS ランナーが優位になるケース: GUI アプリ、codesign/notarization、Xcode UI テスト、または自立型 libSystem 下の純粋な CLI Darwin バイナリではないワークロード。
• ゲート（Gates）としての位置づけ: CI の正しさは

  cargo test

  / Smoke テスト /

  7zz -mmt=4

  で保証され、「ネイティブのウォールクロックを一致させる」ことが目的ではありません。パフォーマンスに関する作業は

  docs/roadmap.md

  で追跡されています。

クイックスタート（Apple Silicon 上の Docker / Colima）

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

# 完全なスモークテスト（ビルド + clippy + テスト + マイクロ実行）
./scripts/docker-smoke.sh

ビルド

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

保守者向け: 自立型 ABI が変更された後に埋め込みを更新してください。

cargo build -p kh-libsystem --release --target aarch64-apple-darwin
./scripts/stage-libsystem.sh   # → crates/kh-runtime/resources/libSystem.B.dylib

libSystem の探索順序

1. --libsystem

   オプション
2. 環境変数

   KAKEHASHI_LIBSYSTEM

3. kh

   の隣にあるパス
4. Crate の resources/ ディレクトリ

5. kh-runtime

   に埋め込まれたバイト列

テストマッピング

cargo test --workspace --exclude kh-libsystem

./scripts/docker-smoke.sh

kh run --expect-code … tests/fixtures/…

tests/fixtures/README.md

kh run --root tests/fixtures/bottle tests/clang-probe/puts_hello

hello

./scripts/docker-7zz.sh …

.tmp/kh-out/

./scripts/docker-curl.sh …

.tmp/kh-out/

.tmp/kh-curl-probe/

./scripts/bench-fair-local.sh

.tmp/kh-bench-fair/

注意:

.tmp/

,

.kh/

, および

target/

は gitignore されています。

ゲストパスとホストパス（Docker 補助スクリプト）

ボトルは Linux FS を

/Volumes/linux/…

/Volumes/linux/src/README.md

<repo>/README.md

/Volumes/linux/out/demo.7z

<repo>/.tmp/kh-out/demo.7z

/Volumes/linux/tmp/…

/tmp/…

docker run --rm

スクリプト参照表

scripts/stage-libsystem.sh

crates/kh-runtime/resources/

scripts/install-linux.sh

scripts/docker-smoke.sh

scripts/docker-7zz.sh

.tmp/kh-out

scripts/docker-curl.sh

docker-7zz

scripts/docker-curl-probe.sh

.tmp/kh-curl-probe

scripts/docker-curl-options.sh

.tmp/kh-curl-options

scripts/docker-git.sh

swscan

.kh/data

scripts/bench-fair-local.sh

.tmp/kh-bench-fair

ライセンス

Apache License 2.0。

LICENSE.txt

NOTICE

免責事項: このプロジェクトは Darling から派生したものではありません。プロプライエタリな Apple SDK や blobs をベンダリングしないでください。