Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

feat(fw): run the hybrid manifest generator for the first time, and switch to it

Lakr30d6a4731011
diff --git a/scripts/fw_manifest.py b/scripts/fw_manifest.py
index b6fbc75e..3463a4ed 100755
--- a/scripts/fw_manifest.py
+++ b/scripts/fw_manifest.py
@@ -1,5 +1,19 @@
#!/usr/bin/env python3
-"""Generate hybrid BuildManifest.plist and Restore.plist for vresearch1 restore.
+"""REFERENCE IMPLEMENTATION -- no longer called by anything.
+
+Superseded 2026-09-23 by `vphone-cli fw manifest`
+(sources/FirmwarePatcher/Manifest/FirmwareManifest.swift). Checked against
+this file on cloudOS 26.4-23E5207q x iPhone 27.0-24A435: same identity
+indices picked, and semantically identical BuildManifest.plist and
+Restore.plist.
+
+That is ONE build pair. What would break on another is the identity
+*selection* -- which identity counts as research, which as release, which as
+the erase identity -- and the only reason to keep this file is to re-run the
+comparison when a new pair lands. Do that before deleting it. It is one of
+the files D1 counts.
+
+Generate hybrid BuildManifest.plist and Restore.plist for vresearch1 restore.
Merges cloudOS boot-chain (vresearch101ap) with vphone600 runtime components
(device tree, SEP, kernel) and iPhone OS images into a single DFU erase-install
diff --git a/scripts/fw_prepare.sh b/scripts/fw_prepare.sh
index c9655269..a8076400 100755
--- a/scripts/fw_prepare.sh
+++ b/scripts/fw_prepare.sh
@@ -689,7 +689,18 @@ cp -n "${CLOUDOS_DIR}"/Firmware/*.dmg.trustcache "$IPHONE_DIR/Firmware"/ 2>/dev/
cp "$IPHONE_DIR/BuildManifest.plist" "$IPHONE_DIR/iPhone-BuildManifest.plist"
echo "==> Generating hybrid plists ..."
-"$PYTHON3" "$SCRIPT_DIR/fw_manifest.py" "$IPHONE_DIR" "$CLOUDOS_DIR"
+# VPHONE_CLI_BIN is set when a vphone-cli subcommand invokes this script; the
+# fallbacks cover being run by hand from a dev tree or from inside the .app,
+# where scripts/ sits in Contents/Resources and the binaries are in MacOS.
+PROJ_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+VPHONE_CLI="${VPHONE_CLI_BIN:-}"
+if [[ -z "$VPHONE_CLI" ]]; then
+ for candidate in "$PROJ_ROOT/.build/release/vphone-cli" "$(dirname "$PROJ_ROOT")/MacOS/vphone-cli"; do
+ [[ -x "$candidate" ]] && { VPHONE_CLI="$candidate"; break; }
+ done
+fi
+[[ -x "$VPHONE_CLI" ]] || { echo "ERROR: cannot find vphone-cli to generate the hybrid plists" >&2; exit 1; }
+"$VPHONE_CLI" fw manifest "$IPHONE_DIR" "$CLOUDOS_DIR"
echo "==> Cleaning up ..."
rm -rf "$CLOUDOS_DIR"
diff --git a/sources/vphone-cli/VPhoneFWCLI.swift b/sources/vphone-cli/VPhoneFWCLI.swift
index 7ca2588f..9f9c1294 100644
--- a/sources/vphone-cli/VPhoneFWCLI.swift
+++ b/sources/vphone-cli/VPhoneFWCLI.swift
@@ -7,7 +7,54 @@ struct VPhoneFWCommand: ParsableCommand {
static let configuration = CommandConfiguration(
commandName: "fw",
abstract: "Firmware pipeline: prepare (download/merge IPSWs) and patch",
- subcommands: [VPhoneFWCatalogCommand.self, VPhoneFWPrepareCommand.self, VPhoneFWPatchCommand.self])
+ subcommands: [
+ VPhoneFWCatalogCommand.self,
+ VPhoneFWPrepareCommand.self,
+ VPhoneFWPatchCommand.self,
+ VPhoneFWManifestCommand.self,
+ ])
+}
+
+// MARK: - manifest
+
+/// Replaces `scripts/fw_manifest.py`, called from `fw_prepare.sh` once both
+/// IPSWs are extracted and merged.
+struct VPhoneFWManifestCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "manifest",
+ abstract: "Write the hybrid BuildManifest.plist and Restore.plist into the iPhone directory",
+ discussion: """
+ Merges the cloudOS boot chain (vresearch101ap, which is what the VM
+ identifies as in DFU) with vphone600 runtime components and the iPhone
+ OS images into a single DFU erase-install build identity.
+
+ Both files are written into <iphone-dir>, replacing what is there.
+ fw_prepare.sh keeps the original as iPhone-BuildManifest.plist first.
+ """
+ )
+
+ @Argument(
+ help: "Extracted iPhone IPSW directory — also where the output is written",
+ transform: URL.init(fileURLWithPath:)
+ )
+ var iPhoneDirectory: URL
+
+ @Argument(
+ help: "Extracted cloudOS IPSW directory",
+ transform: URL.init(fileURLWithPath:)
+ )
+ var cloudOSDirectory: URL
+
+ @Flag(name: .shortAndLong, help: "Print which identities were selected")
+ var verbose = false
+
+ func run() throws {
+ try FirmwareManifest.generate(
+ iPhoneDir: iPhoneDirectory,
+ cloudOSDir: cloudOSDirectory,
+ verbose: true
+ )
+ }
}
// MARK: - catalog
diff --git a/tests/FirmwarePatcherTests/FirmwareManifestSelectionTests.swift b/tests/FirmwarePatcherTests/FirmwareManifestSelectionTests.swift
new file mode 100644
index 00000000..992b1f5e
--- /dev/null
+++ b/tests/FirmwarePatcherTests/FirmwareManifestSelectionTests.swift
@@ -0,0 +1,156 @@
+import Foundation
+import Testing
+@testable import FirmwarePatcher
+
+/// Identity selection for the hybrid manifest.
+///
+/// `FirmwareManifest.generate()` was translated from `scripts/fw_manifest.py`
+/// some time ago and then never called, so its equivalence was unknown until
+/// it was run. It has now been checked against the Python on a real pair —
+/// cloudOS 26.4-23E5207q and iPhone 27.0-24A435 — and produced semantically
+/// identical BuildManifest.plist and Restore.plist, down to the picked
+/// identity indices.
+///
+/// That is one build pair. What breaks on a different one is the *selection*:
+/// which identity counts as research, which as release, which as the erase
+/// identity. Those are pure functions over a build identity, so they can be
+/// pinned here without a firmware image, which is what these do.
+@Suite("Hybrid manifest identity selection")
+struct FirmwareManifestSelectionTests {
+ // MARK: - Fixtures
+
+ static func identity(
+ deviceClass: String,
+ variant: String = "Customer Erase Install (IPSW)",
+ llbPath: String? = nil
+ ) -> PlistDict {
+ var manifest = PlistDict()
+ if let llbPath {
+ manifest["LLB"] = ["Info": ["Path": llbPath] as PlistDict] as PlistDict
+ }
+ return [
+ "Info": [
+ "DeviceClass": deviceClass,
+ "Variant": variant,
+ ] as PlistDict,
+ "Manifest": manifest,
+ ]
+ }
+
+ // MARK: - isResearch
+
+ @Test("a four-part LLB filename with RESEARCH in field 3 marks a research identity")
+ func researchFromLLBPath() {
+ // Firmware/all_flash/LLB.vresearch101.RESEARCH.im4p -> 4 dot-separated
+ // parts, and the third says RESEARCH.
+ let bi = Self.identity(
+ deviceClass: "vresearch101ap",
+ llbPath: "Firmware/all_flash/LLB.vresearch101.RESEARCH.im4p"
+ )
+ #expect(FirmwareManifest.isResearch(bi))
+ }
+
+ @Test("the same filename shape with RELEASE does not")
+ func releaseFromLLBPath() {
+ let bi = Self.identity(
+ deviceClass: "vresearch101ap",
+ llbPath: "Firmware/all_flash/LLB.vresearch101.RELEASE.im4p"
+ )
+ #expect(!FirmwareManifest.isResearch(bi))
+ }
+
+ @Test("with no usable path, the Variant string decides")
+ func researchFromVariant() {
+ #expect(FirmwareManifest.isResearch(
+ Self.identity(deviceClass: "vresearch101ap", variant: "Research Erase Install (IPSW)")
+ ))
+ #expect(!FirmwareManifest.isResearch(
+ Self.identity(deviceClass: "vresearch101ap", variant: "Customer Erase Install (IPSW)")
+ ))
+ }
+
+ @Test("the Variant check is case-insensitive")
+ func researchVariantIsCaseInsensitive() {
+ #expect(FirmwareManifest.isResearch(
+ Self.identity(deviceClass: "vresearch101ap", variant: "RESEARCH Erase Install")
+ ))
+ }
+
+ @Test("a filename that is not four parts falls through to the Variant")
+ func nonFourPartPathFallsThrough() {
+ // "LLB.vresearch101.im4p" is three parts: no RESEARCH field to read,
+ // so the decision has to come from Variant instead of defaulting.
+ let bi = Self.identity(
+ deviceClass: "vresearch101ap",
+ variant: "Research Erase Install (IPSW)",
+ llbPath: "Firmware/all_flash/LLB.vresearch101.im4p"
+ )
+ #expect(FirmwareManifest.isResearch(bi))
+ }
+
+ // MARK: - findCloudOS
+
+ @Test("picks the first release and the first research for a device class")
+ func findsBothIdentities() throws {
+ let identities = [
+ Self.identity(deviceClass: "j226cap"),
+ Self.identity(deviceClass: "vphone600ap"),
+ Self.identity(deviceClass: "vresearch101ap"),
+ Self.identity(deviceClass: "vresearch101ap", variant: "Research Erase Install"),
+ Self.identity(deviceClass: "vresearch101ap", variant: "Research Erase Install"),
+ ]
+ let (release, research) = try FirmwareManifest.findCloudOS(
+ identities, deviceClass: "vresearch101ap"
+ )
+ #expect(release == 2)
+ #expect(research == 3) // the first research one, not the last
+ }
+
+ @Test("a device class with no research identity is an error, not a silent fallback")
+ func missingResearchThrows() {
+ let identities = [Self.identity(deviceClass: "vresearch101ap")]
+ #expect(throws: (any Error).self) {
+ try FirmwareManifest.findCloudOS(identities, deviceClass: "vresearch101ap")
+ }
+ }
+
+ @Test("an unknown device class is an error")
+ func missingDeviceClassThrows() {
+ let identities = [Self.identity(deviceClass: "j226cap")]
+ #expect(throws: (any Error).self) {
+ try FirmwareManifest.findCloudOS(identities, deviceClass: "vphone600ap")
+ }
+ }
+
+ // MARK: - findIPhoneErase
+
+ @Test("erase is the first identity that is not research, upgrade or recovery")
+ func findsEraseIdentity() throws {
+ let identities = [
+ Self.identity(deviceClass: "d47ap", variant: "Customer Upgrade Install (IPSW)"),
+ Self.identity(deviceClass: "d47ap", variant: "Research Erase Install (IPSW)"),
+ Self.identity(deviceClass: "d47ap", variant: "Recovery Customer Install"),
+ Self.identity(deviceClass: "d47ap", variant: "Customer Erase Install (IPSW)"),
+ ]
+ #expect(try FirmwareManifest.findIPhoneErase(identities) == 3)
+ }
+
+ @Test("the erase match is case-insensitive")
+ func eraseMatchIsCaseInsensitive() throws {
+ let identities = [
+ Self.identity(deviceClass: "d47ap", variant: "Customer UPGRADE Install"),
+ Self.identity(deviceClass: "d47ap", variant: "Customer Erase Install"),
+ ]
+ #expect(try FirmwareManifest.findIPhoneErase(identities) == 1)
+ }
+
+ @Test("an iPhone manifest with no erase identity is an error")
+ func missingEraseThrows() {
+ let identities = [
+ Self.identity(deviceClass: "d47ap", variant: "Customer Upgrade Install (IPSW)"),
+ ]
+ #expect(throws: (any Error).self) {
+ try FirmwareManifest.findIPhoneErase(identities)
+ }
+ }
+}