Run a virtual iPhone on an Apple Silicon Mac.
Swift
refactor: Move all manual clones to be submodules (#218)
zqxwce30fcc05ca57a
diff --git a/.gitmodules b/.gitmodulesindex e5d69d52..72296012 100644--- a/.gitmodules+++ b/.gitmodules@@ -16,3 +16,33 @@[submodule "vendor/swift-argument-parser"]path = vendor/swift-argument-parserurl = https://github.com/apple/swift-argument-parser.git+[submodule "scripts/repos/trustcache"]+ path = scripts/repos/trustcache+ url = https://github.com/CRKatri/trustcache.git+[submodule "scripts/repos/insert_dylib"]+ path = scripts/repos/insert_dylib+ url = https://github.com/tyilo/insert_dylib.git+[submodule "scripts/repos/libplist"]+ path = scripts/repos/libplist+ url = https://github.com/libimobiledevice/libplist.git+[submodule "scripts/repos/libimobiledevice-glue"]+ path = scripts/repos/libimobiledevice-glue+ url = https://github.com/libimobiledevice/libimobiledevice-glue.git+[submodule "scripts/repos/libusbmuxd"]+ path = scripts/repos/libusbmuxd+ url = https://github.com/libimobiledevice/libusbmuxd.git+[submodule "scripts/repos/libtatsu"]+ path = scripts/repos/libtatsu+ url = https://github.com/libimobiledevice/libtatsu.git+[submodule "scripts/repos/libimobiledevice"]+ path = scripts/repos/libimobiledevice+ url = https://github.com/libimobiledevice/libimobiledevice.git+[submodule "scripts/repos/libirecovery"]+ path = scripts/repos/libirecovery+ url = https://github.com/libimobiledevice/libirecovery.git+[submodule "scripts/repos/idevicerestore"]+ path = scripts/repos/idevicerestore+ url = https://github.com/libimobiledevice/idevicerestore.git+[submodule "scripts/repos/libzip"]+ path = scripts/repos/libzip+ url = https://github.com/nih-at/libzip.gitdiff --git a/AGENTS.md b/AGENTS.mdindex 4ae30881..0ceef984 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -91,6 +91,7 @@ scripts/├── patchers/ # Python CFW patcher modules│ └── cfw.py # CFW binary patcher entrypoint├── resources/ # Resource archives (git submodule)+├── repos/ # Toolchain source repos (git submodules: trustcache, insert_dylib, libimobiledevice stack)├── patches/ # Build-time patches (libirecovery)├── fw_prepare.sh # Download IPSWs, merge cloudOS into iPhone├── fw_manifest.py # Generate hybrid BuildManifest/Restore plists@@ -101,10 +102,10 @@ scripts/├── cfw_install_jb.sh # Regular + jetsam fix + procursus├── vm_create.sh # Create VM directory├── setup_machine.sh # Full automation (setup → first boot)-├── setup_tools.sh # Install deps, build toolchain, create venv+├── setup_tools.sh # Install deps, build toolchain from submodules, create venv├── setup_venv.sh # Create Python venv├── setup_venv_linux.sh # Create Python venv (Linux)-├── setup_libimobiledevice.sh # Build libimobiledevice from source+├── setup_libimobiledevice.sh # Build libimobiledevice stack from scripts/repos submodules└── tail_jb_patch_logs.sh # Tail JB patch log outputresearch/ # Detailed firmware/patch documentationdiff --git a/Makefile b/Makefileindex fe485968..02d7e06e 100644--- a/Makefile+++ b/Makefile@@ -53,7 +53,7 @@ help:@echo " SUDO_PASSWORD=... Preload sudo credential for setup flow"@echo ""@echo "Setup (one-time):"- @echo " make setup_tools Install all tools (brew, trustcache, insert_dylib, libimobiledevice, venv)"+ @echo " make setup_tools Install all tools (brew, submodule-sourced trustcache/insert_dylib/libimobiledevice, venv)"@echo ""@echo "Build:"@echo " make build Build + sign vphone-cli"diff --git a/README.md b/README.mdindex e55d9d3e..34153f15 100644--- a/README.md+++ b/README.md@@ -85,7 +85,7 @@ Boot into Recovery (long press power button), open Terminal, then choose one setbrew install ideviceinstaller wget gnu-tar openssl@3 ldid-procursus sshpass keystone autoconf automake pkg-config libtool cmake```-**Submodules** — this repo uses a git submodule for resource archives. Clone with:+**Submodules** — this repo uses git submodules for resources, vendored Swift deps, and toolchain sources under `scripts/repos/`. Clone with:```bashgit clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git@@ -103,7 +103,7 @@ make setup_machine # full automation through "First Boot" (includes r## Manual Setup```bash-make setup_tools # install brew deps, build trustcache, clone insert_dylib, build libimobiledevice, create Python venv+make setup_tools # install brew deps, build trustcache + insert_dylib + libimobiledevice from submodule sources, create Python venvmake build # build + sign vphone-climake vm_new # create VM directory with manifest (config.plist)# options: CPU=8 MEMORY=8192 DISK_SIZE=64diff --git a/docs/README_ja.md b/docs/README_ja.mdindex 757c9db5..ff73fb3a 100644--- a/docs/README_ja.md+++ b/docs/README_ja.md@@ -76,7 +76,7 @@ Apple の Virtualization.framework と PCC の研究用 VM インフラを使用brew install ideviceinstaller wget gnu-tar openssl@3 ldid-procursus sshpass keystone autoconf automake pkg-config libtool cmake```-**Submodules** — このリポジトリはリソースアーカイブに git submodule を使用しています。クローン時に以下を使用してください:+**Submodules** — このリポジトリはリソース、Swift 依存、`scripts/repos/` 配下のツールチェーンソースに git submodule を使用しています。クローン時に以下を使用してください:```bashgit clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git@@ -92,7 +92,7 @@ make setup_machine # 初回起動までを完全自動化(復元/## 手動セットアップ```bash-make setup_tools # brew の依存関係インストール、trustcache + libimobiledevice のビルド、Python venv の作成+make setup_tools # brew の依存関係インストール、submodule ソースから trustcache + insert_dylib + libimobiledevice をビルド、Python venv の作成make build # vphone-cli のビルド + 署名make vm_new # VM ディレクトリとマニフェスト(config.plist)の作成# オプション:CPU=8 MEMORY=8192 DISK_SIZE=64diff --git a/docs/README_ko.md b/docs/README_ko.mdindex 82838118..9125a737 100644--- a/docs/README_ko.md+++ b/docs/README_ko.md@@ -76,7 +76,7 @@ PCC 리서치 VM 인프라와 Apple의 Virtualization.framework를 사용하여brew install ideviceinstaller wget gnu-tar openssl@3 ldid-procursus sshpass keystone autoconf automake pkg-config libtool cmake```-**Submodules** — 이 저장소는 리소스 아카이브를 위해 git submodule을 사용합니다. 클론 시 다음 명령어를 사용하세요:+**Submodules** — 이 저장소는 리소스, Swift 의존성, `scripts/repos/` 아래 툴체인 소스를 git submodule로 관리합니다. 클론 시 다음 명령어를 사용하세요:```bashgit clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git@@ -92,7 +92,7 @@ make setup_machine # "First Boot"까지의 전체 과정 자동화 (## 수동 설정```bash-make setup_tools # brew 의존성 설치, trustcache + libimobiledevice 빌드, Python venv 생성+make setup_tools # brew 의존성 설치, submodule 소스에서 trustcache + insert_dylib + libimobiledevice 빌드, Python venv 생성make build # vphone-cli 빌드 및 서명make vm_new # VM 디렉토리 및 매니페스트(config.plist) 생성# 옵션: CPU=8 MEMORY=8192 DISK_SIZE=64diff --git a/docs/README_zh.md b/docs/README_zh.mdindex cd666299..922e4d35 100644--- a/docs/README_zh.md+++ b/docs/README_zh.md@@ -76,7 +76,7 @@brew install ideviceinstaller wget gnu-tar openssl@3 ldid-procursus sshpass keystone autoconf automake pkg-config libtool cmake```-**Submodules** —— 本仓库使用 git submodule 存储资源文件。克隆时请使用:+**Submodules** —— 本仓库通过 git submodule 管理资源、Swift 依赖以及 `scripts/repos/` 下的工具链源码。克隆时请使用:```bashgit clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git@@ -94,7 +94,7 @@ make setup_machine # 完全自动化完成"首次启动"流程(包## 手动设置```bash-make setup_tools # 安装 brew 依赖、构建 trustcache + libimobiledevice、创建 Python 虚拟环境+make setup_tools # 安装 brew 依赖、从 submodule 源码构建 trustcache + insert_dylib + libimobiledevice、创建 Python 虚拟环境make build # 构建并签名 vphone-climake vm_new # 创建 VM 目录及清单文件(config.plist)# 选项:CPU=8 MEMORY=8192 DISK_SIZE=64diff --git a/research/0_binary_patch_comparison.md b/research/0_binary_patch_comparison.mdindex 163a49dd..1d27e02d 100644--- a/research/0_binary_patch_comparison.md+++ b/research/0_binary_patch_comparison.md@@ -301,3 +301,7 @@- replaced the old AppKit-first recorder path with a private-display-only implementation built around hidden `VZGraphicsDisplay._takeScreenshotWithCompletionHandler:` capture.- added still screenshot actions that can copy the captured image to the pasteboard or save a PNG to disk using the same private capture path.- `make build` is used as the sanity check path; live VM validation is still needed to confirm the exact screenshot object type returned on macOS 15.+- 2026-03-15 tooling source sync update:+ - removed ad-hoc `git clone` source fetching from `scripts/setup_tools.sh` and `scripts/setup_libimobiledevice.sh`.+ - added pinned git-submodule sources under `scripts/repos/` for: `trustcache`, `insert_dylib`, `libplist`, `libimobiledevice-glue`, `libusbmuxd`, `libtatsu`, `libimobiledevice`, `libirecovery`, `idevicerestore`.+ - setup scripts now initialize required submodules via `git submodule update --init --recursive <path>` and stage build copies under local tool build directories.diff --git a/scripts/repos/idevicerestore b/scripts/repos/idevicerestorenew file mode 160000index 00000000..405fcd17--- /dev/null+++ b/scripts/repos/idevicerestore@@ -0,0 +1 @@+Subproject commit 405fcd17948ea4bd2571c76abd4451e8412b6260diff --git a/scripts/repos/insert_dylib b/scripts/repos/insert_dylibnew file mode 160000index 00000000..eb727816--- /dev/null+++ b/scripts/repos/insert_dylib@@ -0,0 +1 @@+Subproject commit eb7278162af8fcc372e7f2946a2dee6a386b17d8diff --git a/scripts/repos/libimobiledevice b/scripts/repos/libimobiledevicenew file mode 160000index 00000000..c4f11180--- /dev/null+++ b/scripts/repos/libimobiledevice@@ -0,0 +1 @@+Subproject commit c4f111800d2b08d6c65ec075ad49c4a60e9e4309diff --git a/scripts/repos/libimobiledevice-glue b/scripts/repos/libimobiledevice-gluenew file mode 160000index 00000000..da770a76--- /dev/null+++ b/scripts/repos/libimobiledevice-glue@@ -0,0 +1 @@+Subproject commit da770a7687f35fbb981db4d7b47b1b032cd5c2c7diff --git a/scripts/repos/libirecovery b/scripts/repos/libirecoverynew file mode 160000index 00000000..b59ef481--- /dev/null+++ b/scripts/repos/libirecovery@@ -0,0 +1 @@+Subproject commit b59ef4814525f487287da1609864f432cd79e3eddiff --git a/scripts/repos/libplist b/scripts/repos/libplistnew file mode 160000index 00000000..6e03a1df--- /dev/null+++ b/scripts/repos/libplist@@ -0,0 +1 @@+Subproject commit 6e03a1df6d1aa87c8f9e2b35f1a2ca60feca1c0ediff --git a/scripts/repos/libtatsu b/scripts/repos/libtatsunew file mode 160000index 00000000..60a39f36--- /dev/null+++ b/scripts/repos/libtatsu@@ -0,0 +1 @@+Subproject commit 60a39f36d719344360ec2e87563ed43f61f0530fdiff --git a/scripts/repos/libusbmuxd b/scripts/repos/libusbmuxdnew file mode 160000index 00000000..93eb168b--- /dev/null+++ b/scripts/repos/libusbmuxd@@ -0,0 +1 @@+Subproject commit 93eb168bf6b07472d17781328c21df0c60300524diff --git a/scripts/repos/libzip b/scripts/repos/libzipnew file mode 160000index 00000000..f2bbf19d--- /dev/null+++ b/scripts/repos/libzip@@ -0,0 +1 @@+Subproject commit f2bbf19d9f0a1c1d3746961b8d937fd2395b873adiff --git a/scripts/repos/trustcache b/scripts/repos/trustcachenew file mode 160000index 00000000..aa0e8847--- /dev/null+++ b/scripts/repos/trustcache@@ -0,0 +1 @@+Subproject commit aa0e8847529cf76576fce8d2dbc9e088c8f1a0dfdiff --git a/scripts/setup_libimobiledevice.sh b/scripts/setup_libimobiledevice.shindex 92963bdd..657a61bb 100755--- a/scripts/setup_libimobiledevice.sh+++ b/scripts/setup_libimobiledevice.sh@@ -3,18 +3,20 @@## Produces: idevicerestore, irecovery, and related idevice* tools# Prefix: .limd/ (override with LIMD_PREFIX env var)+# Source: scripts/repos/* git submodules (staged into .limd/src before build)# Requires: autoconf automake libtool pkg-config cmake gitset -euo pipefailSCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"+REPOS_DIR="$SCRIPT_DIR/repos"PREFIX="${LIMD_PREFIX:-$PROJECT_DIR/.limd}"SRC="$PREFIX/src"LOG="$PREFIX/log"-NPROC="$(sysctl -n hw.logicalcpu)"+NPROC="$(sysctl -n hw.logicalcpu 2>/dev/null || getconf _NPROCESSORS_ONLN 2>/dev/null || echo 4)"SDKROOT="$(xcrun --sdk macosx --show-sdk-path)"OPENSSL_PREFIX="$(brew --prefix openssl@3 2>/dev/null || true)"@@ -39,7 +41,7 @@ die() {check_tools() {local missing=()- for cmd in autoconf automake pkg-config cmake git; do+ for cmd in autoconf automake pkg-config cmake git patch; docommand -v "$cmd" &>/dev/null || missing+=("$cmd")donecommand -v glibtoolize &>/dev/null || command -v libtoolize &>/dev/null ||@@ -47,15 +49,33 @@ check_tools() {((${#missing[@]} == 0)) || die "Missing: ${missing[*]} — brew install ${missing[*]}"}-clone() {- local url="$1" dir="$2"- if [[ -d "$dir/.git" ]]; then- git -C "$dir" fetch --depth 1 origin --quiet- git -C "$dir" reset --hard FETCH_HEAD --quiet- git -C "$dir" clean -fdx --quiet- else- git clone --depth 1 "$url" "$dir" --quiet+ensure_repo_submodule() {+ local rel_path="$1"+ local abs_path="$PROJECT_DIR/$rel_path"++ if [[ ! -e "$abs_path/.git" ]]; then+ git -C "$PROJECT_DIR" submodule update --init --recursive "$rel_path"+ fi+}++stage_repo_source() {+ local name="$1"+ local src_dir="$REPOS_DIR/$name"+ local dst_dir="$SRC/$name"+ local version=""++ ensure_repo_submodule "scripts/repos/$name"+ rm -rf "$dst_dir"+ ditto "$src_dir" "$dst_dir"++ # Some autotools projects expect either git metadata or .tarball-version.+ # Staged sources are intentionally detached from git, so preserve version info.+ version="$(git -C "$src_dir" describe --tags --always 2>/dev/null || true)"+ if [[ -n "$version" ]]; then+ printf "%s\n" "$version" >"$dst_dir/.tarball-version"fi++ rm -rf "$dst_dir/.git"}build_lib() {@@ -76,12 +96,14 @@ build_lib() {check_toolsecho "Building libimobiledevice toolchain → $PREFIX"echo ""+echo "Using submodule sources from scripts/repos/"+echo ""# ── 1. Core libraries ───────────────────────────────────────────echo "[1/3] Core libraries (using homebrew openssl@3)"for lib in libplist libimobiledevice-glue libusbmuxd libtatsu libimobiledevice; do- clone "https://github.com/libimobiledevice/$lib" "$SRC/$lib"+ stage_repo_source "$lib"case "$lib" inlibplist | libimobiledevice) build_lib "$lib" --without-cython ;;*) build_lib "$lib" ;;@@ -91,42 +113,43 @@ done# ── 2. libirecovery (+ PCC research VM patch) ───────────────────echo "[2/3] libirecovery + libzip"-clone "https://github.com/libimobiledevice/libirecovery" "$SRC/libirecovery"+stage_repo_source "libirecovery"# PR #150: register iPhone99,11 / vresearch101ap for PCC research VMsif ! grep -q 'vresearch101ap' "$SRC/libirecovery/src/libirecovery.c"; then- cd "$SRC/libirecovery"- git apply "$SCRIPT_DIR/patches/libirecovery-pcc-vm.patch" ||- die "Failed to apply libirecovery PCC patch — check context"- cd "$SRC"+ if ! (cd "$SRC/libirecovery" && patch -p1 --batch --forward --dry-run <"$SCRIPT_DIR/patches/libirecovery-pcc-vm.patch" >/dev/null); then+ die "Failed to validate libirecovery PCC patch — check context"+ fi+ if ! (cd "$SRC/libirecovery" && patch -p1 --batch --forward <"$SCRIPT_DIR/patches/libirecovery-pcc-vm.patch" >"$LOG/libirecovery-pcc-vm.patch.log" 2>&1); then+ die "Failed to apply libirecovery PCC patch — see $LOG/libirecovery-pcc-vm.patch.log"+ fi+ grep -q 'vresearch101ap' "$SRC/libirecovery/src/libirecovery.c" ||+ die "libirecovery PCC patch command succeeded but expected marker is still missing"fibuild_lib libirecovery-# ── libzip (static, for idevicerestore) ──────────────────────────+# ── libzip (static, for idevicerestore, from submodule) ───────────-LIBZIP_VER="1.11.4"if [[ ! -f "$PREFIX/lib/pkgconfig/libzip.pc" ]]; thenecho " libzip"- [[ -d "$SRC/libzip-$LIBZIP_VER" ]] ||- curl -LfsS "https://github.com/nih-at/libzip/releases/download/v$LIBZIP_VER/libzip-$LIBZIP_VER.tar.gz" |- tar xz -C "$SRC"- cmake -S "$SRC/libzip-$LIBZIP_VER" -B "$SRC/libzip-$LIBZIP_VER/build" \+ stage_repo_source "libzip"+ cmake -S "$SRC/libzip" -B "$SRC/libzip/build" \-DCMAKE_INSTALL_PREFIX="$PREFIX" -DCMAKE_OSX_SYSROOT="$SDKROOT" \-DBUILD_SHARED_LIBS=OFF -DBUILD_DOC=OFF -DBUILD_EXAMPLES=OFF \-DBUILD_REGRESS=OFF -DBUILD_TOOLS=OFF \-DENABLE_BZIP2=OFF -DENABLE_LZMA=OFF -DENABLE_ZSTD=OFF \-DENABLE_GNUTLS=OFF -DENABLE_MBEDTLS=OFF -DENABLE_OPENSSL=OFF \>"$LOG/libzip-cmake.log" 2>&1- cmake --build "$SRC/libzip-$LIBZIP_VER/build" -j"$NPROC" \+ cmake --build "$SRC/libzip/build" -j"$NPROC" \>"$LOG/libzip-build.log" 2>&1- cmake --install "$SRC/libzip-$LIBZIP_VER/build" \+ cmake --install "$SRC/libzip/build" \>"$LOG/libzip-install.log" 2>&1fi# ── 3. idevicerestore ───────────────────────────────────────────echo "[3/3] idevicerestore"-clone "https://github.com/libimobiledevice/idevicerestore" "$SRC/idevicerestore"+stage_repo_source "idevicerestore"build_lib idevicerestore \libcurl_CFLAGS="-I$SDKROOT/usr/include" \libcurl_LIBS="-lcurl" \diff --git a/scripts/setup_tools.sh b/scripts/setup_tools.shindex 169b8cb7..9ca3c154 100644--- a/scripts/setup_tools.sh+++ b/scripts/setup_tools.sh@@ -2,26 +2,23 @@# setup_tools.sh — Install all required host tools for vphone-cli## Installs brew packages, builds trustcache from source,-# clones insert_dylib, builds libimobiledevice toolchain, and creates Python venv.+# builds insert_dylib from submodule source, builds libimobiledevice toolchain, and creates Python venv.## Run: make setup_toolsset -euo pipefail-SCRIPT_DIR="${0:a:h}"-PROJECT_DIR="${SCRIPT_DIR:h}"+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"+PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"TOOLS_PREFIX="${TOOLS_PREFIX:-$PROJECT_DIR/.tools}"+REPOS_DIR="$SCRIPT_DIR/repos"-clone_or_update() {- local url="$1"- local dir="$2"+ensure_repo_submodule() {+ local rel_path="$1"+ local abs_path="$PROJECT_DIR/$rel_path"- if [[ -d "$dir/.git" ]]; then- git -C "$dir" fetch --depth 1 origin --quiet- git -C "$dir" reset --hard FETCH_HEAD --quiet- git -C "$dir" clean -fdx --quiet- else- git clone --depth 1 "$url" "$dir" --quiet+ if [[ ! -e "$abs_path/.git" ]]; then+ git -C "$PROJECT_DIR" submodule update --init --recursive "$rel_path"fi}@@ -53,11 +50,14 @@ TRUSTCACHE_BIN="$TOOLS_PREFIX/bin/trustcache"if [[ -x "$TRUSTCACHE_BIN" ]]; thenecho " Already built: $TRUSTCACHE_BIN"else- echo " Building from source (CRKatri/trustcache)..."+ echo " Building from submodule source (scripts/repos/trustcache)..."+ ensure_repo_submodule "scripts/repos/trustcache"+BUILD_DIR=$(mktemp -d)trap "rm -rf '$BUILD_DIR'" EXIT- git clone --depth 1 https://github.com/CRKatri/trustcache.git "$BUILD_DIR/trustcache" --quiet+ ditto "$REPOS_DIR/trustcache" "$BUILD_DIR/trustcache"+ rm -rf "$BUILD_DIR/trustcache/.git"OPENSSL_PREFIX="$(brew --prefix openssl@3)"make -C "$BUILD_DIR/trustcache" \@@ -79,9 +79,8 @@ INSERT_DYLIB_BIN="$TOOLS_PREFIX/bin/insert_dylib"if [[ -x "$INSERT_DYLIB_BIN" ]]; thenecho " Already built: $INSERT_DYLIB_BIN"else- INSERT_DYLIB_DIR="$TOOLS_PREFIX/src/insert_dylib"- mkdir -p "${INSERT_DYLIB_DIR:h}"- clone_or_update "https://github.com/tyilo/insert_dylib" "$INSERT_DYLIB_DIR"+ INSERT_DYLIB_DIR="$REPOS_DIR/insert_dylib"+ ensure_repo_submodule "scripts/repos/insert_dylib"echo " Building insert_dylib..."mkdir -p "$TOOLS_PREFIX/bin"clang -o "$INSERT_DYLIB_BIN" "$INSERT_DYLIB_DIR/insert_dylib/main.c" -framework Security -O2