Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

docs: explain v2 VM format and release install

Lakr9c0ad62c302b
diff --git a/Documents/Guides/compatibility.md b/Documents/Guides/compatibility.md
index 64ff65f2..8684d7df 100644
--- a/Documents/Guides/compatibility.md
+++ b/Documents/Guides/compatibility.md
@@ -2,6 +2,11 @@
[Documentation](../README.md) · [Create a VM](create-and-run.md) · [Patch inventory](../../Research/0_binary_patch_comparison.md)
+**v2.0.0 VM format:** This release starts only newly created VMs whose
+`config.plist` has `schemaVersion=2`. Recreate VMs made by earlier releases
+with `vm create`; there is no in-place upgrade. The firmware results below
+describe tested pairings, not compatibility with older VM bundles.
+
## Tested Environments
These are the two iPhone17,3 combinations exercised with the native JB pipeline in [PR #486](https://github.com/Lakr233/vphone-cli/pull/486). Both reached the lock screen and answered a vphoned ping. A fresh 26.6.2 `vm create` also completed all stages and exited successfully after its first-boot ping.
diff --git a/Documents/README_ja.md b/Documents/README_ja.md
index d0aa77c9..1383f3d2 100644
--- a/Documents/README_ja.md
+++ b/Documents/README_ja.md
@@ -12,6 +12,8 @@ Apple の Virtualization.framework と PCC 研究用 VM 基盤を使って、仮
Apple Silicon、macOS 15 以降、および PV=3 研究用 VM と `vphone-vm` の権限を許可する[ホスト設定](Guides/host-setup.md)が必要です。
+**v2.0.0 の VM 互換性:**このリリースで起動できるのは、新しく作成された `schemaVersion=2` の VM だけです。旧バージョンで作成した VM は `vm create` で作り直してください。既存 VM の直接アップグレードには対応しません。
+
```sh
vphone-cli vm create myphone \
--iphone-source /path/to/iPhone17,3_Restore.ipsw \
@@ -26,7 +28,14 @@ cloudOS 26.4(`23E5207q`)との組み合わせで、iPhone17,3 の iOS 26.6.2
## インストールとビルド
-配布 `.app` の実行に Homebrew、Python、Xcode や別の実行環境は不要です。ソースからのビルドには、vphoned をコンパイルするための iPhoneOS SDK を含む Xcode が必要です。
+配布 `.app` の実行に Homebrew、Python、Xcode や別の実行環境は不要です。[GitHub Releases](https://github.com/Lakr233/vphone-cli/releases) から `vphone-cli-2.0.0.zip` をダウンロードして展開し、アプリ内の CLI を直接実行します。
+
+```sh
+ditto -x -k vphone-cli-2.0.0.zip .
+./vphone-cli.app/Contents/MacOS/vphone-cli host preflight
+```
+
+上の例では、`vphone-cli` をこのアプリ内のパスに置き換えられます。ソースからのビルドには、vphoned をコンパイルするための iPhoneOS SDK を含む Xcode が必要です。
```sh
git clone https://github.com/Lakr233/vphone-cli.git
diff --git a/Documents/README_ko.md b/Documents/README_ko.md
index a89cb140..1459a89d 100644
--- a/Documents/README_ko.md
+++ b/Documents/README_ko.md
@@ -12,6 +12,8 @@ Apple Virtualization.framework와 PCC 연구용 VM 기반으로 가상 iPhone을
Apple Silicon Mac, macOS 15 이상, 그리고 PV=3 연구용 VM과 `vphone-vm` 권한을 허용하는 [호스트 설정](Guides/host-setup.md)이 필요합니다.
+**v2.0.0 VM 호환성:** 이 릴리스는 새로 만든 `schemaVersion=2` VM만 시작합니다. 이전 버전에서 만든 VM은 `vm create`로 다시 만들어야 하며, 기존 VM의 제자리 업그레이드는 지원하지 않습니다.
+
```sh
vphone-cli vm create myphone \
--iphone-source /path/to/iPhone17,3_Restore.ipsw \
@@ -26,7 +28,14 @@ cloudOS 26.4(`23E5207q`)와 함께 iPhone17,3 iOS 26.6.2(`23G90`), 27.0(`24A435`
## 설치와 빌드
-배포된 `.app` 실행에는 Homebrew, Python, Xcode나 별도의 런타임 환경이 필요하지 않습니다. 소스 빌드에는 vphoned용 iPhoneOS SDK가 포함된 Xcode가 필요합니다.
+배포된 `.app` 실행에는 Homebrew, Python, Xcode나 별도의 런타임 환경이 필요하지 않습니다. [GitHub Releases](https://github.com/Lakr233/vphone-cli/releases)에서 `vphone-cli-2.0.0.zip`을 다운로드하고 압축을 푼 뒤 앱 안의 CLI를 직접 실행하세요.
+
+```sh
+ditto -x -k vphone-cli-2.0.0.zip .
+./vphone-cli.app/Contents/MacOS/vphone-cli host preflight
+```
+
+위 예시의 `vphone-cli` 대신 이 앱 내부 경로를 사용할 수 있습니다. 소스 빌드에는 vphoned용 iPhoneOS SDK가 포함된 Xcode가 필요합니다.
```sh
git clone https://github.com/Lakr233/vphone-cli.git
diff --git a/Documents/README_zh.md b/Documents/README_zh.md
index b107f7ae..1098c166 100644
--- a/Documents/README_zh.md
+++ b/Documents/README_zh.md
@@ -12,6 +12,8 @@
需要 Apple Silicon Mac、macOS 15 或更新版本,以及允许 PV=3 研究虚拟机和 `vphone-vm` 私有授权的宿主机设置。先看[宿主机准备](Guides/host-setup.md)。
+**v2.0.0 虚拟机兼容性:**此版本只能启动新建的、`schemaVersion=2` 的虚拟机。旧版本创建的虚拟机必须重新执行 `vm create` 创建;不支持原地升级。
+
```sh
vphone-cli vm create myphone \
--iphone-source /path/to/iPhone17,3_Restore.ipsw \
@@ -26,7 +28,14 @@ vphone-cli vm launch myphone
## 安装与构建
-成品 `.app` 运行时不需要 Homebrew、Python 或 Xcode,也不需要额外安装运行环境。从源码构建则需要 Xcode 的 iPhoneOS SDK,以编译 vphoned:
+成品 `.app` 运行时不需要 Homebrew、Python 或 Xcode,也不需要额外安装运行环境。从 [GitHub Releases](https://github.com/Lakr233/vphone-cli/releases) 下载 `vphone-cli-2.0.0.zip`,解压后直接调用应用内的 CLI:
+
+```sh
+ditto -x -k vphone-cli-2.0.0.zip .
+./vphone-cli.app/Contents/MacOS/vphone-cli host preflight
+```
+
+上文示例中的 `vphone-cli` 可替换为上述应用内路径。从源码构建则需要 Xcode 的 iPhoneOS SDK,以编译 vphoned:
```sh
git clone https://github.com/Lakr233/vphone-cli.git
diff --git a/README.md b/README.md
index bc5be801..96f88b1f 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,10 @@ The supported firmware flow is **JB only**. It applies the required system patch
Use an Apple Silicon Mac running macOS 15 or newer. The host must permit PV=3 research guests and the private entitlements on `vphone-vm`; see [host setup](Documents/Guides/host-setup.md) before the first boot. A Mac running inside another VM cannot boot this guest.
+**v2.0.0 VM compatibility:** This release starts only newly created VMs with
+`schemaVersion=2`. VMs created by earlier releases must be recreated with
+`vm create`; there is no in-place upgrade.
+
```sh
vphone-cli vm create myphone \
--iphone-source /path/to/iPhone17,3_Restore.ipsw \
@@ -38,6 +42,15 @@ For local validation, iPhone17,3 **26.6.2 (23G90)** and **27.0 (24A435)** both r
A distributed `.app` uses macOS system tools and its own bundled binaries; it does not need Homebrew, Python, or Xcode to run. Building from source does not install a separate runtime environment.
+Download `vphone-cli-2.0.0.zip` from [GitHub Releases](https://github.com/Lakr233/vphone-cli/releases), extract it, and run the CLI inside the app:
+
+```sh
+ditto -x -k vphone-cli-2.0.0.zip .
+./vphone-cli.app/Contents/MacOS/vphone-cli host preflight
+```
+
+Use that app path in place of `vphone-cli` in the examples above if the CLI is not on your `PATH`.
+
Building from source needs Xcode, including its iPhoneOS SDK for vphoned:
```sh