Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Run bundle validation as part of VPhone build

Lakre5460ff087d3
diff --git a/AGENTS.md b/AGENTS.md
index 53b342db..8f82fec9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -5,7 +5,7 @@ Virtual iPhone boot tool using Apple's Virtualization.framework with PCC researc
## Quick Reference
- **Build:** `xcodebuild -workspace VPhone.xcworkspace -scheme VPhone -configuration Debug -destination 'platform=macOS,arch=arm64' -derivedDataPath .build/XcodeBundle build`
-- **Test:** Run the Xcode test schemes in their owning projects; then `zsh Scripts/check_aux.sh`
+- **Test:** Run the Xcode test schemes in their owning projects. The `VPhone` build validates the finished bundle.
- **Boot (GUI):** `vphone-cli vm launch <name>`
- **Boot (DFU):** `vphone-cli vm launch <name> --dfu`
- **AMFI refuses `vphone-vm`?** Use the bundled `VPhoneEscalator` allowlist tool as shown in `Documents/Guides/host-setup.md`. Repeat after the VM cdhash changes.
@@ -13,7 +13,7 @@ Virtual iPhone boot tool using Apple's Virtualization.framework with PCC researc
- **Platform:** macOS 15+ (Sequoia). `vphone-vm` needs amfid to accept its private entitlements: either SIP off with `amfi_get_out_of_my_way=1`, or SIP on (`--without debug`) plus an allowlist bypass the user runs. Both are in `Documents/Guides/host-setup.md`; neither is installed by this project.
- **Language:** Swift 6.0 in handwritten Xcode projects, private APIs via [Dynamic](https://github.com/mhdhejazi/Dynamic).
- **Dependencies:** Host and guest SwiftPM packages resolve dependencies by URL and version; `Package.resolved` pins the full graphs. There are no git submodules. **No Python anywhere, and no Homebrew package at runtime** — see Tiers below.
-- **Tiers.** The build machine may use Xcode and build tools. The shipped `VPhone.bundle` must use only system libraries and its own contents at runtime. Guest components run inside the VM. `Scripts/check_aux.sh` checks bundle admission.
+- **Tiers.** The build machine may use Xcode and build tools. The shipped `VPhone.bundle` must use only system libraries and its own contents at runtime. Guest components run inside the VM. `Build/ValidateBundle.sh` checks bundle admission as part of the `VPhone` build.
## Workflow Rules
@@ -101,10 +101,10 @@ There is none, and adding any is a regression.
restore backend was the last holdout and is now `VPhoneExecutable/VPhoneCommand/VPhoneRestore` over
two vendored C targets — see `Research/Restore/native_restore_architecture.md`.
- A patch, a probe, a format reader or a device protocol belongs in Swift,
- where it is built, signed, gated by `Scripts/check_aux.sh` and tested with
+ where it is built, signed, gated by `Build/ValidateBundle.sh` and tested with
everything else. Adding an interpreter back brings with it a provisioning
step, a silent system-`python3` fallback, and a dependency closure
- `Scripts/check_aux.sh` cannot see.
+ `Build/ValidateBundle.sh` cannot see.
- There is no counter-example left. `amfidont` used to be cited as one — a
third-party tool the user installed into their own Python — and it is gone
too: the AMFI allowlist tool is `VPhoneExecutable/VPhoneEscalator`, one C
diff --git a/Documents/Guides/bundle-integration.md b/Documents/Guides/bundle-integration.md
index f1b86bf1..1a899750 100644
--- a/Documents/Guides/bundle-integration.md
+++ b/Documents/Guides/bundle-integration.md
@@ -30,11 +30,10 @@ launching it. The VM library and caches stay outside `VPhone.bundle`, under
workstation process can access them, including after a root-run create.
Guest filesystem permissions inside `Disk.img` retain their own semantics.
-Build and inspect:
+Build and validate:
```sh
xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
-configuration Debug -destination 'platform=macOS,arch=arm64' \
-derivedDataPath .build/XcodeBundle build
-zsh Scripts/check_aux.sh .build/XcodeBundle/Build/Products/Debug/VPhone.bundle
```
diff --git a/Documents/README.md b/Documents/README.md
index 630a7167..3a33daae 100644
--- a/Documents/README.md
+++ b/Documents/README.md
@@ -21,5 +21,5 @@ These pages give a translated overview and quick start. The guides above hold th
- [Research index](../Research/README.md) groups the patch and implementation records by subject.
- [Patch inventory](../Research/0_binary_patch_comparison.md) is the canonical per-component comparison.
-- `xcodebuild -workspace VPhone.xcworkspace -scheme VPhone build` produces `VPhone.bundle`; run each project's test scheme and `zsh Scripts/check_aux.sh` for bundle checks.
+- `xcodebuild -workspace VPhone.xcworkspace -scheme VPhone build` produces and validates `VPhone.bundle`; run each project's test scheme separately.
- `vphone-cli <group> --help` shows the CLI command surface.
diff --git a/Documents/README_ja.md b/Documents/README_ja.md
index ac01eb6e..ffcd99a6 100644
--- a/Documents/README_ja.md
+++ b/Documents/README_ja.md
@@ -42,7 +42,8 @@ cd vphone-cli
xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
-configuration Debug -destination 'platform=macOS,arch=arm64' \
-derivedDataPath .build/XcodeBundle build
-zsh Scripts/check_aux.sh
```
+ビルド中に生成された `VPhone.bundle` が自動で検証されます。
+
AMFI の許可リストを使う場合、ビルドのたびに[ホストの設定手順](Guides/host-setup.md)に従って署名済み VM バイナリを再登録してください。[ドキュメント一覧](README.md)から現在の手順と研究資料に進めます。詳しいガイドは現在英語です。
diff --git a/Documents/README_ko.md b/Documents/README_ko.md
index c72f710b..68f9bcc7 100644
--- a/Documents/README_ko.md
+++ b/Documents/README_ko.md
@@ -42,7 +42,8 @@ cd vphone-cli
xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
-configuration Debug -destination 'platform=macOS,arch=arm64' \
-derivedDataPath .build/XcodeBundle build
-zsh Scripts/check_aux.sh
```
+빌드 과정에서 생성된 `VPhone.bundle`을 자동으로 검증합니다.
+
AMFI 허용 목록을 사용하는 호스트에서는 빌드할 때마다 [호스트 설정 가이드](Guides/host-setup.md)에 따라 서명된 VM 바이너리를 다시 허용하세요. 현재 가이드와 연구 자료는 [문서 목차](README.md)에 모았습니다. 상세 가이드는 현재 영어로 제공됩니다.
diff --git a/Documents/README_zh.md b/Documents/README_zh.md
index af151693..209613a7 100644
--- a/Documents/README_zh.md
+++ b/Documents/README_zh.md
@@ -42,9 +42,10 @@ cd vphone-cli
xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
-configuration Debug -destination 'platform=macOS,arch=arm64' \
-derivedDataPath .build/XcodeBundle build
-zsh Scripts/check_aux.sh
```
+构建会自动验收生成的 `VPhone.bundle`。
+
采用 AMFI 白名单的宿主机,每次重编译后都要按[宿主机准备](Guides/host-setup.md)中的步骤重新允许签名后的 VM 程序。
## 常用命令
diff --git a/README.md b/README.md
index 18b1ea09..91a31fc8 100644
--- a/README.md
+++ b/README.md
@@ -59,10 +59,10 @@ xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
The `VPhone` scheme builds the host tools, guest daemon, and guest components;
every shipped binary is under `Contents/MacOS`. They use ad hoc code signatures,
-with private virtualization entitlements only on `vphone-vm`. Run the test
-schemes in their respective projects and `zsh Scripts/check_aux.sh` to inspect
-the bundle. An AMFI allowlist must be updated whenever the VM binary's cdhash
-changes. See [host setup](Documents/Guides/host-setup.md) and the
+with private virtualization entitlements only on `vphone-vm`. The build validates
+the finished bundle; run the test schemes in their respective projects. An AMFI
+allowlist must be updated whenever the VM binary's cdhash changes. See
+[host setup](Documents/Guides/host-setup.md) and the
[bundle integration contract](Documents/Guides/bundle-integration.md).
## Everyday commands
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Binary/InPlaceRewrite.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Binary/InPlaceRewrite.swift
index fc820da4..16284b0e 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Binary/InPlaceRewrite.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Binary/InPlaceRewrite.swift
@@ -19,7 +19,7 @@
// So a buffer that will be mutated and written back over its own file is READ.
// Nothing that comes through here is large: these are single Mach-Os out of a
// guest filesystem — launchd is 639 KB, the biggest is mobileactivationd at
-// 4.6 MB — so the copy costs nothing worth having, and `Scripts/check_aux.sh` knows
+// 4.6 MB — so the copy costs nothing worth having, and `Build/ValidateBundle.sh` knows
// this spelling is the deliberate one.
import Foundation
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareAEACommand.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareAEACommand.swift
index 0821f0c2..966d9ce0 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareAEACommand.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareAEACommand.swift
@@ -4,7 +4,7 @@
// fw_prepare.sh, and they are the last of them. `ipsw` is a fine program —
// statically linked Go, nothing but system libraries — but it is a program the
// user has to install with Homebrew before a .app that is supposed to be
-// self-contained can finish a job, which is the thing `Scripts/check_aux.sh` exists
+// self-contained can finish a job, which is the thing `Build/ValidateBundle.sh` exists
// to stop.
//
// ipsw fw aea --key <f> -> vphone-cli fw aea-key <f>
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneRestore/MobileRestoreCore/Bridge/zip.h b/VPhoneExecutable/VPhoneCommand/VPhoneRestore/MobileRestoreCore/Bridge/zip.h
index 7c812d5a..ad58b539 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneRestore/MobileRestoreCore/Bridge/zip.h
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneRestore/MobileRestoreCore/Bridge/zip.h
@@ -14,7 +14,7 @@
* libimobiledevice, its glue, libusbmuxd and libtatsu come from the
* AppleMobileDeviceLibrary xcframeworks, and zlib and libcurl are in
* /usr/lib. Linking Homebrew's libzip would put an absolute /opt/homebrew
- * path in the dependency closure, which is exactly what `Scripts/check_aux.sh`
+ * path in the dependency closure, which is exactly what `Build/ValidateBundle.sh`
* gate 1 exists to reject.
*
* WHAT IS LOST
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneSignTests/VPhoneSignFixtures.swift b/VPhoneExecutable/VPhoneCommand/VPhoneSignTests/VPhoneSignFixtures.swift
index 6fe05567..c6a02fb6 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneSignTests/VPhoneSignFixtures.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneSignTests/VPhoneSignFixtures.swift
@@ -78,7 +78,7 @@
//
// Adding a live `ldid` call back — a `which`, a hardcoded Homebrew path, an
// environment variable — is the same regression the "Python" section of
-// AGENTS.md forbids for an interpreter: a dependency `Scripts/check_aux.sh` cannot
+// AGENTS.md forbids for an interpreter: a dependency `Build/ValidateBundle.sh` cannot
// see, and a silent skip when it is missing.
import CryptoKit
diff --git a/VPhoneExecutable/VPhoneVirtualization/Build/StageBundle.sh b/VPhoneExecutable/VPhoneVirtualization/Build/StageBundle.sh
index 94663486..9dbae2a8 100755
--- a/VPhoneExecutable/VPhoneVirtualization/Build/StageBundle.sh
+++ b/VPhoneExecutable/VPhoneVirtualization/Build/StageBundle.sh
@@ -82,3 +82,5 @@ compatibility_library="$(/usr/bin/xcrun swift-stdlib-tool --print \
/usr/bin/codesign --force --sign - "$macos/libswiftCompatibilitySpan.vphone.dylib"
/usr/bin/codesign --force --sign - --entitlements "$root/VPhoneExecutable/VPhoneVirtualization/Resources/VPhoneVirtualization.entitlements" "$macos/vphone-vm"
/usr/bin/codesign --force --sign - "$bundle"
+
+"${0:a:h}/ValidateBundle.sh" "$bundle"
diff --git a/Scripts/check_aux.sh b/VPhoneExecutable/VPhoneVirtualization/Build/ValidateBundle.sh
similarity index 99%
rename from Scripts/check_aux.sh
rename to VPhoneExecutable/VPhoneVirtualization/Build/ValidateBundle.sh
index 995d6c0f..7c475a44 100755
--- a/Scripts/check_aux.sh
+++ b/VPhoneExecutable/VPhoneVirtualization/Build/ValidateBundle.sh
@@ -2,7 +2,7 @@
# vphone-tier: build
set -euo pipefail
-root="${0:a:h:h}"
+root="$(cd "${0:a:h}/../../.." && pwd)"
bundle="${1:-$root/.build/XcodeBundle/Build/Products/Debug/VPhone.bundle}"
macos="$bundle/Contents/MacOS"
resources="$bundle/Contents/Resources"
diff --git a/VPhoneKit/VPhoneCoreKit/Firmware/VPhoneResources.swift b/VPhoneKit/VPhoneCoreKit/Firmware/VPhoneResources.swift
index 84d1b95a..d8004a94 100644
--- a/VPhoneKit/VPhoneCoreKit/Firmware/VPhoneResources.swift
+++ b/VPhoneKit/VPhoneCoreKit/Firmware/VPhoneResources.swift
@@ -138,7 +138,7 @@ public struct VPhoneResources: Sendable {
// was the dangerous one: a `PATH` fallback makes a missing environment look
// like a working one, right up until a restore fails on a stranger's
// machine. Nothing in this package may resolve an interpreter again — see
- // the "Python" section in AGENTS.md, and `Scripts/check_aux.sh`, which now
+ // the "Python" section in AGENTS.md, and `Build/ValidateBundle.sh`, which now
// fails outright on a python3 lookup instead of registering it.
// With the interpreter went the last `PATH` lookup in this package. Every