Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Keep templates under the key their request asked for, and find them without downloading

Jackybfeb3628443f
diff --git a/Documents/Guides/create-and-run.md b/Documents/Guides/create-and-run.md
index cc245501..385f2006 100644
--- a/Documents/Guides/create-and-run.md
+++ b/Documents/Guides/create-and-run.md
@@ -44,8 +44,8 @@ The guest shows the VM's name as its device name, in Xcode's device list and `xc
A template is a complete machine kept in `<library>/.templates/<id>/`. It boots once while it is built, its setup boot, and never again once it is frozen. `vm create` without `--no-template` works out the template key from its options and the two IPSWs before anything is restored: the guest device, the iOS and cloudOS versions and builds, the patch preset and the boot-chain patches it resolves to, the bundle series (`2.9` for 2.9.x), the disk size, what is trimmed from the guest's System volume (`--trim`), and the slimming switches below. Then:
-- If a template with that key exists, the VM is cloned from it with a new identity, given the requested CPU, memory and network, and booted once to check vphoned. This takes seconds and needs neither root nor the IPSWs; nothing is downloaded.
-- Otherwise the full pipeline runs into a staging folder, `.templates/.building-<id>-<uuid>/`: `cfw install`, the offline trim, then the setup boot; the result is frozen and renamed to `.templates/<id>/` in one step, and the VM is cloned from it. The restore tree is removed before the freeze whatever `--keep-artifacts` says: a template never keeps it, because its ~11 GB would stay pinned for as long as the template lives and no clone can use it. `--keep-artifacts` keeps it only with `--no-template`, and `vm template adopt` removes it too. A second `vm create` with the same key waits for the first instead of restoring a second copy. A failed build stays in its staging folder for inspection.
+- If a template with that key exists, the VM is cloned from it with a new identity, given the requested CPU, memory and network, and booted once to check vphoned. This takes seconds and needs neither root nor the IPSWs; nothing is downloaded. The builds come from the IPSWs when they are local files or already in the IPSW cache, and otherwise from a template recorded with the same two sources, as [`vm template find`](#finding-a-template) works them out; a local IPSW that has been deleted counts as not there.
+- Otherwise the IPSWs are downloaded if they are not there, and the full pipeline runs into a staging folder, `.templates/.building-<id>-<uuid>/`: `cfw install`, the offline trim, then the setup boot; the result is frozen and renamed to `.templates/<id>/` in one step, and the VM is cloned from it. The restore tree is removed before the freeze whatever `--keep-artifacts` says: a template never keeps it, because its ~11 GB would stay pinned for as long as the template lives and no clone can use it. `--keep-artifacts` keeps it only with `--no-template`, and `vm template adopt` removes it too. A second `vm create` with the same key waits for the first instead of restoring a second copy. A failed build stays in its staging folder for inspection.
```sh
vphone-cli vm create phone-a --iphone-source … --cloudos-source … # builds the template, clones phone-a
@@ -112,7 +112,9 @@ vphone-cli vm create phone-d --template <id> --skip-first-boot
`--iphone-source` and `--cloudos-source` on `vm template adopt` record the IPSWs the VM was created from in its `Template.plist`, as a `vm create` that builds a template does. `--json` prints the new template as `vm template show --json` does.
-`vm template setup` refuses a running VM and a frozen template. It trims nothing itself: the tier `vm template trim` recorded is kept, and a `--trim` that names another tier is refused. On a VM it reports an app vphoned would not remove and leaves it out of the recorded steps, so the adopted key says what was really done. Given a `.building-…` name from `vm template list` (a `vm create` whose setup boot failed), it sets the build up to its key, which fixes the slimming, runs the offline trim first if the build stopped before it, and freezes it on success.
+`--expect <id>` on `vm template adopt` refuses, and leaves the VM where it is, unless its records give the template identifier `<id>`: the `id` that `vm template find` printed for the options the VM was built with. Without the check, a VM whose setup boot fell short (an app it could not remove) would be saved under another key, and every later `vm create` with those options would miss it and build another template. The refusal names the fields that differ when it can work out the expected key, which it can when a template or build in the library has it or when only the slimming differs; otherwise it prints the VM's own key to compare. With `--json` the refusal is also printed to stdout as `{"adopted": false, "error": "unexpected_template", "id": …, "expected": …, "differences": […], …}`, and the command exits with status 1.
+
+`vm template setup` refuses a running VM and a frozen template. It trims nothing itself: the tier `vm template trim` recorded is kept, and a `--trim` that names another tier is refused. On a VM it reports an app vphoned would not remove and leaves it out of the recorded steps, so the adopted key says what was really done. With `--strict` it fails instead, records nothing, and the setup boot can be run again: use it when the VM is to be adopted with `--expect` under the key `vm template find` gave for the same switches. Given a `.building-…` name from `vm template list` (a `vm create` whose setup boot failed), it sets the build up to its key, which fixes the slimming, runs the offline trim first if the build stopped before it, and freezes it on success.
### Finding a template
@@ -122,7 +124,7 @@ vphone-cli vm create phone-d --template <id> --skip-first-boot
vphone-cli vm template find --iphone-source … --cloudos-source … [--device …] [--preset …] [--disk-size …] [--block <id>] [--allow <id>] [slimming switches] --json
```
-It works out the key as `vm create` does. The builds come from the IPSWs when they are local files or already in the IPSW cache, and otherwise from a template whose record names the same two sources, so the key still resolves once the IPSWs were deleted. `--block` and `--allow` are per-patch overrides as `fw set-patches` records them. The JSON has `resolved`, `resolvedBy` (`ipsw` or `template`), `id`, `summary`, `key`, `template` (the matching template as `vm template show --json` prints it, current or stale), `usable` (it exists and is current), `building` (a create holds its build lock) and, when unresolved, `reason`.
+It works out the key as `vm create` does. The builds come from the IPSWs when they are local files or already in the IPSW cache, and otherwise from a template whose record names the same two sources, so the key still resolves once the IPSWs were deleted, local ones included. `--block` and `--allow` are per-patch overrides as `fw set-patches` records them. The JSON has `resolved`, `resolvedBy` (`ipsw` or `template`), `id`, `summary`, `key`, `template` (the matching template as `vm template show --json` prints it, current or stale), `usable` (it exists and is current), `building` (a create holds its build lock) and, when unresolved, `reason`.
### In Launchpad
@@ -153,7 +155,7 @@ vphone-cli vm template delete <id>
```
note: template 3f2a91c0d4e7 (~17.40 GB) is no longer used by any machine; remove it with `vphone-cli vm template delete 3f2a91c0d4e7`
```
-- **Deleting.** `vm template delete <id>` removes the template; machines cloned from it keep working. The blocks they still share with it are freed only when those machines change them or are deleted, so deleting a template frees less than its size while clones remain. Templates take disk space although `vm list` does not show them; look in `~/.vphone/machines/.templates`, keeping in mind that `du` counts a template and each of its clones in full.
+- **Deleting.** `vm template delete <id>` removes the template; machines cloned from it keep working. The blocks they still share with it are freed only when those machines change them or are deleted, so deleting a template frees less than its size while clones remain. The note it prints says which: the machines that still share its blocks, or that none does and its space is free now. Templates take disk space although `vm list` does not show them; look in `~/.vphone/machines/.templates`, keeping in mind that `du` counts a template and each of its clones in full.
## Manual stages
diff --git a/Research/Host/machine_templates.md b/Research/Host/machine_templates.md
index 1570c983..392a0f06 100644
--- a/Research/Host/machine_templates.md
+++ b/Research/Host/machine_templates.md
@@ -79,10 +79,20 @@ re-resolves with the template's own `PatchSelection.plist`.
`SetupDone`, `ServiceProfile`, `ServiceGroups`, `RemovedApps`, `TrimTier`),
`Sources` (`IPhone`, `CloudOS`: the IPSW sources a `vm create` build or
`vm template adopt --iphone-source … --cloudos-source …` named; not part of
- the key). `vm template find` resolves a request whose IPSWs are neither
- local nor cached from a template recorded with the same sources
- (`VPhoneMachineTemplates.templates(builtFrom:device:in:)`), so Launchpad
- can offer to delete a template's IPSWs.
+ the key). `vm template find` and `vm create` resolve a request's builds
+ the same way, without downloading (`VPhoneMachineTemplates.resolveBuilds`,
+ `VPhoneMachineTemplateKeys.resolveBuilds`): from the IPSWs when both are
+ local files or cached, else from the newest template recorded with the
+ same sources (`templates(builtFrom:device:in:)`). A local path that no
+ longer exists counts as not here (`VPhoneIPSWCache.localArchive` answers
+ nil); a local file that is not an IPSW is still an error. `vm create`
+ downloads only when no template matches and it has to build one, so
+ Launchpad can offer to delete a template's IPSWs and a CLI create clones
+ without them. Until 2026-10-09 `vm create` resolved through
+ `VPhoneFirmwarePreparer.resolveSources` first and downloaded both IPSWs
+ (about 13 GB) before it looked for a template, and `find` failed with "IPSW
+ not found" for a deleted local IPSW (Launchpad 2.9 end-to-end test, B3 and
+ B4).
- `TemplateSource.plist` in a machine cloned from a template: `Identifier`,
`Cloned`. A plain `vm clone` keeps it (the copy shares the template's
blocks too); `vm export` excludes it (an import shares nothing).
@@ -91,6 +101,11 @@ re-resolves with the template's own `PatchSelection.plist`.
template list/show` print it with the template's allocated size; `vm delete`
of the last machine using a template that still exists prints a note to
delete it (`unusedTemplate(after:in:)`), never deleting it itself.
+ `vm template delete` says what the deletion frees
+ (`VPhoneMachineTemplates.deletionNote`, from `usage` read before it): with
+ machines using the template, that they still share its blocks, freed only
+ when they change them or are deleted; with none, that its space is free
+ now. Until 2026-10-09 it printed the first note whatever the usage (B8).
- A build happens in `.building-<id>-<uuid>/<id>/` and is frozen by writing
`Frozen = true` and one `renamex_np(RENAME_EXCL)` to `.templates/<id>`. A
listed template is always complete; a race with another build of the same
@@ -311,9 +326,27 @@ Retries: a call that did not reach vphoned (no socket, guest not connected,
timeout) or that vphoned refused with `retryable: true` or `reason: busy`
(`apfs.snapshot.delete` on EBUSY) is repeated every 3 s until the step's
deadline. Other refusals fail the step, except `apps.remove_system`'s
-`remove_incomplete`, whose `results` are read: a template build (key fixed)
-fails on any app not removed; a machine to be adopted reports it and leaves it
-out of the recorded steps, so the adopted key says what was done.
+`remove_incomplete`, whose `results` are read: a strict setup boot fails on
+any app not removed; a lenient one reports it and leaves it out of the
+recorded steps, so the adopted key says what was done. A template build (key
+fixed) is always strict, and so is `vm template setup --strict` on a machine
+(`VPhoneTemplateSetupPlan.requiresEveryApp`); a strict run also checks, once
+the profile is applied, that nothing fell short of the plan
+(`VPhoneTemplateSetupOutcome.deviations(from:)`) and fails before the reboot
+if anything did.
+
+An app left behind was seen once in two setup boots on 27.0 (2026-10-08,
+Find My): "LaunchServices still lists the app after unregistration". icli's
+`unregisterApp` looks at the record straight after `icli_unregister_app`, and
+LaunchServices had not dropped it yet. The lenient setup boot then recorded
+nine removed apps, `adopt` saved the template under a key `vm template find`
+never computes for the default options, and every later create with them
+missed it and built another 17.5 GB template (B1). vphoned now polls the
+record every 0.1 s for up to 2.5 s, unregisters once more if it is still
+listed, and only then fails the app (`GuestAppUnregistration`). For Launchpad
+the setup boot is meant to run with `--strict` and the adopt with
+`--expect <id>` (below), so a template is never saved under a key the request
+did not ask for.
On any failure the VM is killed, the failure names the step
(`VPhoneTemplateSetupFailure`), and nothing is recorded:
@@ -379,6 +412,20 @@ made after the latest one, as these clones were.
recorded, and refuses a `--trim` that names another one.
- `freeze` and `adopt` refuse a record whose steps did not produce the key's
slimming, and a trim whose snapshot was not deleted.
+- `vm template adopt <vm> --expect <id>` refuses, before anything moves,
+ unless the key the machine's records give hashes to `<id>`, the identifier
+ `vm template find` gave the request
+ (`VPhoneMachineTemplateKey.mismatch(expecting:known:)`). A hash cannot be
+ undone, so the expected key is looked for among the library's templates and
+ builds, then among the keys that differ from the machine's only in slimming
+ (trim tier, setup boot, profile, groups, any subset of the default apps:
+ some tens of thousands of hashes); when found, the refusal names each field
+ (`removed apps: expected com.apple.findmy removed too, the machine still
+ has it`), otherwise it spells out the machine's canonical description to
+ compare with `find --json`'s key. With `--json` the refusal is also printed
+ to stdout: `adopted: false`, `error: unexpected_template`, `message`, `id`
+ (computed), `expected`, `key`, `expectedKey` (or null), `differences`,
+ `canonicalDescription`, `steps`; the exit status is 1.
## Staleness
diff --git a/Research/vphoned_http_api.md b/Research/vphoned_http_api.md
index bec4e035..dfeca446 100644
--- a/Research/vphoned_http_api.md
+++ b/Research/vphoned_http_api.md
@@ -557,7 +557,12 @@ path shape (`GuestSystemAppPolicy.swift`). Then, in this order:
`copy`. A backup of the same app in the legacy directory (below) is removed
once the new removal is done. `backup: false` skips this;
2. the app is unregistered from LaunchServices (icli's `unregisterApp`, as
- `apps.unregister`);
+ `apps.unregister`). LaunchServices can list it for a moment longer, and
+ icli checks at once, so vphoned looks at the record again every 0.1 s for
+ up to 2.5 s before it believes "still lists the app", unregisters once
+ more if it is still listed, waits as long again, and only then fails the
+ app (`GuestAppUnregistration`); `unregister_attempts` in the app's result
+ says when a second unregistration was needed;
3. the container is removed recursively, with `SerializedPlaceholder.ipa`,
`BundleMetadata.plist` and the container metadata.
@@ -566,7 +571,7 @@ repaired by installd from the placeholder on the next boot
(`Research/Guest/post_setup_signin_and_appstore.md`). SpringBoard restarts once
at the end when anything was removed and `respring` is not false. The result
is `{results: [{bundle_id, status, removed, container, app, backup,
-backup_method, unregistered, error?}], removed, failed, backup_directory, respring}`.
+backup_method, unregistered, unregister_attempts?, error?}], removed, failed, backup_directory, respring}`.
`status` is `removed`, `absent` (not installed: a no-op that succeeds; a
removal an earlier call left half done, with its backup in place, is finished
instead), `unregistered_stale` (LaunchServices listed a container that is
diff --git a/VPhoneDaemon/Daemon/GuestAPI+SystemApps.swift b/VPhoneDaemon/Daemon/GuestAPI+SystemApps.swift
index 20ef2d26..552b1a11 100644
--- a/VPhoneDaemon/Daemon/GuestAPI+SystemApps.swift
+++ b/VPhoneDaemon/Daemon/GuestAPI+SystemApps.swift
@@ -92,7 +92,7 @@ extension GuestAPI {
guard try bundleContainerExists(location) else {
// LaunchServices lists a bundle whose container is gone:
// dropping the record is all that is left to do.
- let unregistered = try unregisterApp(bundlePath, force: true)
+ let unregistered = try unregisterSystemApp(bundlePath)
result["unregistered"] = unregistered["unregistered"] as? Bool ?? false
result["status"] = "unregistered_stale"
result["removed"] = true
@@ -108,8 +108,11 @@ extension GuestAPI {
result["backup_method"] = made.method
}
do {
- let unregistered = try unregisterApp(bundlePath, force: true)
+ let unregistered = try unregisterSystemApp(bundlePath)
result["unregistered"] = unregistered["unregistered"] as? Bool ?? false
+ if let attempts = unregistered["attempts"] as? Int, attempts > 1 {
+ result["unregister_attempts"] = attempts
+ }
} catch {
if backup {
discardBackup(id)
@@ -451,6 +454,49 @@ extension GuestAPI {
// MARK: - Helpers
+ /// Unregisters the app at `path` and waits for LaunchServices to drop its
+ /// record, unregistering once more if it does not
+ /// (`GuestAppUnregistration`). IcliKit's `unregisterApp` looks at the
+ /// record straight away, and its "still lists the app" is not the last
+ /// word. Throws when the app is still listed after the last attempt.
+ private static func unregisterSystemApp(_ path: String) throws -> [String: Any] {
+ var attempt = 1
+ while true {
+ var result: [String: Any] = [:]
+ var failure: Error?
+ do {
+ result = try unregisterApp(path, force: true)
+ } catch {
+ failure = error
+ }
+ let start = Date()
+ polling: while true {
+ let registered = try appRegistration(path)["registered"] as? Bool == true
+ switch GuestAppUnregistration.next(registered: registered, attempt: attempt, waited: Date().timeIntervalSince(start)) {
+ case .done:
+ if failure != nil || attempt > 1 {
+ // Gone, though not when IcliKit looked, or gone
+ // between the last look and the retry.
+ result = ["unregistered": true, "path": path]
+ }
+ result["attempts"] = attempt
+ return result
+ case .wait:
+ Thread.sleep(forTimeInterval: GuestAppUnregistration.pollInterval)
+ case .retry:
+ attempt += 1
+ break polling
+ case .fail:
+ let reason = failure.map(describe) ?? "LaunchServices still lists \(path) after unregistration"
+ throw GuestAPIError.operationFailed(
+ "\(reason) (unregistered \(attempt) times, still listed "
+ + "\(GuestAppUnregistration.settleTimeout) s after the last)",
+ )
+ }
+ }
+ }
+ }
+
/// The live LaunchServices record for `id`, never a cached one.
private static func installedApp(_ id: String) throws -> [String: Any]? {
let apps = try listApps()["apps"] as? [[String: Any]] ?? []
diff --git a/VPhoneDaemon/Daemon/GuestSystemAppPolicy.swift b/VPhoneDaemon/Daemon/GuestSystemAppPolicy.swift
index 84659e70..f044c478 100644
--- a/VPhoneDaemon/Daemon/GuestSystemAppPolicy.swift
+++ b/VPhoneDaemon/Daemon/GuestSystemAppPolicy.swift
@@ -218,3 +218,40 @@ struct GuestSystemAppManifest: Codable, Equatable {
return manifest
}
}
+
+// MARK: - Unregistration
+
+/// LaunchServices can still list an app for a moment after
+/// `icli_unregister_app` returned. IcliKit's `unregisterApp` checks the
+/// record at once and then throws "LaunchServices still lists the app after
+/// unregistration": Find My, once in two template setup boots on 27.0
+/// (2026-10-08), which left a template keyed by nine removed apps instead of
+/// ten. `apps.remove_system` therefore polls the record for up to
+/// `settleTimeout` before it believes that, unregisters once more if the app
+/// is still listed, polls again, and only then fails the app.
+enum GuestAppUnregistration {
+ /// How long a record may take to go after one unregistration.
+ static let settleTimeout: TimeInterval = 2.5
+ static let pollInterval: TimeInterval = 0.1
+ /// Unregistrations before the app is failed: the first and one retry.
+ static let attempts = 2
+
+ enum Next: Equatable {
+ /// LaunchServices no longer lists the app.
+ case done
+ /// Still listed; look again after `pollInterval`.
+ case wait
+ /// Still listed after `settleTimeout`; unregister it again.
+ case retry
+ /// Still listed after the last attempt.
+ case fail
+ }
+
+ /// What to do after one look at the record. `attempt` counts
+ /// unregistrations from 1; `waited` is the time since the latest.
+ static func next(registered: Bool, attempt: Int, waited: TimeInterval) -> Next {
+ guard registered else { return .done }
+ guard waited >= settleTimeout else { return .wait }
+ return attempt < attempts ? .retry : .fail
+ }
+}
diff --git a/VPhoneDaemon/Tests/SystemMaintenanceTests.swift b/VPhoneDaemon/Tests/SystemMaintenanceTests.swift
index a61f997c..c6983ec6 100644
--- a/VPhoneDaemon/Tests/SystemMaintenanceTests.swift
+++ b/VPhoneDaemon/Tests/SystemMaintenanceTests.swift
@@ -38,6 +38,7 @@ enum SystemMaintenanceTests {
backupNames()
backupSelection()
manifests()
+ unregistration()
snapshotSelection()
snapshotErrno()
print("\(checks - failures)/\(checks) checks passed")
@@ -115,6 +116,57 @@ enum SystemMaintenanceTests {
}
}
+ // MARK: - Unregistration
+
+ /// A record LaunchServices still lists right after unregistration is
+ /// looked at again for 2.5 s, unregistered once more, looked at for
+ /// another 2.5 s, and only then failed.
+ static func unregistration() {
+ typealias U = GuestAppUnregistration
+ check(U.settleTimeout >= 2 && U.settleTimeout <= 3, "waits 2 to 3 s for the record to go")
+ check(U.pollInterval > 0 && U.pollInterval <= 0.25, "looks again at a short interval")
+ check(U.attempts == 2, "one retry")
+ check(U.next(registered: false, attempt: 1, waited: 0) == .done, "gone at once")
+ check(U.next(registered: false, attempt: 1, waited: 1.2) == .done, "gone while waiting")
+ check(U.next(registered: false, attempt: 2, waited: 9) == .done, "gone after the retry, however late it is seen")
+ check(U.next(registered: true, attempt: 1, waited: 0) == .wait, "still listed right after: wait")
+ check(U.next(registered: true, attempt: 1, waited: U.settleTimeout - 0.1) == .wait, "still listed before the timeout: wait")
+ check(U.next(registered: true, attempt: 1, waited: U.settleTimeout) == .retry, "still listed at the timeout: unregister again")
+ check(U.next(registered: true, attempt: 2, waited: 0.5) == .wait, "the retry waits as well")
+ check(U.next(registered: true, attempt: 2, waited: U.settleTimeout) == .fail, "still listed after the retry: fail")
+ check(U.next(registered: true, attempt: 3, waited: U.settleTimeout) == .fail, "never more than the attempts")
+
+ // The decision loop the daemon runs, against a record that goes on
+ // the given look (counting every look across attempts).
+ func simulate(goneOnLook gone: Int?) -> (outcome: U.Next, attempts: Int, looks: Int) {
+ var attempt = 1
+ var looks = 0
+ var waited: TimeInterval = 0
+ while true {
+ looks += 1
+ let registered = gone.map { looks < $0 } ?? true
+ let next = U.next(registered: registered, attempt: attempt, waited: waited)
+ switch next {
+ case .done, .fail: return (next, attempt, looks)
+ case .wait: waited += U.pollInterval
+ case .retry:
+ attempt += 1
+ waited = 0
+ }
+ }
+ }
+ let immediate = simulate(goneOnLook: 1)
+ check(immediate.outcome == .done && immediate.attempts == 1 && immediate.looks == 1, "a clean unregistration looks once")
+ let late = simulate(goneOnLook: 5)
+ check(late.outcome == .done && late.attempts == 1, "a record that goes within the wait needs no retry")
+ let perLook = Int((U.settleTimeout / U.pollInterval).rounded(.up)) + 1
+ let retried = simulate(goneOnLook: perLook + 3)
+ check(retried.outcome == .done && retried.attempts == 2, "a record that outlasts the wait is unregistered again")
+ let stuck = simulate(goneOnLook: nil)
+ check(stuck.outcome == .fail && stuck.attempts == 2, "a record that never goes fails after the retry")
+ check(stuck.looks <= 2 * (perLook + 1), "and the looks are bounded")
+ }
+
// MARK: - Backup names
static func backupNames() {
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneMachineTemplateKeys.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneMachineTemplateKeys.swift
index d6bf6b5f..b3dd3a10 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneMachineTemplateKeys.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneMachineTemplateKeys.swift
@@ -1,6 +1,7 @@
import ArgumentParser
import FirmwarePatcher
import Foundation
+import VPhoneArchiveKit
import VPhoneCoreKit
import VPhonePatchKit
@@ -98,6 +99,55 @@ enum VPhoneMachineTemplateKeys {
)
}
+ // MARK: Builds of a request
+
+ /// The device and builds of the two IPSWs when both are local files or
+ /// already in the IPSW cache, read without downloading; nil otherwise. A
+ /// local path that no longer exists counts as not here.
+ static func localBuilds(
+ iPhoneSource: String,
+ cloudOSSource: String,
+ cache: URL,
+ device: String?,
+ ) throws -> VPhoneMachineTemplateBuilds? {
+ guard let phone = try VPhoneIPSWCache.localArchive(iPhoneSource, in: cache),
+ let cloud = try VPhoneIPSWCache.localArchive(cloudOSSource, in: cache)
+ else {
+ return nil
+ }
+ 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).")
+ }
+ return VPhoneMachineTemplateBuilds(
+ device: guest.productType,
+ ios: .init(version: phone.version, build: phone.build),
+ cloudOS: .init(version: cloud.version, build: cloud.build),
+ origin: .ipsw,
+ )
+ }
+
+ /// The builds a request names without downloading: from the IPSWs when
+ /// they are here, else from a template recorded with the same sources
+ /// (``VPhoneMachineTemplates/resolveBuilds(sources:device:in:local:)``).
+ /// Nil when only a download would tell.
+ static func resolveBuilds(
+ iPhoneSource: String,
+ cloudOSSource: String,
+ cache: URL,
+ device: String?,
+ in library: VPhoneLibrary,
+ ) throws -> VPhoneMachineTemplateBuilds? {
+ try VPhoneMachineTemplates.resolveBuilds(
+ sources: VPhoneMachineTemplateSources(iPhone: iPhoneSource, cloudOS: cloudOSSource),
+ device: device,
+ in: library,
+ ) {
+ try localBuilds(iPhoneSource: iPhoneSource, cloudOSSource: cloudOSSource, cache: cache, device: device)
+ }
+ }
+
// MARK: Recorded machine
/// What a machine's records say about it, for adopting it.
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreator.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreator.swift
index b13a0c05..8048a330 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreator.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreator.swift
@@ -249,6 +249,37 @@ public struct VPhoneVirtualMachineCreator {
guard slimming.problems.isEmpty else {
throw ValidationError("Cannot build this template: \(slimming.problems.joined(separator: "; ")). Pass --trim none.")
}
+ // Resolved as vm template find resolves it: from the IPSWs when they
+ // are local or cached, else from a template recorded with the same
+ // sources. Nothing is downloaded unless no template matches and one
+ // has to be built.
+ let builds = try VPhoneMachineTemplateKeys.resolveBuilds(
+ iPhoneSource: phoneSource,
+ cloudOSSource: cloudSource,
+ cache: options.ipswCacheDirectory,
+ device: options.device,
+ in: library,
+ )
+ if let builds {
+ let key = try VPhoneMachineTemplateKeys.key(
+ device: builds.device,
+ ios: builds.ios,
+ cloudOS: builds.cloudOS,
+ preset: options.patchPreset,
+ diskSizeGB: options.diskSizeGB,
+ slimming: slimming,
+ )
+ if let found = try VPhoneMachineTemplates.template(for: key, in: library) {
+ print("[*] Template key \(key.identifier): \(key.summary)")
+ if builds.origin == .template, let source = builds.template {
+ print("[*] Builds from template \(source), recorded with the same IPSW sources; nothing downloaded")
+ }
+ return try requireCurrent(found)
+ }
+ }
+
+ // A build: it needs the IPSWs, so they are downloaded now when they
+ // are not here, and the key is taken from them.
let sources = try VPhoneFirmwarePreparer.resolveSources(
iPhoneSource: phoneSource,
cloudOSSource: cloudSource,
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineTemplateCommand.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineTemplateCommand.swift
index e0b2609f..0ba58b00 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineTemplateCommand.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineTemplateCommand.swift
@@ -301,44 +301,23 @@ struct VPhoneVirtualMachineTemplateFindCommand: ParsableCommand {
}
}
- 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? {
+ private func resolveBuilds(in library: VPhoneLibrary, report: inout VPhoneMachineTemplateFindReport) throws -> VPhoneMachineTemplateBuilds? {
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
+ guard let builds = try VPhoneMachineTemplateKeys.resolveBuilds(
+ iPhoneSource: iphoneSource,
+ cloudOSSource: cloudosSource,
+ cache: cache,
+ device: device,
+ in: library,
+ ) else {
+ report.reason = VPhoneMachineTemplates.unresolvedBuildsReason
+ return nil
+ }
+ report.resolvedBy = builds.origin.rawValue
+ return builds
}
}
@@ -363,9 +342,15 @@ struct VPhoneVirtualMachineTemplateSetupCommand: ParsableCommand {
tier vm template trim recorded. Then vm template adopt <name> freezes it with what this \
recorded. An app that will not go is reported and left out of the template's key.
+ --strict: anything short of the requested slimming, an app vphoned does not remove above \
+ all, fails the setup boot and records nothing, instead of being reported and left out of \
+ the key. Use it when the machine is to be adopted under a key worked out beforehand \
+ (vm template find, then vm template adopt --expect), as Launchpad does.
+
A .building-… name from vm template list: a vm create whose template build failed. Its \
- key fixes the slimming, so switches that disagree are refused, every app must go, and on \
- success the template is frozen and vm create uses it.
+ key fixes the slimming, so switches that disagree are refused, every app must go (strict \
+ whether --strict is given or not), and on success the template is frozen and vm create \
+ uses it.
Slimming: --slim off skips the app removal and the service profile; the setup boot still \
skips Setup and deletes the snapshot, so a trim recorded before it is kept.
@@ -376,6 +361,8 @@ struct VPhoneVirtualMachineTemplateSetupCommand: ParsableCommand {
@Argument(help: "VM name, or a .building-… name from vm template list") var target: String
@OptionGroup var slimming: VPhoneTemplateSlimmingOptions
@Flag(help: "Show the VM window while it boots") var window = false
+ @Flag(help: "Fail instead of warning when the setup boot falls short of the requested slimming (an app not removed)")
+ var strict = false
@Flag(name: .customShort("v"), help: "Increase verbosity: -vvv internal trace")
var verboseCount: Int
@@ -432,7 +419,7 @@ struct VPhoneVirtualMachineTemplateSetupCommand: ParsableCommand {
}
try VPhoneTemplateSetupRun.run(
bundleURL: bundle.url,
- plan: VPhoneTemplateSetupPlan(slimming: wanted, requiresEveryApp: false),
+ plan: VPhoneTemplateSetupPlan(slimming: wanted, requiresEveryApp: strict),
launcher: VPhoneHostPreflight.check(),
resources: resources,
headless: !window,
@@ -505,6 +492,14 @@ struct VPhoneVirtualMachineTemplateAdoptCommand: ParsableCommand {
--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.
+
+ --expect <id> refuses, and leaves the machine where it is, unless the key its records \
+ give has that identifier: the one vm template find printed for the request the machine \
+ was built for. A template under another identifier would never be found by that request. \
+ The refusal names the fields that differ when the expected key is known (a template or \
+ build in the library has it, or it differs only in slimming, as when an app was not \
+ removed); with --json it is also printed to stdout as an object with adopted false, \
+ the computed id and the expected one.
""",
)
@@ -513,12 +508,17 @@ struct VPhoneVirtualMachineTemplateAdoptCommand: ParsableCommand {
@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?
+ @Option(help: ArgumentHelp("Refuse unless the template's identifier is this one (from vm template find)", valueName: "id"))
+ var expect: 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.")
}
+ if let expect, !VPhoneMachineTemplateKey.isIdentifier(expect.lowercased()) {
+ throw ValidationError("--expect takes a template identifier of \(VPhoneMachineTemplateKey.identifierLength) hex digits, not \(expect).")
+ }
}
func run() throws {
@@ -531,6 +531,14 @@ struct VPhoneVirtualMachineTemplateAdoptCommand: ParsableCommand {
let previous = try VPhoneMachineTemplates.readRecord(inBundle: bundle.url)
let steps = previous?.steps ?? VPhoneMachineTemplateSteps()
let recorded = try VPhoneMachineTemplateKeys.recorded(bundle, slimming: steps.slimming)
+ if let expect, recorded.key.identifier != expect.lowercased(),
+ let mismatch = recorded.key.mismatch(expecting: expect, known: knownKeys())
+ {
+ if json {
+ try print(encodeJSON(VPhoneMachineTemplateAdoptRefusal(mismatch, steps: steps)))
+ }
+ throw mismatch
+ }
var problems: [String] = []
let series = VPhoneMachineTemplateKeys.currentSeries
if recorded.key.bundleSeries != series {
@@ -571,6 +579,45 @@ struct VPhoneVirtualMachineTemplateAdoptCommand: ParsableCommand {
print(" \(template.key.summary)")
print("create machines from it with: vphone-cli vm create <name> --template \(template.identifier)")
}
+
+ /// The keys of the library's templates and builds, to name the one an
+ /// `--expect` identifier stands for.
+ private func knownKeys() -> [VPhoneMachineTemplateKey] {
+ guard let listing = try? VPhoneMachineTemplates.list(in: lib.library) else { return [] }
+ let builds = listing.staging.compactMap { staging -> VPhoneMachineTemplateKey? in
+ guard let identifier = staging.identifier else { return nil }
+ let url = staging.url.appendingPathComponent(identifier, isDirectory: true)
+ return (try? VPhoneMachineTemplates.readRecord(inBundle: url))?.key
+ }
+ return listing.templates.map(\.key) + builds
+ }
+}
+
+/// What `adopt --expect <id> --json` prints when it refuses.
+struct VPhoneMachineTemplateAdoptRefusal: Encodable {
+ var adopted = false
+ var error = "unexpected_template"
+ var message: String
+ /// The identifier the machine's records give.
+ var id: String
+ var expected: String
+ var key: VPhoneMachineTemplateKey
+ /// The key `expected` stands for, when known.
+ var expectedKey: VPhoneMachineTemplateKey?
+ var differences: [String]
+ var canonicalDescription: String
+ var steps: VPhoneMachineTemplateSteps
+
+ init(_ mismatch: VPhoneMachineTemplateKeyMismatch, steps: VPhoneMachineTemplateSteps) {
+ message = mismatch.description
+ id = mismatch.identifier
+ expected = mismatch.expected
+ key = mismatch.key
+ expectedKey = mismatch.expectedKey
+ differences = mismatch.differences
+ canonicalDescription = mismatch.key.canonicalDescription
+ self.steps = steps
+ }
}
// MARK: - trim
@@ -682,8 +729,11 @@ struct VPhoneVirtualMachineTemplateDeleteCommand: ParsableCommand {
return
}
}
+ // Who uses it, read before it goes: the note depends on it.
+ let identifier = (try? VPhoneMachineTemplates.template(id, in: library).identifier) ?? id
+ let machines = id.hasPrefix(".building-") ? [] : VPhoneMachineTemplates.usage(in: library)[identifier] ?? []
let removed = try VPhoneMachineTemplates.delete(id, in: library)
print("deleted \(removed.lastPathComponent)")
- print("note: blocks still shared with machines cloned from it are freed only when those machines change or are deleted")
+ print("note: \(VPhoneMachineTemplates.deletionNote(machines: machines))")
}
}
diff --git a/VPhoneKit/VPhoneArchiveKit/Transfer/VPhoneIPSWCache.swift b/VPhoneKit/VPhoneArchiveKit/Transfer/VPhoneIPSWCache.swift
index 242b6f76..5645eda5 100644
--- a/VPhoneKit/VPhoneArchiveKit/Transfer/VPhoneIPSWCache.swift
+++ b/VPhoneKit/VPhoneArchiveKit/Transfer/VPhoneIPSWCache.swift
@@ -117,13 +117,16 @@ 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.
+ /// remote source is not in the cache, or a local one no longer exists
+ /// (the caller then looks elsewhere, such as a template recorded with the
+ /// same source); a local file that exists but is not an IPSW still
+ /// throws. 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))
+ return try inspectIfPresent(URL(fileURLWithPath: source))
}
if scheme == "file" {
- return try inspect(url)
+ return try inspectIfPresent(url)
}
guard scheme == "http" || scheme == "https" else {
throw Error.unsupportedSource(source)
@@ -133,6 +136,13 @@ public enum VPhoneIPSWCache {
return try? inspect(cache)
}
+ /// A local IPSW, or nil when nothing is at its path (a dangling link
+ /// included).
+ private static func inspectIfPresent(_ file: URL) throws -> Archive? {
+ guard FileManager.default.fileExists(atPath: file.path) else { return nil }
+ return try inspect(file)
+ }
+
/// 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/VPhoneArchiveKitTests/IPSWCacheTests.swift b/VPhoneKit/VPhoneArchiveKitTests/IPSWCacheTests.swift
index 600378d8..26090f74 100644
--- a/VPhoneKit/VPhoneArchiveKitTests/IPSWCacheTests.swift
+++ b/VPhoneKit/VPhoneArchiveKitTests/IPSWCacheTests.swift
@@ -165,6 +165,30 @@ struct IPSWCacheTests {
#expect(!FileManager.default.fileExists(atPath: root.appendingPathComponent("cache").path))
}
+ @Test func `a local archive that no longer exists is not here, and an unreadable one still fails`() throws {
+ let root = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+ try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true)
+ defer { try? FileManager.default.removeItem(at: root) }
+ let cache = root.appendingPathComponent("cache")
+ let source = try fixture(in: root)
+ #expect(try VPhoneIPSWCache.localArchive(source.path, in: cache)?.build == "23G90")
+ #expect(try VPhoneIPSWCache.localArchive(source.absoluteString, in: cache)?.build == "23G90")
+
+ // Deleted since: nil, so vm template find falls back to the sources
+ // a template recorded instead of failing (B4).
+ let missing = root.appendingPathComponent("gone/iPhone.ipsw")
+ #expect(try VPhoneIPSWCache.localArchive(missing.path, in: cache) == nil)
+ #expect(try VPhoneIPSWCache.localArchive(missing.absoluteString, in: cache) == nil)
+ // A remote source that is not cached: nil, nothing downloaded.
+ #expect(try VPhoneIPSWCache.localArchive("https://example.invalid/iPhone.ipsw", in: cache) == nil)
+ #expect(!FileManager.default.fileExists(atPath: cache.path))
+
+ // Something at the path that is not an IPSW is still an error.
+ let junk = root.appendingPathComponent("junk.ipsw")
+ try Data("not a zip".utf8).write(to: junk)
+ #expect(throws: (any Error).self) { try VPhoneIPSWCache.localArchive(junk.path, in: cache) }
+ }
+
@Test func `download replaces invalid cache only after validation`() async throws {
let root = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true)
diff --git a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplateKey.swift b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplateKey.swift
index 9801fd99..c8310ce7 100644
--- a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplateKey.swift
+++ b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplateKey.swift
@@ -321,6 +321,130 @@ public struct VPhoneMachineTemplateRequest: Equatable, Sendable {
}
}
+// MARK: - Expected identifier
+
+/// `vm template adopt --expect <id>` refused: the key a machine's records
+/// give hashes to another identifier than the one the caller worked out for
+/// its request (`vm template find`). Adopting it anyway would file the
+/// template where no later request with the same options looks, and every
+/// such request would build another one.
+public struct VPhoneMachineTemplateKeyMismatch: Error, CustomStringConvertible, LocalizedError, Sendable {
+ public var expected: String
+ /// The key the machine's records give.
+ public var key: VPhoneMachineTemplateKey
+ /// The key that hashes to `expected`, when it could be recovered (see
+ /// ``VPhoneMachineTemplateKey/mismatch(expecting:known:)``).
+ public var expectedKey: VPhoneMachineTemplateKey?
+ /// Per field, the expected value and the machine's (`expected → machine`);
+ /// empty when the expected key is not known.
+ public var differences: [String]
+
+ public var identifier: String {
+ key.identifier
+ }
+
+ public var description: String {
+ let head = "The machine's records give template \(identifier), not the expected \(expected)"
+ guard expectedKey != nil else {
+ return head + ". The key behind \(expected) is not known here; compare this machine's key with the key "
+ + "vm template find --json prints: " + key.canonicalDescription.split(separator: "\n").joined(separator: "; ") + "."
+ }
+ return head + ": " + differences.joined(separator: "; ") + "."
+ }
+
+ public var errorDescription: String? {
+ description
+ }
+}
+
+public extension VPhoneMachineTemplateKey {
+ /// Nil when this key hashes to `expected`. Otherwise why not: the key
+ /// behind `expected` is looked for among `known` (the library's
+ /// templates and builds), then among the keys that differ from this one
+ /// only in slimming (the trim tier, the setup boot, the service profile
+ /// and groups, and which of the default apps were removed), where a
+ /// setup boot that left an app behind lands. A hash cannot be undone, so
+ /// a key that differs elsewhere, and is not known, stays unknown.
+ func mismatch(expecting expected: String, known: [VPhoneMachineTemplateKey] = []) -> VPhoneMachineTemplateKeyMismatch? {
+ let expected = expected.lowercased()
+ guard identifier != expected else { return nil }
+ let found = known.first { $0.identifier == expected } ?? slimmingVariant(identifiedBy: expected)
+ return VPhoneMachineTemplateKeyMismatch(
+ expected: expected,
+ key: self,
+ expectedKey: found,
+ differences: found.map { $0.mismatchLines(against: self) } ?? [],
+ )
+ }
+
+ /// The key with this one's fields but another slimming whose identifier
+ /// is `identifier`, or nil. At most a few tens of thousands of hashes,
+ /// this key's own values tried first.
+ func slimmingVariant(identifiedBy identifier: String) -> VPhoneMachineTemplateKey? {
+ func unique<T: Hashable>(_ values: [T]) -> [T] {
+ var seen = Set<T>()
+ return values.filter { seen.insert($0).inserted }
+ }
+ let tiers = unique([
+ slimming.trimTier,
+ "none",
+ VPhoneTemplateSlimmingRequest.defaultTrimTier,
+ (try? VPhoneSystemTrimSpec(tier: .conservative).keyValue) ?? "none",
+ ])
+ let setups = [slimming.setupBoot, !slimming.setupBoot]
+ let profiles = unique([slimming.serviceProfile] + VPhoneTemplateSlimmingRequest.serviceProfiles)
+ let groups = unique([slimming.serviceGroups, [], [VPhoneTemplateSlimmingRequest.accountsGroup]])
+ let apps = unique(slimming.removedApps + VPhoneTemplateSlimmingRequest.defaultRemovedApps)
+ // Every subset of the apps, this key's own first; a list too long to
+ // enumerate is tried as it is, as the default, and as none.
+ let appSets: [[String]] = apps.count <= 12
+ ? [slimming.removedApps] + (0 ..< (1 << apps.count)).map { mask in
+ apps.indices.filter { mask & (1 << $0) != 0 }.map { apps[$0] }
+ }
+ : [slimming.removedApps, VPhoneTemplateSlimmingRequest.defaultRemovedApps, []]
+ var candidate = self
+ for setup in setups {
+ for tier in tiers {
+ for profile in profiles {
+ for group in groups {
+ for removed in appSets {
+ candidate.slimming = VPhoneMachineTemplateSlimming(
+ trimTier: tier,
+ setupBoot: setup,
+ serviceProfile: profile,
+ serviceGroups: group,
+ removedApps: removed,
+ )
+ if candidate.identifier == identifier {
+ return candidate
+ }
+ }
+ }
+ }
+ }
+ }
+ return nil
+ }
+
+ /// ``differences(from:)`` from this (expected) key to `other`, with the
+ /// removed apps as the apps one list has and the other lacks.
+ private func mismatchLines(against other: VPhoneMachineTemplateKey) -> [String] {
+ var lines = differences(from: other).filter { !$0.hasPrefix("removed apps:") }
+ let mine = Set(slimming.removedApps)
+ let theirs = Set(other.slimming.removedApps)
+ let notRemoved = mine.subtracting(theirs).sorted()
+ let extra = theirs.subtracting(mine).sorted()
+ if !notRemoved.isEmpty {
+ lines.append("removed apps: expected \(notRemoved.joined(separator: ", ")) removed too, the machine still has "
+ + (notRemoved.count == 1 ? "it" : "them"))
+ }
+ if !extra.isEmpty {
+ lines.append("removed apps: the machine also lacks \(extra.joined(separator: ", ")), which was not expected")
+ }
+ return lines
+ }
+}
+
// MARK: - Bundle version
public enum VPhoneBundleVersion {
diff --git a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplates.swift b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplates.swift
index ceaf804e..09cd37da 100644
--- a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplates.swift
+++ b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplates.swift
@@ -127,6 +127,39 @@ public struct VPhoneMachineTemplateSources: Codable, Equatable, Sendable {
}
}
+/// The guest device and the two OS builds a request's key starts from, and
+/// where they came from.
+public struct VPhoneMachineTemplateBuilds: Equatable, Sendable {
+ public enum Origin: String, Sendable {
+ /// Read from the IPSWs: local files, or remote ones already cached.
+ case ipsw
+ /// Taken from the key of a template whose record names the same two
+ /// sources (``VPhoneMachineTemplates/templates(builtFrom:device:in:)``).
+ case template
+ }
+
+ public var device: String
+ public var ios: VPhoneRestoreInfo.OSVersion
+ public var cloudOS: VPhoneRestoreInfo.OSVersion
+ public var origin: Origin
+ /// The template the builds were taken from, for ``Origin/template``.
+ public var template: String?
+
+ public init(
+ device: String,
+ ios: VPhoneRestoreInfo.OSVersion,
+ cloudOS: VPhoneRestoreInfo.OSVersion,
+ origin: Origin,
+ template: String? = nil,
+ ) {
+ self.device = device
+ self.ios = ios
+ self.cloudOS = cloudOS
+ self.origin = origin
+ self.template = template
+ }
+}
+
// MARK: - Record
/// `Template.plist`, in the template's machine folder.
@@ -491,6 +524,39 @@ public enum VPhoneMachineTemplates {
.sorted { $0.record.created > $1.record.created }
}
+ /// Why ``resolveBuilds(sources:device:in:local:)`` found nothing.
+ public static let unresolvedBuildsReason = "the IPSWs are not downloaded and no template records these sources"
+
+ /// The builds a request names, without downloading anything: first
+ /// `local`, which reads the two IPSWs when both are local files or in
+ /// the IPSW cache and returns nil otherwise (a local path that no longer
+ /// exists included); then the newest template recorded with the same
+ /// two sources (and `device`, when one is named). Nil when neither has
+ /// them: only a download would tell. `vm template find` and `vm create`
+ /// both resolve this way, so a create clones the template find reports
+ /// and downloads only for a build.
+ public static func resolveBuilds(
+ sources: VPhoneMachineTemplateSources,
+ device: String?,
+ in library: VPhoneLibrary,
+ local: () throws -> VPhoneMachineTemplateBuilds?,
+ ) throws -> VPhoneMachineTemplateBuilds? {
+ if let builds = try local() {
+ return builds
+ }
+ guard let template = templates(builtFrom: sources, device: device, in: library).first else {
+ return nil
+ }
+ let key = template.key
+ return VPhoneMachineTemplateBuilds(
+ device: key.device,
+ ios: .init(version: key.iOSVersion, build: key.iOSBuild),
+ cloudOS: .init(version: key.cloudOSVersion, build: key.cloudOSBuild),
+ origin: .template,
+ template: template.identifier,
+ )
+ }
+
/// 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)
@@ -820,6 +886,19 @@ public enum VPhoneMachineTemplates {
// MARK: Delete
+ /// What `vm template delete` says about the space it freed: blocks a
+ /// machine cloned from the template still shares stay allocated until
+ /// that machine changes or is deleted; with no such machine, the
+ /// template's space is free at once. `machines` is what
+ /// ``usage(in:)`` listed for the template before it was deleted.
+ public static func deletionNote(machines: [String]) -> String {
+ guard !machines.isEmpty else {
+ return "no machine was cloned from it, so its space is free now"
+ }
+ return "\(machines.count) machine(s) cloned from it (\(machines.joined(separator: ", "))) still share its blocks; "
+ + "those blocks are freed only when the machines change them or are deleted"
+ }
+
/// Removes a frozen template, by identifier or unique prefix, or a staging
/// folder by its `.building-…` name that no build holds. Returns what was
/// removed. Machines cloned from the template keep working: they share
diff --git a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneTemplateSetupBoot.swift b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneTemplateSetupBoot.swift
index a7f7ec82..5bfaa8af 100644
--- a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneTemplateSetupBoot.swift
+++ b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneTemplateSetupBoot.swift
@@ -124,9 +124,12 @@ public struct VPhoneTemplateSetupPlan: Equatable, Sendable {
public var serviceProfile: String
public var serviceGroups: [String]
public var removedApps: [String]
- /// Whether an app vphoned does not remove fails the setup boot. A template
- /// being built has its key, and with it the apps it promises, fixed; a
- /// machine to be adopted afterwards gets a key from what was done.
+ /// Strict: whether falling short of this plan fails the setup boot, an
+ /// app vphoned does not remove above all, instead of being reported and
+ /// left out of the recorded steps. A template being built has its key,
+ /// and with it the apps it promises, fixed; so does a machine Launchpad
+ /// (`vm template setup --strict`) adopts under the key `vm template find`
+ /// gave. Otherwise a machine to be adopted gets a key from what was done.
public var requiresEveryApp: Bool
/// Clear the device name `vphone-vm` pinned during this boot, so a clone
/// does not show the template's name before its own VM pins its name.
@@ -227,6 +230,27 @@ public struct VPhoneTemplateSetupOutcome: Equatable, Sendable {
apps.filter(\.isGone).map(\.bundleID).sorted()
}
+ /// Where the slimming done so far falls short of `plan`: an app not
+ /// removed, another service profile or groups. What a strict setup boot
+ /// refuses once the profile is applied.
+ public func deviations(from plan: VPhoneTemplateSetupPlan) -> [String] {
+ var lines: [String] = []
+ let kept = Set(plan.removedApps).subtracting(removedApps).sorted()
+ if !kept.isEmpty {
+ let reasons = kept.map { id in
+ apps.first { $0.bundleID == id }.map { "\(id) (\($0.error ?? $0.status))" } ?? id
+ }
+ lines.append("not removed: \(reasons.joined(separator: ", "))")
+ }
+ if serviceProfile != plan.serviceProfile {
+ lines.append("service profile \(serviceProfile), not \(plan.serviceProfile)")
+ }
+ if serviceGroups.sorted() != plan.serviceGroups.sorted() {
+ lines.append("service groups \(serviceGroups.sorted().joined(separator: ",")), not \(plan.serviceGroups.sorted().joined(separator: ","))")
+ }
+ return lines
+ }
+
/// Every step ran and the VM shut down cleanly.
public var isComplete: Bool {
snapshotsGone && setupSkipped && settled && verified && stoppedCleanly
@@ -322,7 +346,10 @@ public final class VPhoneTemplateSetupBoot {
try step(.skipSetup) { try skipSetup() }
try step(.settle) { try settle() }
try step(.removeApps) { try removeApps() }
- try step(.serviceProfile) { try applyServiceProfile() }
+ try step(.serviceProfile) {
+ try applyServiceProfile()
+ try requirePlan()
+ }
try step(.reboot) { try reboot() }
try step(.verify) { try verify() }
try step(.deviceName) { clearDeviceName() }
@@ -493,6 +520,16 @@ public final class VPhoneTemplateSetupBoot {
+ "\(outcome.servicesOwned) services owned, \(strings(applied["disabled"]).count) disabled now")
}
+ /// A strict setup boot stops here, before the reboot, when what was done
+ /// falls short of the plan.
+ private func requirePlan() throws {
+ guard plan.requiresEveryApp else { return }
+ let deviations = outcome.deviations(from: plan)
+ guard deviations.isEmpty else {
+ throw StepError("strict: the setup boot fell short of the requested slimming: \(deviations.joined(separator: "; "))")
+ }
+ }
+
private func requireApplied(_ result: [String: Any]) throws {
let failed = (result["failed"] as? [[String: Any]] ?? []).map { row in
"\(row["label"] as? String ?? "?") (\(row["action"] as? String ?? "?"): \(row["error"] as? String ?? "?"))"
diff --git a/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplateKeyTests.swift b/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplateKeyTests.swift
index 2bb23b2d..98bc3d7f 100644
--- a/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplateKeyTests.swift
+++ b/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplateKeyTests.swift
@@ -178,4 +178,68 @@ struct MachineTemplateKeyTests {
#expect(text.contains("<key>\(field)</key>"), "\(field)")
}
}
+
+ // MARK: - Expected identifier (adopt --expect)
+
+ @Test func `the expected identifier passes, in either case`() {
+ let key = Self.key(slimming: VPhoneTemplateSlimmingRequest.defaultSlimming)
+ #expect(key.mismatch(expecting: key.identifier) == nil)
+ #expect(key.mismatch(expecting: key.identifier.uppercased()) == nil)
+ }
+
+ @Test func `an app the setup boot left behind is named as the difference`() throws {
+ // B1: find keyed the request by ten removed apps; the setup boot left
+ // Find My, so the machine's records give nine.
+ let requested = Self.key(slimming: VPhoneTemplateSlimmingRequest.defaultSlimming)
+ var adopted = requested
+ adopted.slimming.removedApps.removeAll { $0 == "com.apple.findmy" }
+ let mismatch = try #require(adopted.mismatch(expecting: requested.identifier))
+ #expect(mismatch.identifier == adopted.identifier)
+ #expect(mismatch.expected == requested.identifier)
+ #expect(mismatch.expectedKey == requested)
+ #expect(mismatch.differences == ["removed apps: expected com.apple.findmy removed too, the machine still has it"])
+ #expect(mismatch.description.contains(adopted.identifier))
+ #expect(mismatch.description.contains(requested.identifier))
+ #expect(mismatch.description.contains("com.apple.findmy"))
+ }
+
+ @Test func `other slimming differences are recovered and named`() throws {
+ let requested = Self.key(slimming: VPhoneMachineTemplateSlimming(
+ trimTier: VPhoneTemplateSlimmingRequest.defaultTrimTier,
+ setupBoot: true,
+ serviceProfile: "trimmed",
+ serviceGroups: ["accounts"],
+ removedApps: ["com.apple.news", "com.apple.tv"],
+ ))
+ let adopted = Self.key(slimming: VPhoneMachineTemplateSlimming(
+ trimTier: "none",
+ setupBoot: true,
+ serviceProfile: "none",
+ removedApps: ["com.apple.news", "com.apple.Home"],
+ ))
+ let mismatch = try #require(adopted.mismatch(expecting: requested.identifier))
+ #expect(mismatch.expectedKey == requested)
+ #expect(mismatch.differences.contains("trim tier: \(VPhoneTemplateSlimmingRequest.defaultTrimTier) → none"))
+ #expect(mismatch.differences.contains("service profile: trimmed → none"))
+ #expect(mismatch.differences.contains("service groups: accounts → none"))
+ #expect(mismatch.differences.contains("removed apps: expected com.apple.tv removed too, the machine still has it"))
+ #expect(mismatch.differences.contains("removed apps: the machine also lacks com.apple.Home, which was not expected"))
+ }
+
+ @Test func `a known key outside slimming is named, an unknown one is described`() throws {
+ let adopted = Self.key(series: "2.9")
+ let elsewhere = Self.key(series: "2.8", disk: 128)
+ let known = try #require(adopted.mismatch(expecting: elsewhere.identifier, known: [Self.key(device: "iPad16,1"), elsewhere]))
+ #expect(known.expectedKey == elsewhere)
+ #expect(known.differences == ["bundle series: 2.8 → 2.9", "disk size: 128 GB → 64 GB"])
+
+ // Not in the library and not a slimming variant: the hash cannot be
+ // undone, so the machine's own key is spelled out to compare.
+ let unknown = try #require(adopted.mismatch(expecting: elsewhere.identifier))
+ #expect(unknown.expectedKey == nil)
+ #expect(unknown.differences.isEmpty)
+ #expect(unknown.description.contains("is not known here"))
+ #expect(unknown.description.contains("series=2.9"))
+ #expect(unknown.description.contains("removed-apps="))
+ }
}
diff --git a/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplatesTests.swift b/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplatesTests.swift
index 96b24323..1364780d 100644
--- a/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplatesTests.swift
+++ b/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplatesTests.swift
@@ -611,4 +611,62 @@ struct MachineTemplatesTests {
let elsewhere = VPhoneMachineTemplateSources(iPhone: "https://example.invalid/a.ipsw", cloudOS: "https://example.invalid/other")
#expect(VPhoneMachineTemplates.templates(builtFrom: elsewhere, in: fixture.library).isEmpty)
}
+
+ @Test func `builds come from the IPSWs first, then from a template with the same sources, and never from a download`() throws {
+ let fixture = try makeFixture()
+ defer { fixture.cleanUp() }
+ let sources = VPhoneMachineTemplateSources(iPhone: "https://example.invalid/a.ipsw", cloudOS: "https://example.invalid/c")
+ let fromIPSW = VPhoneMachineTemplateBuilds(
+ device: "iPhone17,3",
+ ios: .init(version: "27.0.1", build: "24A446"),
+ cloudOS: .init(version: "26.4", build: "23E5207q"),
+ origin: .ipsw,
+ )
+
+ // Nothing local, no template: unresolved, so only a build (which
+ // downloads) can tell; the local reader is asked once.
+ var looks = 0
+ let none = try VPhoneMachineTemplates.resolveBuilds(sources: sources, device: nil, in: fixture.library) {
+ looks += 1
+ return nil
+ }
+ #expect(none == nil)
+ #expect(looks == 1)
+
+ try makeMachine("src", in: fixture)
+ var built = record()
+ built.sources = sources
+ let template = try VPhoneMachineTemplates.adopt(machineNamed: "src", in: fixture.library, record: built)
+
+ // The IPSWs are here: they win over the template's record.
+ let local = try VPhoneMachineTemplates.resolveBuilds(sources: sources, device: nil, in: fixture.library) { fromIPSW }
+ #expect(local == fromIPSW)
+
+ // Not here (deleted, or a local path that no longer exists): the
+ // template recorded with the same sources gives the builds.
+ let recorded = try #require(try VPhoneMachineTemplates.resolveBuilds(sources: sources, device: nil, in: fixture.library) { nil })
+ #expect(recorded.origin == .template)
+ #expect(recorded.template == template.identifier)
+ #expect(recorded.device == template.key.device)
+ #expect(recorded.ios == .init(version: template.key.iOSVersion, build: template.key.iOSBuild))
+ #expect(recorded.cloudOS == .init(version: template.key.cloudOSVersion, build: template.key.cloudOSBuild))
+ // ...for its device only, and only for the same two sources.
+ #expect(try VPhoneMachineTemplates.resolveBuilds(sources: sources, device: "iPad16,1", in: fixture.library) { nil } == nil)
+ let other = VPhoneMachineTemplateSources(iPhone: sources.iPhone, cloudOS: "https://example.invalid/other")
+ #expect(try VPhoneMachineTemplates.resolveBuilds(sources: other, device: nil, in: fixture.library) { nil } == nil)
+
+ // A local reader that fails (an IPSW that is there but unreadable)
+ // fails the resolution rather than quietly using a template.
+ struct Unreadable: Error {}
+ #expect(throws: Unreadable.self) {
+ try VPhoneMachineTemplates.resolveBuilds(sources: sources, device: nil, in: fixture.library) { throw Unreadable() }
+ }
+ }
+
+ @Test func `deleting a template says the space is free unless machines still share its blocks`() {
+ #expect(VPhoneMachineTemplates.deletionNote(machines: []) == "no machine was cloned from it, so its space is free now")
+ let shared = VPhoneMachineTemplates.deletionNote(machines: ["phone-a", "phone-b"])
+ #expect(shared.hasPrefix("2 machine(s) cloned from it (phone-a, phone-b) still share its blocks"))
+ #expect(shared.contains("freed only when"))
+ }
}
diff --git a/VPhoneKit/VPhoneCoreKitTests/Bundle/TemplateSetupBootTests.swift b/VPhoneKit/VPhoneCoreKitTests/Bundle/TemplateSetupBootTests.swift
index 784fcd3f..6e7c98cd 100644
--- a/VPhoneKit/VPhoneCoreKitTests/Bundle/TemplateSetupBootTests.swift
+++ b/VPhoneKit/VPhoneCoreKitTests/Bundle/TemplateSetupBootTests.swift
@@ -358,6 +358,45 @@ struct TemplateSetupBootTests {
#expect(steps.slimming != VPhoneTemplateSlimmingRequest.defaultSlimming)
}
+ @Test func `a strict setup boot of a machine fails where the lenient one warns`() throws {
+ // vm template setup --strict: a machine Launchpad adopts under the
+ // key vm template find gave must not lose an app from that key.
+ let guest = FakeGuest(clock: FakeClock())
+ guest.refusedApps = ["com.apple.findmy"]
+ let failure = try #require(run(guest, requiresEveryApp: true).failed)
+ #expect(failure.step == .removeApps)
+ #expect(failure.reason.contains("com.apple.findmy"))
+ // Nothing recorded: the outcome is incomplete.
+ #expect(!failure.outcome.isComplete)
+ #expect(!guest.calls.contains("system.reboot"))
+ }
+
+ @Test func `deviations name what fell short of the plan`() {
+ let plan = VPhoneTemplateSetupPlan(slimming: VPhoneTemplateSlimmingRequest.defaultSlimming, requiresEveryApp: true)
+ var outcome = VPhoneTemplateSetupOutcome()
+ outcome.apps = plan.removedApps.map { VPhoneTemplateSetupAppResult(bundleID: $0, status: "removed") }
+ outcome.serviceProfile = plan.serviceProfile
+ outcome.serviceGroups = plan.serviceGroups
+ #expect(outcome.deviations(from: plan).isEmpty)
+
+ var short = outcome
+ short.apps[short.apps.firstIndex { $0.bundleID == "com.apple.findmy" }!] = VPhoneTemplateSetupAppResult(
+ bundleID: "com.apple.findmy",
+ status: "failed",
+ error: "LaunchServices still lists the app after unregistration",
+ )
+ short.apps.removeAll { $0.bundleID == "com.apple.news" }
+ let lines = short.deviations(from: plan)
+ #expect(lines.count == 1)
+ #expect(lines.first?.contains("com.apple.findmy (LaunchServices still lists") == true)
+ #expect(lines.first?.contains("com.apple.news") == true)
+
+ var profile = outcome
+ profile.serviceProfile = "none"
+ profile.serviceGroups = ["accounts"]
+ #expect(profile.deviations(from: plan) == ["service profile none, not trimmed", "service groups accounts, not "])
+ }
+
@Test func `an app that is already gone counts as removed`() throws {
let guest = FakeGuest(clock: FakeClock())
guest.installed.remove("com.apple.news")