Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Find a create's template without its IPSWs, and record where templates came from

Jacky84eefee2536b
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreator.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreator.swift
index bbd4610d..b13a0c05 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreator.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreator.swift
@@ -336,6 +336,11 @@ public struct VPhoneVirtualMachineCreator {
builtWithBundleVersion: bundleVersion,
bootChainBundleVersion: bundleVersion,
sourceMachine: options.name,
+ // So `vm template find` keys a later request without the
+ // IPSWs, once they are deleted.
+ sources: options.iphoneSource.flatMap { phone in
+ options.cloudosSource.map { VPhoneMachineTemplateSources(iPhone: phone, cloudOS: $0) }
+ },
),
inBundle: bundle.url,
)
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineTemplateCommand.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineTemplateCommand.swift
index d47570ab..e0b2609f 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineTemplateCommand.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineTemplateCommand.swift
@@ -1,6 +1,9 @@
import ArgumentParser
+import Darwin
import Foundation
+import VPhoneArchiveKit
import VPhoneCoreKit
+import VPhonePatchKit
// MARK: - Command group
@@ -28,6 +31,7 @@ struct VPhoneVirtualMachineTemplateCommand: ParsableCommand {
subcommands: [
VPhoneVirtualMachineTemplateListCommand.self,
VPhoneVirtualMachineTemplateShowCommand.self,
+ VPhoneVirtualMachineTemplateFindCommand.self,
VPhoneVirtualMachineTemplateSetupCommand.self,
VPhoneVirtualMachineTemplateAdoptCommand.self,
VPhoneVirtualMachineTemplateTrimCommand.self,
@@ -56,6 +60,8 @@ struct VPhoneMachineTemplateReport: Encodable {
var machines: [String]
var stale: Bool
var staleReasons: [String]
+ /// The IPSW sources it was built from, when its build named them.
+ var sources: VPhoneMachineTemplateSources?
init(_ template: VPhoneMachineTemplate, usage: [String: [String]]) {
let record = template.record
@@ -72,6 +78,7 @@ struct VPhoneMachineTemplateReport: Encodable {
machines = usage[template.identifier] ?? []
staleReasons = VPhoneMachineTemplateKeys.staleReasons(template)
stale = !staleReasons.isEmpty
+ sources = record.sources
}
}
@@ -184,6 +191,157 @@ struct VPhoneVirtualMachineTemplateShowCommand: ParsableCommand {
}
}
+// MARK: - find
+
+/// What `find --json` prints. `resolved` is false when neither the IPSWs nor
+/// a template's recorded sources give the builds, and then only `reason`
+/// follows.
+struct VPhoneMachineTemplateFindReport: Encodable {
+ var resolved = false
+ /// `ipsw` (read from the IPSWs, local or cached) or `template` (taken
+ /// from a template built from the same sources).
+ var resolvedBy: String?
+ var id: String?
+ var summary: String?
+ var key: VPhoneMachineTemplateKey?
+ /// The template with this key, current or stale.
+ var template: VPhoneMachineTemplateReport?
+ /// True when `template` is there and current: `vm create --template`
+ /// with `id` clones from it.
+ var usable = false
+ /// A create is building this key right now.
+ var building = false
+ var reason: String?
+}
+
+struct VPhoneVirtualMachineTemplateFindCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "find",
+ abstract: "Find the template a vm create with these options would clone from",
+ discussion: """
+ Resolves the template key the way vm create does, without downloading anything or \
+ changing the library, and reports whether that template exists and is current. The \
+ builds come from the IPSWs when they are local files or in the IPSW cache; otherwise \
+ from a template whose record says it was built from the same two sources, so a key \
+ still resolves after its IPSWs were deleted. When neither works the key is unresolved \
+ and a create would download the IPSWs.
+
+ --block and --allow are the per-patch overrides fw set-patches records; a machine \
+ built with them has a boot-chain digest of its own.
+ """,
+ )
+
+ @OptionGroup var lib: VPhoneLibraryOption
+ @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: "Directory for downloaded IPSWs (default: ~/.vphone/ipsws or $VPHONE_ROOT/ipsws)")
+ var ipswCache: String?
+ @Option(help: ArgumentHelp("Guest device, when the IPSW covers several models", valueName: "product-type"))
+ var device: String?
+ @Option(name: .customLong("preset"), help: "Patch preset (default standard)") var preset: String?
+ @Option(name: .shortAndLong, help: "Disk size (GB, default 64)") var diskSize: UInt64?
+ @Option(name: .customLong("block"), help: ArgumentHelp("A patch the preset turns on, turned off", valueName: "id"))
+ var blocked: [String] = []
+ @Option(name: .customLong("allow"), help: ArgumentHelp("A patch the preset leaves off, turned on", valueName: "id"))
+ var allowed: [String] = []
+ @OptionGroup(title: "Template slimming") var slimming: VPhoneTemplateSlimmingOptions
+ @Flag(name: .shortAndLong, help: "Emit JSON") var json = false
+
+ func run() throws {
+ if let device, VPhoneGuestDevice.named(device) == nil {
+ throw ValidationError("vphone runs \(VPhoneGuestDevice.known.map(\.productType).joined(separator: ", ")) guests, not \(device).")
+ }
+ let wanted = try slimming.resolve()
+ guard wanted.problems.isEmpty else {
+ throw ValidationError("No template can be built with this slimming: \(wanted.problems.joined(separator: "; ")).")
+ }
+ let library = lib.library
+ var report = VPhoneMachineTemplateFindReport()
+ if let builds = try resolveBuilds(in: library, report: &report) {
+ let key = try VPhoneMachineTemplateKeys.key(
+ device: builds.device,
+ ios: builds.ios,
+ cloudOS: builds.cloudOS,
+ preset: preset ?? VPhonePatchPreset.standardIdentifier,
+ blocked: blocked,
+ allowed: allowed,
+ diskSizeGB: diskSize ?? 64,
+ slimming: wanted,
+ )
+ report.resolved = true
+ report.id = key.identifier
+ report.summary = key.summary
+ report.key = key
+ let listing = try VPhoneMachineTemplates.list(in: library)
+ report.building = listing.staging.contains { $0.identifier == key.identifier && $0.isActive }
+ if let template = try VPhoneMachineTemplates.template(for: key, in: library) {
+ let found = VPhoneMachineTemplateReport(template, usage: VPhoneMachineTemplates.usage(in: library))
+ report.template = found
+ report.usable = !found.stale
+ }
+ }
+ if json {
+ try print(encodeJSON(report))
+ return
+ }
+ guard report.resolved, let id = report.id else {
+ print("unresolved: \(report.reason ?? "unknown")")
+ return
+ }
+ print("key: \(id) \(report.summary ?? "")")
+ print("builds: from \(report.resolvedBy == "ipsw" ? "the IPSWs" : "a template built from the same sources")")
+ if let template = report.template {
+ print("template: \(template.id) \(template.stale ? "STALE" : "current"), "
+ + "\(VPhoneSystemTrim.formatBytes(template.allocatedBytes)) on disk")
+ for reason in template.staleReasons {
+ print(" stale: \(reason)")
+ }
+ } else {
+ print("template: none\(report.building ? " (a create is building it)" : "")")
+ }
+ }
+
+ private struct Builds {
+ var device: String
+ var ios: VPhoneRestoreInfo.OSVersion
+ var cloudOS: VPhoneRestoreInfo.OSVersion
+ }
+
+ /// The device and builds, from the IPSWs when they are here, else from a
+ /// template built from the same sources; nil with `report.reason` set.
+ private func resolveBuilds(in library: VPhoneLibrary, report: inout VPhoneMachineTemplateFindReport) throws -> Builds? {
+ let cache = ipswCache.map { URL(fileURLWithPath: ($0 as NSString).expandingTildeInPath, isDirectory: true) }
+ ?? VPhoneResources.ipswCacheDirectory()
+ if let phone = try VPhoneIPSWCache.localArchive(iphoneSource, in: cache),
+ let cloud = try VPhoneIPSWCache.localArchive(cloudosSource, in: cache)
+ {
+ try VPhoneIPSWCache.checkPair(iPhone: phone, cloudOS: cloud)
+ let guest = VPhoneIPSWCache.guestDevice(for: phone, preferring: device) ?? .default
+ if let device, VPhoneGuestDevice.named(device) != guest {
+ throw ValidationError("The iPhone IPSW is for \(phone.productTypes.joined(separator: ", ")), not \(device).")
+ }
+ report.resolvedBy = "ipsw"
+ return Builds(
+ device: guest.productType,
+ ios: .init(version: phone.version, build: phone.build),
+ cloudOS: .init(version: cloud.version, build: cloud.build),
+ )
+ }
+ let sources = VPhoneMachineTemplateSources(iPhone: iphoneSource, cloudOS: cloudosSource)
+ if let template = VPhoneMachineTemplates.templates(builtFrom: sources, device: device, in: library).first {
+ let key = template.key
+ report.resolvedBy = "template"
+ return Builds(
+ device: key.device,
+ ios: .init(version: key.iOSVersion, build: key.iOSBuild),
+ cloudOS: .init(version: key.cloudOSVersion, build: key.cloudOSBuild),
+ )
+ }
+ report.reason = "the IPSWs are not downloaded and no template records these sources"
+ return nil
+ }
+}
+
// MARK: - setup
struct VPhoneVirtualMachineTemplateSetupCommand: ParsableCommand {
@@ -222,6 +380,8 @@ struct VPhoneVirtualMachineTemplateSetupCommand: ParsableCommand {
var verboseCount: Int
func run() throws {
+ // Each step's line as it starts, also through a pipe (Launchpad).
+ setvbuf(stdout, nil, _IOLBF, 0)
let library = lib.library
let resources = VPhoneResources.resolve()
let verbosity = VPhoneVerbosity(count: verboseCount)
@@ -342,14 +502,30 @@ struct VPhoneVirtualMachineTemplateAdoptCommand: ParsableCommand {
exists. --force adopts a machine whose boot chain was built by another bundle series \
than this vphone-cli's, or whose patch receipt differs from its plan; such a template \
is listed as stale.
+
+ --iphone-source and --cloudos-source record the IPSWs the machine was created from, \
+ so vm template find resolves a request from the same sources after they are deleted.
""",
)
@OptionGroup var lib: VPhoneLibraryOption
@Argument(help: "VM name") var name: String
@Flag(help: "adopt even when the template would be stale") var force = false
+ @Option(name: .shortAndLong, help: "iPhone IPSW URL or path the machine was created from") var iphoneSource: String?
+ @Option(name: .shortAndLong, help: "cloudOS IPSW URL or path the machine was created from") var cloudosSource: String?
+ @Flag(name: .shortAndLong, help: "Emit the new template as JSON (as vm template show --json)") var json = false
+
+ func validate() throws {
+ if (iphoneSource == nil) != (cloudosSource == nil) {
+ throw ValidationError("Give both --iphone-source and --cloudos-source, or neither.")
+ }
+ }
func run() throws {
+ // With --json, progress goes to stderr and stdout carries the report.
+ let say: (String) -> Void = json
+ ? { FileHandle.standardError.write(Data(($0 + "\n").utf8)) }
+ : { print($0) }
let bundle = try lib.library.bundle(named: name)
try VPhoneBundleActivity.requireStopped(bundle)
let previous = try VPhoneMachineTemplates.readRecord(inBundle: bundle.url)
@@ -368,9 +544,12 @@ struct VPhoneVirtualMachineTemplateAdoptCommand: ParsableCommand {
throw ValidationError("VM '\(name)' would be a stale template: \(problems.joined(separator: "; ")). Pass --force to adopt it anyway.")
}
for problem in problems {
- print("warning: \(problem)")
+ say("warning: \(problem)")
}
}
+ let sources = iphoneSource.flatMap { phone in
+ cloudosSource.map { VPhoneMachineTemplateSources(iPhone: phone, cloudOS: $0) }
+ }
let record = VPhoneMachineTemplateRecord(
key: recorded.key,
created: previous?.created ?? Date(),
@@ -378,11 +557,16 @@ struct VPhoneVirtualMachineTemplateAdoptCommand: ParsableCommand {
bootChainBundleVersion: recorded.bootChainBundleVersion,
sourceMachine: name,
steps: steps,
+ sources: sources ?? previous?.sources,
)
if let tree = VPhoneMachineTemplates.restoreTree(of: bundle) {
- print("[*] Removing the restore tree \(tree)/: a template never keeps it")
+ say("[*] Removing the restore tree \(tree)/: a template never keeps it")
}
let template = try VPhoneMachineTemplates.adopt(machineNamed: name, in: lib.library, record: record)
+ if json {
+ try print(encodeJSON(VPhoneMachineTemplateReport(template, usage: VPhoneMachineTemplates.usage(in: lib.library))))
+ return
+ }
print("adopted \(name) as template \(template.identifier)")
print(" \(template.key.summary)")
print("create machines from it with: vphone-cli vm create <name> --template \(template.identifier)")
@@ -422,6 +606,7 @@ struct VPhoneVirtualMachineTemplateTrimCommand: ParsableCommand {
@Flag(name: .shortAndLong, help: "Emit JSON") var json = false
func run() throws {
+ setvbuf(stdout, nil, _IOLBF, 0)
let spec = try VPhoneSystemTrimSpec.parse(tier: tier, keptLanguages: keepLanguages)
let library = lib.library
let bundle: VPhoneBundle
diff --git a/VPhoneKit/VPhoneArchiveKit/Transfer/VPhoneIPSWCache.swift b/VPhoneKit/VPhoneArchiveKit/Transfer/VPhoneIPSWCache.swift
index 2aeb5f0d..242b6f76 100644
--- a/VPhoneKit/VPhoneArchiveKit/Transfer/VPhoneIPSWCache.swift
+++ b/VPhoneKit/VPhoneArchiveKit/Transfer/VPhoneIPSWCache.swift
@@ -114,6 +114,25 @@ public enum VPhoneIPSWCache {
)
}
+ /// `source` as ``resolve(_:in:session:connections:progress:)`` would
+ /// return it, without downloading: a local file is read in place, a
+ /// remote one only when the cache holds a readable copy. Nil when a
+ /// remote source is not in the cache; nothing is written or removed.
+ public static func localArchive(_ source: String, in cacheDirectory: URL) throws -> Archive? {
+ guard let url = URL(string: source), let scheme = url.scheme?.lowercased() else {
+ return try inspect(URL(fileURLWithPath: source))
+ }
+ if scheme == "file" {
+ return try inspect(url)
+ }
+ guard scheme == "http" || scheme == "https" else {
+ throw Error.unsupportedSource(source)
+ }
+ let cache = cacheDirectory.appendingPathComponent(cacheName(for: url))
+ guard FileManager.default.fileExists(atPath: cache.path) else { return nil }
+ return try? inspect(cache)
+ }
+
/// The cached archive when it is readable; an unreadable one is removed.
private static func reuse(_ cache: URL, in _: URL) throws -> Archive? {
guard FileManager.default.fileExists(atPath: cache.path) else { return nil }
diff --git a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplates.swift b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplates.swift
index 39b06030..ceaf804e 100644
--- a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplates.swift
+++ b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplates.swift
@@ -106,6 +106,27 @@ public struct VPhoneMachineTemplateSource: Codable, Equatable, Sendable {
}
}
+// MARK: - Sources
+
+/// The IPSW sources a template was built from, as the create named them: a
+/// URL or a local path for each. `vm template find` matches a request
+/// against them, so a create finds its template after the IPSWs it came
+/// from were deleted, without downloading them again to read their builds.
+public struct VPhoneMachineTemplateSources: Codable, Equatable, Sendable {
+ public var iPhone: String
+ public var cloudOS: String
+
+ public init(iPhone: String, cloudOS: String) {
+ self.iPhone = iPhone
+ self.cloudOS = cloudOS
+ }
+
+ private enum CodingKeys: String, CodingKey {
+ case iPhone = "IPhone"
+ case cloudOS = "CloudOS"
+ }
+}
+
// MARK: - Record
/// `Template.plist`, in the template's machine folder.
@@ -124,6 +145,10 @@ public struct VPhoneMachineTemplateRecord: Codable, Equatable, Sendable {
public var frozen: Bool
public var frozenAt: Date?
public var steps: VPhoneMachineTemplateSteps
+ /// The IPSWs it was built from, when the build named them; nil for a
+ /// template adopted without them. Not part of the key: two URLs of the
+ /// same build make the same template.
+ public var sources: VPhoneMachineTemplateSources?
public init(
key: VPhoneMachineTemplateKey,
@@ -134,6 +159,7 @@ public struct VPhoneMachineTemplateRecord: Codable, Equatable, Sendable {
frozen: Bool = false,
frozenAt: Date? = nil,
steps: VPhoneMachineTemplateSteps = VPhoneMachineTemplateSteps(),
+ sources: VPhoneMachineTemplateSources? = nil,
) {
identifier = key.identifier
self.key = key
@@ -144,6 +170,7 @@ public struct VPhoneMachineTemplateRecord: Codable, Equatable, Sendable {
self.frozen = frozen
self.frozenAt = frozenAt.map(VPhoneMachineTemplates.wholeSeconds)
self.steps = steps
+ self.sources = sources
}
private enum CodingKeys: String, CodingKey {
@@ -156,6 +183,7 @@ public struct VPhoneMachineTemplateRecord: Codable, Equatable, Sendable {
case frozen = "Frozen"
case frozenAt = "FrozenAt"
case steps = "Steps"
+ case sources = "Sources"
}
public init(from decoder: any Decoder) throws {
@@ -169,6 +197,7 @@ public struct VPhoneMachineTemplateRecord: Codable, Equatable, Sendable {
frozen = try container.decodeIfPresent(Bool.self, forKey: .frozen) ?? false
frozenAt = try container.decodeIfPresent(Date.self, forKey: .frozenAt)
steps = try container.decodeIfPresent(VPhoneMachineTemplateSteps.self, forKey: .steps) ?? VPhoneMachineTemplateSteps()
+ sources = try container.decodeIfPresent(VPhoneMachineTemplateSources.self, forKey: .sources)
}
}
@@ -446,6 +475,22 @@ public enum VPhoneMachineTemplates {
return only
}
+ /// The frozen templates whose record says they were built from these two
+ /// sources, newest first. Their keys give the builds those sources hold,
+ /// so a request can be keyed without the IPSWs, which may have been
+ /// deleted since. A template for another `device` is left out when one
+ /// is named.
+ public static func templates(
+ builtFrom sources: VPhoneMachineTemplateSources,
+ device: String? = nil,
+ in library: VPhoneLibrary,
+ ) -> [VPhoneMachineTemplate] {
+ let templates = (try? list(in: library).templates) ?? []
+ return templates
+ .filter { $0.record.sources == sources && (device == nil || $0.key.device == device) }
+ .sorted { $0.record.created > $1.record.created }
+ }
+
/// The template whose key this is, if one is frozen.
public static func template(for key: VPhoneMachineTemplateKey, in library: VPhoneLibrary) throws -> VPhoneMachineTemplate? {
let url = url(of: key.identifier, in: library)
diff --git a/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplatesTests.swift b/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplatesTests.swift
index 105aee05..96b24323 100644
--- a/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplatesTests.swift
+++ b/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplatesTests.swift
@@ -563,4 +563,52 @@ struct MachineTemplatesTests {
#expect(VPhoneMachineTemplates.readSource(inBundle: machine.url) == nil)
#expect(VPhoneMachineTemplates.usage(in: fixture.library).isEmpty)
}
+
+ // MARK: - Sources
+
+ @Test func `a record keeps the IPSW sources it was built from, and an older record has none`() throws {
+ let fixture = try makeFixture()
+ defer { fixture.cleanUp() }
+ let machine = try makeMachine("src", in: fixture)
+ var built = record()
+ built.sources = VPhoneMachineTemplateSources(iPhone: "https://example.invalid/iPhone17,3_27.0_24A435_Restore.ipsw", cloudOS: "/tmp/cloudos.ipsw")
+ try VPhoneMachineTemplates.writeRecord(built, inBundle: machine.url)
+ #expect(try VPhoneMachineTemplates.readRecord(inBundle: machine.url)?.sources == built.sources)
+ let plist = try String(contentsOf: machine.url.appendingPathComponent(VPhoneMachineTemplates.recordFileName), encoding: .utf8)
+ #expect(plist.contains("<key>Sources</key>"))
+ #expect(plist.contains("<key>IPhone</key>"))
+ #expect(plist.contains("<key>CloudOS</key>"))
+
+ // A record written before sources were kept reads as none.
+ try VPhoneMachineTemplates.writeRecord(record(), inBundle: machine.url)
+ #expect(try VPhoneMachineTemplates.readRecord(inBundle: machine.url)?.sources == nil)
+ }
+
+ @Test func `templates built from the same sources are found by them, newest first, per device`() throws {
+ let fixture = try makeFixture()
+ defer { fixture.cleanUp() }
+ let sources = VPhoneMachineTemplateSources(iPhone: "https://example.invalid/a.ipsw", cloudOS: "https://example.invalid/c")
+ try makeMachine("one", in: fixture)
+ try makeMachine("two", in: fixture)
+ try makeMachine("three", in: fixture)
+ var older = record()
+ older.sources = sources
+ let newer = VPhoneMachineTemplateRecord(
+ key: MachineTemplateKeyTests.key(disk: 128),
+ created: Date(timeIntervalSince1970: 1_900_000_000),
+ sourceMachine: "two",
+ sources: sources,
+ )
+ let other = VPhoneMachineTemplateRecord(key: MachineTemplateKeyTests.key(disk: 32), sourceMachine: "three")
+ let first = try VPhoneMachineTemplates.adopt(machineNamed: "one", in: fixture.library, record: older)
+ let second = try VPhoneMachineTemplates.adopt(machineNamed: "two", in: fixture.library, record: newer)
+ try VPhoneMachineTemplates.adopt(machineNamed: "three", in: fixture.library, record: other)
+
+ let found = VPhoneMachineTemplates.templates(builtFrom: sources, in: fixture.library)
+ #expect(found.map(\.identifier) == [second.identifier, first.identifier])
+ #expect(VPhoneMachineTemplates.templates(builtFrom: sources, device: "iPhone17,3", in: fixture.library).count == 2)
+ #expect(VPhoneMachineTemplates.templates(builtFrom: sources, device: "iPad16,1", in: fixture.library).isEmpty)
+ let elsewhere = VPhoneMachineTemplateSources(iPhone: "https://example.invalid/a.ipsw", cloudOS: "https://example.invalid/other")
+ #expect(VPhoneMachineTemplates.templates(builtFrom: elsewhere, in: fixture.library).isEmpty)
+ }
}