Run a virtual iPhone on an Apple Silicon Mac.
Swift
cli: Resolve --iphone-version and --iphone-build in vm create
zqxwcea3176db50f62
diff --git a/Documents/Guides/create-and-run.md b/Documents/Guides/create-and-run.mdindex d337ba24..bb91318c 100644--- a/Documents/Guides/create-and-run.md+++ b/Documents/Guides/create-and-run.md@@ -20,6 +20,8 @@ Creation runs prepare → firmware patch → online DFU restore → host-mountedBy default that pipeline builds a [template](#templates) rather than the VM itself, and the VM is cloned from it. The next `vm create` for the same device, iOS and cloudOS builds, preset and disk size clones from the same template instead of restoring again. Pass `--no-template` to build the VM on its own, as before.+`--iphone-version` or `--iphone-build` instead of `--iphone-source` resolves the IPSW as `fw prepare` does, for `--device` (iPhone17,3 by default). Without `--cloudos-source` the cloudOS is the one the catalog recommends for that release, as `fw catalog` lists it.+`--cpu`, `--memory`, `--network` and `--unlock-at-startup` set those `vm config` settings on the new VM (defaults: 8 cores, 8192 MB, nat, off). `--skip-first-boot` leaves out the final boot, for a caller that boots the VM itself.`fw prepare` creates a temporary vphone VM with no network device, starts it in DFU, and restores the selected cloudOS IPSW using this project's restore backend. It mounts the restored System volume read-only, extracts the GPU bundle, then removes the temporary VM. This first restore supplies the GPU driver for the second, hybrid iPhone restore. The extracted bundle is cached per cloudOS build in `~/.vphone/gpu-drivers/`, so later machines on the same cloudOS skip the temporary restore. `vm create` and `fw prepare` also accept `--gpu-driver-bundle /path/to/AppleParavirtGPUMetalIOGPUFamily.bundle` to reuse a previously extracted bundle without the temporary restore. The CLI checks its iPhoneOS platform version against the selected cloudOS version. Each restore obtains its own ticket online.diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareCommand.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareCommand.swiftindex 13baed94..01eb6945 100644--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareCommand.swift+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareCommand.swift@@ -262,9 +262,7 @@ struct VPhoneFirmwarePrepareCommand: ParsableCommand {func run() throws {let resources = projectRoot.map { VPhoneResources(base: URL(fileURLWithPath: $0)) } ?? .resolve()- let sourceGuide = resources.base.appendingPathComponent("Documents/Guides/compatibility.md")- let bundleGuide = resources.base.appendingPathComponent("docs/guides/compatibility.md")- let readme = FileManager.default.fileExists(atPath: sourceGuide.path) ? sourceGuide.path : bundleGuide.path+ let readme = VPhoneFirmwareSourceSelection.compatibilityGuide(resources)let needsCatalog = list || iphoneVersion != nil || iphoneBuild != nilif let device, VPhoneGuestDevice.named(device) == nil {throw ValidationError("vphone runs \(VPhoneGuestDevice.known.map(\.productType).joined(separator: ", ")) guests, not \(device).")@@ -278,15 +276,8 @@ struct VPhoneFirmwarePrepareCommand: ParsableCommand {throw ValidationError("--download-connections takes 1 to 16, not \(downloadConnections).")}let chosenDevice = device- // A device without an IPSW lists and resolves its restore base's.- let device = VPhoneGuestDevice.named(device)?.restoreBase?.productType ?? device ?? VPhoneFirmwareCatalog.device- let urls = if needsCatalog {- try vphoneRunBlocking {- try await VPhoneFirmwareIndex.restoreURLs(forDevice: device)- }.joined(separator: "\n")- } else {- ""- }+ let device = VPhoneFirmwareSourceSelection.lookupDevice(device)+ let urls = needsCatalog ? try VPhoneFirmwareSourceSelection.restoreURLs(forDevice: device) : ""if list {let code = VPhoneFirmwareMatrixCommandLine.list(@@ -305,19 +296,13 @@ struct VPhoneFirmwarePrepareCommand: ParsableCommand {guard source == nil else {throw ValidationError("Use either --iphone-source or --iphone-version/--iphone-build.")}- let selection = VPhoneFirmwareMatrix.selection(+ source = try VPhoneFirmwareSourceSelection.release(device: device,- version: iphoneVersion ?? "",- build: iphoneBuild ?? "",- readme: try? String(contentsOfFile: readme, encoding: .utf8),+ version: iphoneVersion,+ build: iphoneBuild,+ readme: readme,downloadURLs: urls,- style: .forStream(FileHandle.standardError.fileDescriptor),- )- switch selection {- case let .selected(release, _): source = release.url- case let .ambiguous(message), let .unmatched(message):- throw ValidationError(message.trimmingCharacters(in: .whitespacesAndNewlines))- }+ ).url}let selected = try VPhoneFirmwareSourceSelection.resolve(iphone: source, cloudos: cloudosSource, device: chosenDevice)diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareSourceSelection.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareSourceSelection.swiftindex 23948d8b..926a42e0 100644--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareSourceSelection.swift+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareSourceSelection.swift@@ -1,3 +1,4 @@+import ArgumentParserimport Foundationimport VPhoneCoreKit@@ -24,4 +25,48 @@ enum VPhoneFirmwareSourceSelection {write: { err($0) },)}++ // MARK: Version Selectors++ /// The compatibility guide whose Tested Environments table rates each build.+ static func compatibilityGuide(_ resources: VPhoneResources) -> String {+ let source = resources.base.appendingPathComponent("Documents/Guides/compatibility.md")+ let bundle = resources.base.appendingPathComponent("docs/guides/compatibility.md")+ return FileManager.default.fileExists(atPath: source.path) ? source.path : bundle.path+ }++ /// The device whose IPSWs a version selector looks up: a device without an+ /// IPSW lists and resolves its restore base's.+ static func lookupDevice(_ device: String?) -> String {+ VPhoneGuestDevice.named(device)?.restoreBase?.productType ?? device ?? VPhoneFirmwareCatalog.device+ }++ static func restoreURLs(forDevice device: String) throws -> String {+ try vphoneRunBlocking {+ try await VPhoneFirmwareIndex.restoreURLs(forDevice: device)+ }.joined(separator: "\n")+ }++ /// The downloadable IPSW `--iphone-version`/`--iphone-build` select.+ static func release(+ device: String,+ version: String?,+ build: String?,+ readme: String,+ downloadURLs: String,+ ) throws -> VPhoneFirmwareRelease {+ let selection = VPhoneFirmwareMatrix.selection(+ device: device,+ version: version ?? "",+ build: build ?? "",+ readme: try? String(contentsOfFile: readme, encoding: .utf8),+ downloadURLs: downloadURLs,+ style: .forStream(FileHandle.standardError.fileDescriptor),+ )+ switch selection {+ case let .selected(release, _): return release+ case let .ambiguous(message), let .unmatched(message):+ throw ValidationError(message.trimmingCharacters(in: .whitespacesAndNewlines))+ }+ }}diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreateCommand.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreateCommand.swiftindex 04fcb455..40d3d2d7 100644--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreateCommand.swift+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreateCommand.swift@@ -45,6 +45,10 @@ struct VPhoneVirtualMachineCreateCommand: ParsableCommand {@Argument(help: "new VM name") var name: String@Option(name: .shortAndLong, help: "iPhone IPSW URL or local path") var iphoneSource: String?@Option(name: .shortAndLong, help: "cloudOS IPSW URL or local path") var cloudosSource: String?+ @Option(help: "iPhone version to resolve to an IPSW; the cloudOS defaults to its recommended one")+ var iphoneVersion: String?+ @Option(help: "iPhone build to resolve to an IPSW; the cloudOS defaults to its recommended one")+ var iphoneBuild: String?@Option(help: "GPU driver bundle from the same cloudOS build, for offline AEA recovery")var gpuDriverBundle: String?@Option(help: "Directory for downloaded IPSWs, shared by every VM (default: ~/.vphone/ipsws or $VPHONE_ROOT/ipsws)")@@ -151,6 +155,9 @@ struct VPhoneVirtualMachineCreateCommand: ParsableCommand {inferredProductType = VPhoneIPSWCache.guestDevice(for: archive)?.productType}+ if iphoneSource != nil, iphoneVersion != nil || iphoneBuild != nil {+ throw ValidationError("Use either --iphone-source or --iphone-version/--iphone-build.")+ }if template != nil, noTemplate {throw ValidationError("--template and --no-template exclude each other.")}@@ -184,6 +191,8 @@ struct VPhoneVirtualMachineCreateCommand: ParsableCommand {let firmware = [("--iphone-source", iphoneSource != nil),("--cloudos-source", cloudosSource != nil),+ ("--iphone-version", iphoneVersion != nil),+ ("--iphone-build", iphoneBuild != nil),("--gpu-driver-bundle", gpuDriverBundle != nil),("--ipsw-cache", ipswCache != nil),("--keep-artifacts", keepArtifacts),@@ -222,9 +231,32 @@ struct VPhoneVirtualMachineCreateCommand: ParsableCommand {var sources = VPhoneFirmwareSources(iphoneSource: nil, cloudosSource: nil)if templateUse == .none || templateUse == .automatic {+ var iphone = iphoneSource+ var cloudos = cloudosSource+ if iphoneVersion != nil || iphoneBuild != nil {+ let lookup = VPhoneFirmwareSourceSelection.lookupDevice(selectedDevice)+ let release = try VPhoneFirmwareSourceSelection.release(+ device: lookup,+ version: iphoneVersion,+ build: iphoneBuild,+ readme: VPhoneFirmwareSourceSelection.compatibilityGuide(resources),+ downloadURLs: VPhoneFirmwareSourceSelection.restoreURLs(forDevice: lookup),+ )+ iphone = release.url+ print("[+] IPSW: \(release.version) (\(release.build)) \(release.url)")+ if cloudos == nil {+ let recommended = VPhoneFirmwareCatalog.recommendedCloudOS(+ forDevice: selectedDevice ?? VPhoneFirmwareCatalog.device,+ version: release.version,+ url: release.url,+ )+ cloudos = recommended.url+ print("[+] cloudOS: \(recommended.name), recommended for \(release.version)")+ }+ }// Prompt for any firmware component not supplied on the command line,// from the guest device's builds.- sources = try VPhoneFirmwareSourceSelection.resolve(iphone: iphoneSource, cloudos: cloudosSource, device: selectedDevice)+ sources = try VPhoneFirmwareSourceSelection.resolve(iphone: iphone, cloudos: cloudos, device: selectedDevice)guard sources.iphoneSource != nil, sources.cloudosSource != nil else {throw ValidationError("Specify both --iphone-source and --cloudos-source when running without a terminal.")}