Skip to content

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.md
index 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.md
index 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.md
index 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.md
index 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.swift
index 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.swift
index 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.swift
index 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.swift
index 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)