Run a virtual iPhone on an Apple Silicon Mac.
Swift
vphone-cli: Add VPHONE_ROOT env variable to override user data root
Bent72ccbde1de4f
diff --git a/README.md b/README.mdindex 3491957e..8d3f5290 100644--- a/README.md+++ b/README.md@@ -107,16 +107,19 @@ See [`research/0_binary_patch_comparison.md`](./research/0_binary_patch_comparis## Locations-Everything vphone-cli creates lives under `~/.vphone/` — kept outside the repo and the `.app` so the signed bundle stays portable:+Everything vphone-cli creates lives under `~/.vphone/` — kept outside the repo and the `.app` so the signed bundle stays portable. Redirect the whole tree with `$VPHONE_ROOT`:| Path | Contents || ----------------- | -------------------------------------------------------------------------------------------- |+| `~/.vphone/` | The per-user data root — override the entire location with `$VPHONE_ROOT`. || `~/.vphone/VMs/` | VM bundles — one directory per VM. This is the library; override with `$VPHONE_LIBRARY_ROOT`. || `~/.vphone/ipsws/`| Downloaded iPhone + cloudOS IPSWs, cached and reused across VMs. || `~/.vphone/tools/`| Cached APFS seal-volume artifacts (`apfs_sealvolume_<version>`) fetched during `fw prepare`. || `~/.vphone/debs/` | Cached `.deb` packages the `jb`/`exp` CFW install lays into the guest (Sileo, apt, …). || `~/.vphone/venv/` | Auto-provisioned Python environment (see [Python runtime](#python-runtime); override with `$VPHONE_VENV_DIR`). |+Precedence: the per-item overrides (`$VPHONE_LIBRARY_ROOT`, `$VPHONE_VENV_DIR`) win over `$VPHONE_ROOT`, which wins over the `~/.vphone` default. The `ipsws/`, `tools/`, and `debs/` caches always sit directly under whichever root is active.+## SIP/AMFI Relaxation**Option A — fully disable SIP, then disable AMFI via boot-arg (most permissive).**diff --git a/docs/README_ja.md b/docs/README_ja.mdindex 1320c8e1..a870fc9f 100644--- a/docs/README_ja.md+++ b/docs/README_ja.md@@ -107,16 +107,19 @@ vphone-cli vm launch myphone # 6. 初回起動## 場所-vphone-cli が生成するものはすべて `~/.vphone/` 以下に置かれます — 署名済みバンドルがポータブルであり続けるよう、リポジトリと `.app` の外に保管されます:+vphone-cli が生成するものはすべて `~/.vphone/` 以下に置かれます — 署名済みバンドルがポータブルであり続けるよう、リポジトリと `.app` の外に保管されます。`$VPHONE_ROOT` でツリー全体をリダイレクトできます:| パス | 内容 || ----------------- | ------------------------------------------------------------------------------------------ |+| `~/.vphone/` | ユーザー別データルート — `$VPHONE_ROOT` で場所全体を上書きします。 || `~/.vphone/VMs/` | VM バンドル — VM ごとに 1 ディレクトリ。これがライブラリです。`$VPHONE_LIBRARY_ROOT` で上書きできます。 || `~/.vphone/ipsws/`| ダウンロードされた iPhone + cloudOS の IPSW。キャッシュされ、複数の VM で再利用されます。 || `~/.vphone/tools/`| `fw prepare` 中に取得された APFS seal-volume アーティファクト(`apfs_sealvolume_<version>`)のキャッシュ。 || `~/.vphone/debs/` | `jb`/`exp` の CFW インストールがゲストに配置する `.deb` パッケージのキャッシュ(Sileo、apt など)。 || `~/.vphone/venv/` | 自動的にプロビジョニングされる Python 環境([Python ランタイム](#python-ランタイム) を参照。`$VPHONE_VENV_DIR` で上書き可能)。 |+優先順位: 項目ごとの上書き(`$VPHONE_LIBRARY_ROOT`、`$VPHONE_VENV_DIR`)が `$VPHONE_ROOT` より優先され、`$VPHONE_ROOT` は `~/.vphone` のデフォルトより優先されます。`ipsws/`、`tools/`、`debs/` キャッシュは、常に現在有効なルートの直下に置かれます。+## SIP/AMFI の緩和**オプション A — SIP を完全に無効化し、boot-arg で AMFI を無効化する(最も緩い)。**diff --git a/docs/README_ko.md b/docs/README_ko.mdindex 06922a2b..569742b0 100644--- a/docs/README_ko.md+++ b/docs/README_ko.md@@ -107,16 +107,19 @@ vphone-cli vm launch myphone # 6. 첫 부팅## 위치-vphone-cli가 생성하는 모든 것은 `~/.vphone/` 아래에 있습니다 — 서명된 번들이 이식 가능하도록 저장소와 `.app` 외부에 보관됩니다:+vphone-cli가 생성하는 모든 것은 `~/.vphone/` 아래에 있습니다 — 서명된 번들이 이식 가능하도록 저장소와 `.app` 외부에 보관됩니다. `$VPHONE_ROOT`로 전체 트리를 리디렉션할 수 있습니다:| 경로 | 내용 || ----------------- | ------------------------------------------------------------------------------------------ |+| `~/.vphone/` | 사용자별 데이터 루트 — `$VPHONE_ROOT`로 전체 위치를 재정의합니다. || `~/.vphone/VMs/` | VM 번들 — VM마다 하나의 디렉터리. 라이브러리이며, `$VPHONE_LIBRARY_ROOT`로 재정의할 수 있습니다. || `~/.vphone/ipsws/`| 다운로드된 iPhone + cloudOS IPSW, 캐시되어 여러 VM에서 재사용됩니다. || `~/.vphone/tools/`| `fw prepare` 중에 가져온 APFS seal-volume 아티팩트(`apfs_sealvolume_<version>`) 캐시. || `~/.vphone/debs/` | `jb`/`exp` CFW 설치가 게스트에 넣는 `.deb` 패키지 캐시 (Sileo, apt 등). || `~/.vphone/venv/` | 자동으로 프로비저닝되는 Python 환경 ([Python 런타임](#python-런타임) 참조; `$VPHONE_VENV_DIR`로 재정의). |+우선순위: 항목별 재정의(`$VPHONE_LIBRARY_ROOT`, `$VPHONE_VENV_DIR`)가 `$VPHONE_ROOT`보다 우선하고, `$VPHONE_ROOT`는 `~/.vphone` 기본값보다 우선합니다. `ipsws/`, `tools/`, `debs/` 캐시는 항상 현재 활성 루트 바로 아래에 위치합니다.+## SIP/AMFI 완화**방법 A — SIP를 완전히 비활성화한 후, boot-arg로 AMFI를 비활성화 (가장 관대).**diff --git a/docs/README_zh.md b/docs/README_zh.mdindex 2b97ade1..29e73a60 100644--- a/docs/README_zh.md+++ b/docs/README_zh.md@@ -107,16 +107,19 @@ vphone-cli vm launch myphone # 6. 首次启动## 位置-vphone-cli 创建的所有内容都位于 `~/.vphone/` 下——保存在仓库和 `.app` 之外,以便签名后的包保持可移植:+vphone-cli 创建的所有内容都位于 `~/.vphone/` 下——保存在仓库和 `.app` 之外,以便签名后的包保持可移植。可用 `$VPHONE_ROOT` 重定向整个目录树:| 路径 | 内容 || ----------------- | -------------------------------------------------------------------------------- |+| `~/.vphone/` | 每用户数据根目录——用 `$VPHONE_ROOT` 覆盖整个位置。 || `~/.vphone/VMs/` | 虚拟机包——每个虚拟机一个目录。这是库;可用 `$VPHONE_LIBRARY_ROOT` 覆盖。 || `~/.vphone/ipsws/`| 已下载的 iPhone + cloudOS IPSW,缓存后在多个虚拟机间复用。 || `~/.vphone/tools/`| `fw prepare` 期间获取的 APFS seal-volume 制品(`apfs_sealvolume_<version>`)缓存。 || `~/.vphone/debs/` | `jb`/`exp` CFW 安装写入客户机的 `.deb` 包缓存(Sileo、apt 等)。 || `~/.vphone/venv/` | 自动配置的 Python 环境(见 [Python 运行时](#python-运行时);可用 `$VPHONE_VENV_DIR` 覆盖)。 |+优先级:单项覆盖(`$VPHONE_LIBRARY_ROOT`、`$VPHONE_VENV_DIR`)优先于 `$VPHONE_ROOT`,`$VPHONE_ROOT` 优先于 `~/.vphone` 默认值。`ipsws/`、`tools/` 和 `debs/` 缓存始终位于当前生效的根目录之下。+## 放宽 SIP/AMFI**方案 A——完全禁用 SIP,然后通过 boot-arg 禁用 AMFI(最宽松)。**diff --git a/sources/VPhoneCore/VPhoneLibrary.swift b/sources/VPhoneCore/VPhoneLibrary.swiftindex 2dd2a070..6e864a91 100644--- a/sources/VPhoneCore/VPhoneLibrary.swift+++ b/sources/VPhoneCore/VPhoneLibrary.swift@@ -41,8 +41,8 @@ public struct VPhoneLibrary: Sendable {// `~/.vphone/VMs` — deliberately space-free: bundle paths flow into the// shell/make firmware pipeline, and "Application Support" (a space) breaks// any unquoted expansion there. Keep the default path shell-safe.- return FileManager.default.homeDirectoryForCurrentUser- .appendingPathComponent(".vphone/VMs", isDirectory: true)+ return VPhoneResources.userDataRoot()+ .appendingPathComponent("VMs", isDirectory: true)}public func url(forName name: String) -> URL {diff --git a/sources/VPhoneCore/VPhoneResources.swift b/sources/VPhoneCore/VPhoneResources.swiftindex 5db975a0..3b80a1aa 100644--- a/sources/VPhoneCore/VPhoneResources.swift+++ b/sources/VPhoneCore/VPhoneResources.swift@@ -70,9 +70,17 @@ public struct VPhoneResources: Sendable {// MARK: - Cache dirs- public var userCacheDir: URL {- FileManager.default.homeDirectoryForCurrentUser.appendingPathComponent(".vphone")+ /// The per-user data root: `$VPHONE_ROOT` when set, else `~/.vphone`. Both+ /// `VPhoneResources` (ipsws/tools/debs/venv) and `VPhoneLibrary` (VMs)+ /// derive from this so one variable redirects everything vphone-cli creates.+ public static func userDataRoot() -> URL {+ if let root = ProcessInfo.processInfo.environment["VPHONE_ROOT"], !root.isEmpty {+ return URL(fileURLWithPath: root, isDirectory: true)+ }+ return FileManager.default.homeDirectoryForCurrentUser.appendingPathComponent(".vphone")}++ public var userCacheDir: URL { Self.userDataRoot() }public var ipswCacheDir: URL { userCacheDir.appendingPathComponent("ipsws") }public var sealVolumeCacheDir: URL { userCacheDir.appendingPathComponent("tools") }public var debsCacheDir: URL { userCacheDir.appendingPathComponent("debs") }diff --git a/tests/VPhoneCoreTests/LibraryTests.swift b/tests/VPhoneCoreTests/LibraryTests.swiftindex 4a2cab1f..decd5a2b 100644--- a/tests/VPhoneCoreTests/LibraryTests.swift+++ b/tests/VPhoneCoreTests/LibraryTests.swift@@ -50,10 +50,18 @@ struct LibraryTests {#expect(VPhoneLibrary.defaultRoot().path == "/tmp/vphone-test-root")}+ @Test func defaultRootHonorsVPHONERoot() {+ unsetenv("VPHONE_LIBRARY_ROOT")+ setenv("VPHONE_ROOT", "/tmp/vphone-test-root", 1)+ defer { unsetenv("VPHONE_ROOT") }+ #expect(VPhoneLibrary.defaultRoot().path == "/tmp/vphone-test-root/VMs")+ }+@Test func defaultRootIsShellSafe() {// The default root feeds the shell/make firmware pipeline; a space in it// (e.g. "Application Support") breaks unquoted expansion. Must stay space-free.unsetenv("VPHONE_LIBRARY_ROOT")+ unsetenv("VPHONE_ROOT")#expect(!VPhoneLibrary.defaultRoot().path.contains(" "))}diff --git a/tests/VPhoneCoreTests/ResourcesTests.swift b/tests/VPhoneCoreTests/ResourcesTests.swiftindex 3872c44b..4a721501 100644--- a/tests/VPhoneCoreTests/ResourcesTests.swift+++ b/tests/VPhoneCoreTests/ResourcesTests.swift@@ -27,6 +27,8 @@ struct ResourcesTests {}@Test func cacheDirsAreHomeRelativeAndToolsBinIsBaseRelative() {+ // The VPHONE_ROOT override would relocate the cache; only assert the default.+ if ProcessInfo.processInfo.environment["VPHONE_ROOT"] != nil { return }let r = VPhoneResources(base: URL(fileURLWithPath: "/Applications/vphone-cli.app/Contents/Resources"))#expect(r.userCacheDir.path.hasSuffix("/.vphone"))#expect(r.toolsBinDir.path == r.base.appendingPathComponent(".tools/bin").path)@@ -43,12 +45,36 @@ struct ResourcesTests {}@Test func managedVenvDefaultsUnderDotVphone() {- // The override env var would change this; only assert the default.+ // The override env vars would change this; only assert the default.if ProcessInfo.processInfo.environment["VPHONE_VENV_DIR"] != nil { return }+ if ProcessInfo.processInfo.environment["VPHONE_ROOT"] != nil { return }let r = VPhoneResources(base: URL(fileURLWithPath: "/x"))#expect(r.managedVenvDir.path.hasSuffix("/.vphone/venv"))}+ @Test func userCacheDirHonorsVPHONERoot() {+ unsetenv("VPHONE_VENV_DIR")+ setenv("VPHONE_ROOT", "/tmp/vphone-test-root", 1)+ defer { unsetenv("VPHONE_ROOT") }+ let r = VPhoneResources(base: URL(fileURLWithPath: "/x"))+ #expect(r.userCacheDir.path == "/tmp/vphone-test-root")+ #expect(r.ipswCacheDir.path == "/tmp/vphone-test-root/ipsws")+ #expect(r.sealVolumeCacheDir.path == "/tmp/vphone-test-root/tools")+ #expect(r.debsCacheDir.path == "/tmp/vphone-test-root/debs")+ #expect(r.managedVenvDir.path == "/tmp/vphone-test-root/venv")+ }++ @Test func managedVenvOverrideBeatsVPHONERoot() {+ setenv("VPHONE_ROOT", "/tmp/vphone-test-root", 1)+ setenv("VPHONE_VENV_DIR", "/tmp/custom-venv", 1)+ defer {+ unsetenv("VPHONE_ROOT")+ unsetenv("VPHONE_VENV_DIR")+ }+ let r = VPhoneResources(base: URL(fileURLWithPath: "/x"))+ #expect(r.managedVenvDir.path == "/tmp/custom-venv")+ }+@Test func pythonUsabilityProbeRejectsMissingAcceptsDevVenv() {let cwd = URL(fileURLWithPath: FileManager.default.currentDirectoryPath)let r = VPhoneResources(base: cwd)