Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Count template users by build, and say what a delete frees

Jacky9a35217d13d6
diff --git a/Documents/Guides/create-and-run.md b/Documents/Guides/create-and-run.md
index 58c00f97..7d0e7cce 100644
--- a/Documents/Guides/create-and-run.md
+++ b/Documents/Guides/create-and-run.md
@@ -152,12 +152,12 @@ vphone-cli vm template delete <id>
- **Stale.** A template is listed as stale when this `vphone-cli` belongs to another bundle series, when its key has an older format, when its preset now resolves to other boot-chain patches, or when its patch receipt disagrees with its plan. A stale template is never used: `vm create` with its key fails and names it. Delete it to have the next `vm create` build a new one.
- **Adopt.** `vm template adopt <vm>` turns a stopped VM into a template, under the key its own records give (`restore-info.json`, `PatchPlan.plist`, `config.plist`, the disk image, Launchpad's `launchpad.json`, and the steps `vm template trim` and `vm template setup` recorded in its `Template.plist`). The VM leaves `vm list`. Adopt a VM straight after its setup boot: every clone inherits what its guest has done since. A VM with snapshots is refused, and so is one that would be stale unless `--force` is given.
- **Never booted once frozen.** `vm launch` and `vphone-vm` refuse a frozen template, in DFU too; no machine name reaches into `.templates`, so `vm launch`, `clone`, `export`, `rename` and `delete` cannot pick one up by accident. A template that booted after being frozen would write state into the blocks every later clone inherits, and the clones made before it would stop sharing them.
-- **Machines using it.** A machine cloned from a template records the template in `TemplateSource.plist`; a `vm clone` of it keeps the record (the copy shares the template's blocks too) and `vm export` leaves it out (an import shares nothing). `vm template list` and `show` list the machines using each template and its size on disk, and `vm info` shows a machine's template. When `vm delete` removes the last machine cloned from a template that still exists, it says so, and never deletes the template itself:
+- **Machines using it.** A machine cloned from a template records the template in `TemplateSource.plist`; a `vm clone` of it keeps the record (the copy shares the template's blocks too) and `vm export` leaves it out (an import shares nothing). The record also names the template's build, so a template deleted and built again with the same key does not count the machines cloned from the old one, which share none of its blocks. `vm template list` and `show` list the machines using each template and its size on disk, and `vm info` shows a machine's template. When `vm delete` removes the last machine cloned from a template that still exists, it says so, and never deletes the template itself:
```
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. 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.
+- **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 use it, whose shared blocks stay allocated until they change them or are deleted, or that no machine uses it now, so deleting frees its blocks, though a local Time Machine snapshot taken while it existed may keep them until the snapshot expires. `--json` with `--force` prints the same facts. 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 df032de6..06ca1f42 100644
--- a/Research/Host/machine_templates.md
+++ b/Research/Host/machine_templates.md
@@ -78,8 +78,11 @@ re-resolves with the template's own `PatchSelection.plist`.
Launchpad never list a template.
- `Template.plist`: `Identifier`, `Key`, `Created`, `BuiltWithBundleVersion`,
`BootChainBundleVersion`, `SourceMachine` (the name a derived mDNS name
- follows from), `Frozen`, `FrozenAt`, `Steps` (`SnapshotDeleted`,
- `SetupDone`, `ServiceProfile`, `ServiceGroups`, `RemovedApps`, `TrimTier`),
+ follows from), `Frozen`, `FrozenAt`, `Build` (a UUID set each time a template
+ is frozen or adopted), `Steps` (`SnapshotDeleted`, `SetupDone`,
+ `ServiceProfile`, `ServiceGroups`, `RemovedApps`, `TrimTier`, and
+ `UnregisterAttempts`: the removed apps vphoned had to unregister more than
+ once, with the count; not part of the key),
`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` and `vm create` resolve a request's builds
@@ -97,18 +100,34 @@ re-resolves with the template's own `PatchSelection.plist`.
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).
- `VPhoneMachineTemplates.usage` maps each template to the machines (and
- templates adopted from such machines) that carry its identifier. `vm
- 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).
+ `Build` (the template's `Build`), `Cloned`. A plain `vm clone` keeps it
+ (the copy shares the template's blocks too); `vm export` excludes it (an
+ import shares nothing). `VPhoneMachineTemplates.usage` maps each template to
+ the machines (and templates adopted from such machines) cloned from it.
+ The identifier alone does not say that: a template deleted and built again
+ with the same key gets the same identifier and shares nothing with the
+ clones of the old one. A clone counts for a template only when
+ `VPhoneMachineTemplateSource.isClone(of:)` says so: both `Build`s equal, or,
+ when either side has none (records written before 2026-10-09), `Cloned` no
+ earlier than the template's `FrozenAt` (else `Created`). Until then the
+ rebuilt template counted the old build's clones as its users, in `vm
+ template list/show`, Launchpad's "N machine(s) use it" and the delete notes
+ (PR #633 retest, N1). `vm template list/show --json` add `build` and
+ `frozenAt`. `vm template list/show` print the users with the template's
+ allocated size; `vm delete` of the last machine cloned from the template
+ that exists now prints a note to delete it (`unusedTemplate(after:in:)`;
+ deleting a clone of an earlier build prints nothing), never deleting it
+ itself. `vm template delete` says what the deletion frees
+ (`VPhoneMachineTemplates.deletionNote`, from `usage` read before it), from
+ facts it has: with machines using the template, it names them and says the
+ blocks they share stay allocated until they change them or are deleted;
+ with none, "no machine uses it now; deleting frees its blocks (a local Time
+ Machine snapshot may keep them until it expires)". It cannot know whether
+ the template was cloned before and the clones deleted, so it no longer says
+ "no machine was cloned from it", and a local snapshot can keep the blocks,
+ so it no longer says "its space is free now" (retest B8). `--json` (with
+ `--force`) prints `deleted`, `path`, `machines`, `blocksFreed` and the
+ same `note`.
- 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
@@ -410,7 +429,15 @@ 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
+listed, and only then fails the app (`GuestAppUnregistration`). It
+reports `unregister_attempts` for an app that needed more than one call. The
+setup boot keeps it (`VPhoneTemplateSetupAppResult.unregisterAttempts`),
+prints ` <bundle id>: unregistered after N attempts` in its remove-apps step
+and a summary line in its report, and records the counts in
+`Steps.UnregisterAttempts`, so the race can be counted from build logs and
+`vm template show`. Until 2026-10-09 the count never left vphoned (retest
+G1). It does not tell a first check that still saw the app from one that did
+not: an app that left LaunchServices while vphoned polled still counts 1. 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.
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneTemplateSetup.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneTemplateSetup.swift
index 898533aa..4ccecf50 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneTemplateSetup.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneTemplateSetup.swift
@@ -189,6 +189,10 @@ enum VPhoneTemplateSetupRun {
}
print(" services: \(services)\(outcome.serviceProfile == "none" ? "" : " (\(outcome.servicesOwned) owned)")")
print(" apps removed: \(outcome.removedApps.isEmpty ? "none" : outcome.removedApps.joined(separator: ", "))")
+ let retried = outcome.retriedUnregistrations.sorted { $0.key < $1.key }
+ if !retried.isEmpty {
+ print(" unregistered after retries: \(retried.map { "\($0.key) (\($0.value) attempts)" }.joined(separator: ", "))")
+ }
for warning in outcome.warnings {
print(" warning: \(warning)")
}
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineTemplateCommand.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineTemplateCommand.swift
index 0ba58b00..1435513b 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineTemplateCommand.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineTemplateCommand.swift
@@ -56,12 +56,18 @@ struct VPhoneMachineTemplateReport: Encodable {
/// What the template's files take on disk (`st_blocks`): what deleting
/// it frees once no machine shares its blocks.
var allocatedBytes: UInt64
- /// Machines cloned from it (their `TemplateSource.plist`), sorted.
+ /// Machines cloned from this build of it (their `TemplateSource.plist`),
+ /// sorted. Machines cloned from an earlier template with the same key
+ /// are not listed: they share none of its blocks.
var machines: [String]
var stale: Bool
var staleReasons: [String]
/// The IPSW sources it was built from, when its build named them.
var sources: VPhoneMachineTemplateSources?
+ /// The build's UUID, copied into each clone's `TemplateSource.plist`;
+ /// nil for a template frozen before builds were recorded.
+ var build: String?
+ var frozenAt: Date?
init(_ template: VPhoneMachineTemplate, usage: [String: [String]]) {
let record = template.record
@@ -79,6 +85,8 @@ struct VPhoneMachineTemplateReport: Encodable {
staleReasons = VPhoneMachineTemplateKeys.staleReasons(template)
stale = !staleReasons.isEmpty
sources = record.sources
+ build = record.build
+ frozenAt = record.frozenAt
}
}
@@ -180,7 +188,14 @@ struct VPhoneVirtualMachineTemplateShowCommand: ParsableCommand {
print("removed: \(key.slimming.removedApps.joined(separator: ","))")
}
print("steps: snapshot deleted \(report.steps.snapshotDeleted ? "yes" : "no"), setup done \(report.steps.setupDone ? "yes" : "no")")
+ let retried = report.steps.unregisterAttempts.sorted { $0.key < $1.key }
+ if !retried.isEmpty {
+ print("retried: \(retried.map { "\($0.key) unregistered after \($0.value) attempts" }.joined(separator: ", "))")
+ }
print("created: \(report.created.formatted(.iso8601))")
+ if let frozenAt = report.frozenAt {
+ print("frozen: \(frozenAt.formatted(.iso8601))\(report.build.map { ", build \($0)" } ?? "")")
+ }
if let source = report.sourceMachine {
print("source: \(source)")
}
@@ -709,13 +724,24 @@ struct VPhoneVirtualMachineTemplateDeleteCommand: ParsableCommand {
abstract: "Delete a template or an unfinished template build",
discussion: """
Machines cloned from the template keep working: they share its blocks but do not refer \
- to it. The space those shared blocks take is freed only when no clone uses them either.
+ to it. The space those shared blocks take is freed only when no clone uses them either. \
+ A local Time Machine snapshot taken while the template existed keeps its blocks until \
+ the snapshot expires.
+
+ --json prints what was deleted and the machines that used it; it needs --force.
""",
)
@OptionGroup var lib: VPhoneLibraryOption
@Argument(help: "template id (or unique prefix), or a .building-… name from vm template list") var id: String
@Flag(name: .shortAndLong, help: "Do not prompt") var force = false
+ @Flag(name: .shortAndLong, help: "Emit the result as JSON (needs --force)") var json = false
+
+ func validate() throws {
+ if json, !force {
+ throw ValidationError("--json does not prompt: pass --force with it.")
+ }
+ }
func run() throws {
let library = lib.library
@@ -733,7 +759,33 @@ struct VPhoneVirtualMachineTemplateDeleteCommand: ParsableCommand {
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)
+ let note = VPhoneMachineTemplates.deletionNote(machines: machines)
+ if json {
+ try print(encodeJSON(VPhoneMachineTemplateDeleteReport(
+ deleted: removed.lastPathComponent,
+ path: removed.path,
+ machines: machines,
+ blocksFreed: machines.isEmpty,
+ note: note,
+ )))
+ return
+ }
print("deleted \(removed.lastPathComponent)")
- print("note: \(VPhoneMachineTemplates.deletionNote(machines: machines))")
+ print("note: \(note)")
}
}
+
+/// What `vm template delete --json` prints.
+struct VPhoneMachineTemplateDeleteReport: Encodable {
+ /// The template identifier or `.building-…` name removed.
+ var deleted: String
+ var path: String
+ /// The machines that used the template when it was deleted; their shared
+ /// blocks stay allocated until they change them or are deleted.
+ var machines: [String]
+ /// True when no machine used it, so its blocks are freed, unless a local
+ /// Time Machine snapshot keeps them until it expires.
+ var blocksFreed: Bool
+ /// The same note the text output prints.
+ var note: String
+}
diff --git a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplates.swift b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplates.swift
index 09cd37da..89374da2 100644
--- a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplates.swift
+++ b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplates.swift
@@ -20,6 +20,11 @@ public struct VPhoneMachineTemplateSteps: Codable, Equatable, Sendable {
public var serviceGroups: [String]
public var removedApps: [String]
public var trimTier: String
+ /// The removed apps vphoned had to unregister more than once, with the
+ /// number of attempts. Not part of the key: a record of how the setup
+ /// boot went, kept so the race with first-boot registration can be
+ /// counted afterwards.
+ public var unregisterAttempts: [String: Int]
public init(
snapshotDeleted: Bool = false,
@@ -28,6 +33,7 @@ public struct VPhoneMachineTemplateSteps: Codable, Equatable, Sendable {
serviceGroups: [String] = [],
removedApps: [String] = [],
trimTier: String = "none",
+ unregisterAttempts: [String: Int] = [:],
) {
self.snapshotDeleted = snapshotDeleted
self.setupDone = setupDone
@@ -35,6 +41,7 @@ public struct VPhoneMachineTemplateSteps: Codable, Equatable, Sendable {
self.serviceGroups = Array(Set(serviceGroups)).sorted()
self.removedApps = Array(Set(removedApps)).sorted()
self.trimTier = trimTier
+ self.unregisterAttempts = unregisterAttempts
}
/// Why a template with these steps must not be frozen, or nothing.
@@ -74,6 +81,7 @@ public struct VPhoneMachineTemplateSteps: Codable, Equatable, Sendable {
case serviceGroups = "ServiceGroups"
case removedApps = "RemovedApps"
case trimTier = "TrimTier"
+ case unregisterAttempts = "UnregisterAttempts"
}
public init(from decoder: any Decoder) throws {
@@ -84,6 +92,7 @@ public struct VPhoneMachineTemplateSteps: Codable, Equatable, Sendable {
serviceGroups = try container.decodeIfPresent([String].self, forKey: .serviceGroups) ?? []
removedApps = try container.decodeIfPresent([String].self, forKey: .removedApps) ?? []
trimTier = try container.decodeIfPresent(String.self, forKey: .trimTier) ?? "none"
+ unregisterAttempts = try container.decodeIfPresent([String: Int].self, forKey: .unregisterAttempts) ?? [:]
}
}
@@ -91,17 +100,42 @@ public struct VPhoneMachineTemplateSteps: Codable, Equatable, Sendable {
/// `TemplateSource.plist`, in a machine cloned from a template: which
/// template it shares blocks with.
+///
+/// The identifier names a key, and a key outlives any one template built for
+/// it: a template deleted and built again gets the same identifier, but the
+/// new one shares no block with machines cloned from the old one. `Build`
+/// names the build, so only machines of the template that exists now count
+/// as its users.
public struct VPhoneMachineTemplateSource: Codable, Equatable, Sendable {
public var identifier: String
+ /// The ``VPhoneMachineTemplateRecord/build`` of the template it was cloned
+ /// from; nil in a record written before builds had one, or for a
+ /// template without one.
+ public var build: String?
public var cloned: Date
- public init(identifier: String, cloned: Date = Date()) {
+ public init(identifier: String, build: String? = nil, cloned: Date = Date()) {
self.identifier = identifier
+ self.build = build
self.cloned = VPhoneMachineTemplates.wholeSeconds(cloned)
}
+ /// Whether a machine with this record was cloned from the template
+ /// `record` describes, and not from an earlier one with the same key.
+ /// Both sides having a build decides it. Otherwise (a record written
+ /// before builds were recorded, on either side) the dates do: a machine
+ /// cloned before the template was frozen cannot have come from it.
+ public func isClone(of record: VPhoneMachineTemplateRecord) -> Bool {
+ guard identifier == record.identifier else { return false }
+ if let build, let other = record.build {
+ return build == other
+ }
+ return cloned >= (record.frozenAt ?? record.created)
+ }
+
private enum CodingKeys: String, CodingKey {
case identifier = "Identifier"
+ case build = "Build"
case cloned = "Cloned"
}
}
@@ -182,6 +216,12 @@ public struct VPhoneMachineTemplateRecord: Codable, Equatable, Sendable {
/// template adopted without them. Not part of the key: two URLs of the
/// same build make the same template.
public var sources: VPhoneMachineTemplateSources?
+ /// A UUID set each time a template is frozen or adopted, and copied into
+ /// each clone's `TemplateSource.plist`. The identifier stays the same
+ /// when a template is deleted and built again; this does not, so the
+ /// clones of an earlier build are not counted as the new one's users.
+ /// Nil for a template frozen before it was recorded.
+ public var build: String?
public init(
key: VPhoneMachineTemplateKey,
@@ -193,6 +233,7 @@ public struct VPhoneMachineTemplateRecord: Codable, Equatable, Sendable {
frozenAt: Date? = nil,
steps: VPhoneMachineTemplateSteps = VPhoneMachineTemplateSteps(),
sources: VPhoneMachineTemplateSources? = nil,
+ build: String? = nil,
) {
identifier = key.identifier
self.key = key
@@ -204,6 +245,7 @@ public struct VPhoneMachineTemplateRecord: Codable, Equatable, Sendable {
self.frozenAt = frozenAt.map(VPhoneMachineTemplates.wholeSeconds)
self.steps = steps
self.sources = sources
+ self.build = build
}
private enum CodingKeys: String, CodingKey {
@@ -217,6 +259,7 @@ public struct VPhoneMachineTemplateRecord: Codable, Equatable, Sendable {
case frozenAt = "FrozenAt"
case steps = "Steps"
case sources = "Sources"
+ case build = "Build"
}
public init(from decoder: any Decoder) throws {
@@ -231,6 +274,7 @@ public struct VPhoneMachineTemplateRecord: Codable, Equatable, Sendable {
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)
+ build = try container.decodeIfPresent(String.self, forKey: .build)
}
}
@@ -669,6 +713,7 @@ public enum VPhoneMachineTemplates {
try removeRestoreTree(of: bundle)
record.frozen = true
record.frozenAt = Self.wholeSeconds(now)
+ record.build = UUID().uuidString
try writeRecord(record, inBundle: build.bundleURL)
let destination = url(of: build.identifier, in: build.libraryRoot)
do {
@@ -677,6 +722,7 @@ public enum VPhoneMachineTemplates {
} catch {
record.frozen = false
record.frozenAt = nil
+ record.build = nil
try? writeRecord(record, inBundle: build.bundleURL)
throw error
}
@@ -747,6 +793,7 @@ public enum VPhoneMachineTemplates {
try removeRestoreTree(of: bundle)
record.frozen = true
record.frozenAt = Self.wholeSeconds(now)
+ record.build = UUID().uuidString
try writeRecord(record, inBundle: bundle.url)
do {
// Checked again just before the rename: nothing may have opened
@@ -788,7 +835,10 @@ public enum VPhoneMachineTemplates {
newIdentity: true,
)
do {
- try writeSource(VPhoneMachineTemplateSource(identifier: template.identifier), inBundle: clone.url)
+ try writeSource(
+ VPhoneMachineTemplateSource(identifier: template.identifier, build: template.record.build),
+ inBundle: clone.url,
+ )
} catch {
try? FileManager.default.removeItem(at: clone.url)
throw error
@@ -827,27 +877,46 @@ public enum VPhoneMachineTemplates {
/// The machines of the library cloned from each template, by template
/// identifier, sorted by name. Templates adopted from such a machine
/// count too, under `.templates/<id>`: they share its blocks as well.
+ ///
+ /// A machine counts only for the template it was cloned from
+ /// (``VPhoneMachineTemplateSource/isClone(of:)``): one cloned from an
+ /// earlier template with the same key, since deleted and built again,
+ /// shares nothing with the template that exists now and is left out. A
+ /// machine whose template no longer exists is listed under its identifier.
public static func usage(in library: VPhoneLibrary) -> [String: [String]] {
+ let templates = (try? list(in: library).templates) ?? []
+ var records: [String: VPhoneMachineTemplateRecord] = [:]
+ for template in templates {
+ records[template.identifier] = template.record
+ }
var users: [String: [String]] = [:]
+ func count(_ source: VPhoneMachineTemplateSource, as user: String) {
+ if let record = records[source.identifier], !source.isClone(of: record) {
+ return
+ }
+ users[source.identifier, default: []].append(user)
+ }
for bundle in (try? library.bundles()) ?? [] {
if let source = readSource(inBundle: bundle.url) {
- users[source.identifier, default: []].append(bundle.name)
+ count(source, as: bundle.name)
}
}
- for template in (try? list(in: library).templates) ?? [] {
+ for template in templates {
if let source = readSource(inBundle: template.url), source.identifier != template.identifier {
- users[source.identifier, default: []].append("\(directoryName)/\(template.identifier)")
+ count(source, as: "\(directoryName)/\(template.identifier)")
}
}
return users.mapValues { $0.sorted() }
}
- /// The template `source` names, when it still exists and nothing in the
- /// library uses it any more: what `vm delete` reports after deleting a
- /// machine cloned from it. Never deletes it.
+ /// The template `source` names, when it still exists, the deleted machine
+ /// was cloned from it (not from an earlier template with the same key),
+ /// and nothing in the library uses it any more: what `vm delete` reports
+ /// after deleting a machine cloned from it. Never deletes it.
public static func unusedTemplate(after source: VPhoneMachineTemplateSource?, in library: VPhoneLibrary) -> VPhoneMachineTemplate? {
guard let source,
let template = try? Self.template(source.identifier, in: library),
+ source.isClone(of: template.record),
usage(in: library)[template.identifier, default: []].isEmpty
else { return nil }
return template
@@ -886,17 +955,20 @@ 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.
+ /// What `vm template delete` says about the space it freed, from what is
+ /// known. `machines` is what ``usage(in:)`` listed for the template before
+ /// it was deleted: the machines that use it now. Machines cloned from it
+ /// and deleted since are not among them, so the note never claims it was
+ /// never cloned. With no user its blocks are freed, unless a local Time
+ /// Machine snapshot taken while it existed keeps them; with users, the
+ /// blocks they share stay allocated until they change them or are 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 "no machine uses it now; deleting frees its blocks "
+ + "(a local Time Machine snapshot may keep them until it expires)"
}
- 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"
+ return "\(machines.count) machine(s) use it (\(machines.joined(separator: ", "))); "
+ + "the blocks they share with it stay allocated until they change them or are deleted"
}
/// Removes a frozen template, by identifier or unique prefix, or a staging
diff --git a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneTemplateSetupBoot.swift b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneTemplateSetupBoot.swift
index 5bfaa8af..c986e468 100644
--- a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneTemplateSetupBoot.swift
+++ b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneTemplateSetupBoot.swift
@@ -194,11 +194,17 @@ public struct VPhoneTemplateSetupAppResult: Equatable, Sendable {
/// vphoned's status: `removed`, `absent`, `unregistered_stale` or `failed`.
public var status: String
public var error: String?
+ /// How many times vphoned called LaunchServices to unregister the app:
+ /// more than one when the app was still listed after the first call (the
+ /// race with Find My's first-boot registration). vphoned reports it only
+ /// above one; 1 otherwise.
+ public var unregisterAttempts: Int
- public init(bundleID: String, status: String, error: String? = nil) {
+ public init(bundleID: String, status: String, error: String? = nil, unregisterAttempts: Int = 1) {
self.bundleID = bundleID
self.status = status
self.error = error
+ self.unregisterAttempts = unregisterAttempts
}
/// The app is not installed afterwards, whichever way.
@@ -230,6 +236,16 @@ public struct VPhoneTemplateSetupOutcome: Equatable, Sendable {
apps.filter(\.isGone).map(\.bundleID).sorted()
}
+ /// The apps vphoned had to unregister more than once, with the number of
+ /// attempts.
+ public var retriedUnregistrations: [String: Int] {
+ var retried: [String: Int] = [:]
+ for app in apps where app.unregisterAttempts > 1 {
+ retried[app.bundleID] = app.unregisterAttempts
+ }
+ return retried
+ }
+
/// 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.
@@ -264,6 +280,7 @@ public struct VPhoneTemplateSetupOutcome: Equatable, Sendable {
steps.serviceProfile = serviceProfile
steps.serviceGroups = serviceGroups.sorted()
steps.removedApps = removedApps
+ steps.unregisterAttempts = retriedUnregistrations
return steps
}
}
@@ -457,7 +474,12 @@ public final class VPhoneTemplateSetupBoot {
}
var results = rows.compactMap { row -> VPhoneTemplateSetupAppResult? in
guard let id = row["bundle_id"] as? String else { return nil }
- return VPhoneTemplateSetupAppResult(bundleID: id, status: row["status"] as? String ?? "failed", error: row["error"] as? String)
+ return VPhoneTemplateSetupAppResult(
+ bundleID: id,
+ status: row["status"] as? String ?? "failed",
+ error: row["error"] as? String,
+ unregisterAttempts: max(1, Self.number(row["unregister_attempts"]).flatMap { Int(exactly: $0.rounded()) } ?? 1),
+ )
}
for id in plan.removedApps where !results.contains(where: { $0.bundleID == id }) {
results.append(VPhoneTemplateSetupAppResult(bundleID: id, status: "failed", error: "vphoned returned no result for it"))
@@ -465,6 +487,12 @@ public final class VPhoneTemplateSetupBoot {
outcome.apps = results
let refused = results.filter { !$0.isGone }
log(" \(results.count - refused.count) of \(results.count) apps removed or absent")
+ // Each app LaunchServices still listed after the first unregister
+ // call: the build log is where the race with first-boot
+ // registration can be counted.
+ for app in results.sorted(by: { $0.bundleID < $1.bundleID }) where app.unregisterAttempts > 1 {
+ log(" \(app.bundleID): unregistered after \(app.unregisterAttempts) attempts")
+ }
guard !refused.isEmpty else { return }
let lines = refused.map { "\($0.bundleID): \($0.error ?? $0.status)" }
if plan.requiresEveryApp {
diff --git a/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplatesTests.swift b/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplatesTests.swift
index 1364780d..2fed51c4 100644
--- a/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplatesTests.swift
+++ b/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplatesTests.swift
@@ -663,10 +663,124 @@ struct MachineTemplatesTests {
}
}
- @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")
+ @Test func `deleting a template says its blocks are freed unless machines use it`() {
+ let free = VPhoneMachineTemplates.deletionNote(machines: [])
+ #expect(free.hasPrefix("no machine uses it now; deleting frees its blocks"))
+ // Never claims it was never cloned, and does not promise free space a
+ // local Time Machine snapshot may keep.
+ #expect(!free.contains("cloned"))
+ #expect(free.contains("Time Machine snapshot"))
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"))
+ #expect(shared.hasPrefix("2 machine(s) use it (phone-a, phone-b); "))
+ #expect(shared.contains("stay allocated until they change them or are deleted"))
+ }
+
+ // MARK: - Builds
+
+ @Test func `a template rebuilt with the same key does not count the old build's clones`() throws {
+ let fixture = try makeFixture()
+ defer { fixture.cleanUp() }
+ try makeMachine("src", in: fixture)
+ let first = try VPhoneMachineTemplates.adopt(
+ machineNamed: "src", in: fixture.library, record: record(), now: Date(timeIntervalSince1970: 1_800_000_100),
+ )
+ let firstBuild = try #require(first.record.build)
+ let old = try VPhoneMachineTemplates.cloneMachine(from: first, to: "old", in: fixture.library)
+ #expect(VPhoneMachineTemplates.readSource(inBundle: old.url)?.build == firstBuild)
+ #expect(VPhoneMachineTemplates.usage(in: fixture.library) == [first.identifier: ["old"]])
+
+ // Deleted and built again under the same identifier, with a new build.
+ try VPhoneMachineTemplates.delete(first.identifier, in: fixture.library)
+ #expect(VPhoneMachineTemplates.usage(in: fixture.library) == [first.identifier: ["old"]])
+ try makeMachine("src2", in: fixture)
+ let second = try VPhoneMachineTemplates.adopt(machineNamed: "src2", in: fixture.library, record: record(source: "src2"))
+ #expect(second.identifier == first.identifier)
+ #expect(second.record.build != nil && second.record.build != firstBuild)
+ #expect(VPhoneMachineTemplates.usage(in: fixture.library)[second.identifier] == nil)
+
+ let new = try VPhoneMachineTemplates.cloneMachine(from: second, to: "new", in: fixture.library)
+ #expect(VPhoneMachineTemplates.usage(in: fixture.library) == [second.identifier: ["new"]])
+ // Deleting the old build's clone says nothing about the new template;
+ // deleting the new one's last clone does.
+ let oldSource = VPhoneMachineTemplates.readSource(inBundle: old.url)
+ try VPhoneBundleOperations.delete(bundleNamed: "old", in: fixture.library)
+ #expect(VPhoneMachineTemplates.unusedTemplate(after: oldSource, in: fixture.library) == nil)
+ let newSource = VPhoneMachineTemplates.readSource(inBundle: new.url)
+ try VPhoneBundleOperations.delete(bundleNamed: "new", in: fixture.library)
+ #expect(VPhoneMachineTemplates.unusedTemplate(after: newSource, in: fixture.library)?.identifier == second.identifier)
+ }
+
+ @Test func `a clone record without a build is matched by its clone date`() throws {
+ let frozenAt = Date(timeIntervalSince1970: 1_800_000_100)
+ var template = record()
+ template.frozen = true
+ template.frozenAt = frozenAt
+ template.build = UUID().uuidString
+ let id = template.identifier
+
+ // Written before builds were recorded: the date decides.
+ #expect(VPhoneMachineTemplateSource(identifier: id, cloned: frozenAt).isClone(of: template))
+ #expect(VPhoneMachineTemplateSource(identifier: id, cloned: frozenAt + 60).isClone(of: template))
+ #expect(!VPhoneMachineTemplateSource(identifier: id, cloned: frozenAt - 1).isClone(of: template))
+ // A build on both sides decides, whatever the dates say.
+ #expect(VPhoneMachineTemplateSource(identifier: id, build: template.build, cloned: frozenAt - 600).isClone(of: template))
+ #expect(!VPhoneMachineTemplateSource(identifier: id, build: UUID().uuidString, cloned: frozenAt + 60).isClone(of: template))
+ // A template frozen before builds were recorded: the date again.
+ var legacy = template
+ legacy.build = nil
+ #expect(VPhoneMachineTemplateSource(identifier: id, build: UUID().uuidString, cloned: frozenAt + 60).isClone(of: legacy))
+ #expect(!VPhoneMachineTemplateSource(identifier: id, build: UUID().uuidString, cloned: frozenAt - 60).isClone(of: legacy))
+ // Without a freeze date, the creation date.
+ legacy.frozenAt = nil
+ #expect(VPhoneMachineTemplateSource(identifier: id, cloned: template.created).isClone(of: legacy))
+ #expect(!VPhoneMachineTemplateSource(identifier: id, cloned: template.created - 1).isClone(of: legacy))
+ // Another key never.
+ #expect(!VPhoneMachineTemplateSource(identifier: "000000000000", build: template.build, cloned: frozenAt).isClone(of: template))
+ }
+
+ @Test func `a legacy clone record of a deleted template is left out by date`() throws {
+ let fixture = try makeFixture()
+ defer { fixture.cleanUp() }
+ try makeMachine("src", in: fixture)
+ let template = try VPhoneMachineTemplates.adopt(machineNamed: "src", in: fixture.library, record: record())
+ let frozenAt = try #require(template.record.frozenAt)
+ // Two clones whose records predate builds: one of an earlier template
+ // with this key, one of this one.
+ let earlier = try makeMachine("earlier", in: fixture)
+ try VPhoneMachineTemplates.writeSource(
+ VPhoneMachineTemplateSource(identifier: template.identifier, cloned: frozenAt - 3600), inBundle: earlier.url,
+ )
+ let current = try makeMachine("current", in: fixture)
+ try VPhoneMachineTemplates.writeSource(
+ VPhoneMachineTemplateSource(identifier: template.identifier, cloned: frozenAt + 1), inBundle: current.url,
+ )
+ #expect(VPhoneMachineTemplates.usage(in: fixture.library) == [template.identifier: ["current"]])
+ }
+
+ @Test func `a record without a build reads, and a frozen one gets one`() throws {
+ let fixture = try makeFixture()
+ defer { fixture.cleanUp() }
+ let machine = try makeMachine("src", in: fixture)
+ // An older record: no Build key at all.
+ try VPhoneMachineTemplates.writeRecord(record(), inBundle: machine.url)
+ let raw = try Data(contentsOf: machine.url.appendingPathComponent(VPhoneMachineTemplates.recordFileName))
+ #expect(!String(decoding: raw, as: UTF8.self).contains("<key>Build</key>"))
+ #expect(try VPhoneMachineTemplates.readRecord(inBundle: machine.url)?.build == nil)
+ let source = try PropertyListDecoder().decode(
+ VPhoneMachineTemplateSource.self,
+ from: PropertyListSerialization.data(
+ fromPropertyList: ["Identifier": "52b1fcc75e0c", "Cloned": Date(timeIntervalSince1970: 1_800_000_000)],
+ format: .xml, options: 0,
+ ),
+ )
+ #expect(source.build == nil)
+
+ let key = MachineTemplateKeyTests.key(bootChain: "built")
+ let build = try VPhoneMachineTemplates.beginBuild(key, in: fixture.library)
+ try makeMachine(key.identifier, in: fixture, library: build.library)
+ try VPhoneMachineTemplates.writeRecord(record(key), inBundle: build.bundleURL)
+ let frozen = try VPhoneMachineTemplates.freeze(build)
+ #expect(frozen.record.build != nil)
+ #expect(try VPhoneMachineTemplates.template(frozen.identifier, in: fixture.library).record.build == frozen.record.build)
}
}
diff --git a/VPhoneKit/VPhoneCoreKitTests/Bundle/TemplateSetupBootTests.swift b/VPhoneKit/VPhoneCoreKitTests/Bundle/TemplateSetupBootTests.swift
index 6e7c98cd..0ab9d8fe 100644
--- a/VPhoneKit/VPhoneCoreKitTests/Bundle/TemplateSetupBootTests.swift
+++ b/VPhoneKit/VPhoneCoreKitTests/Bundle/TemplateSetupBootTests.swift
@@ -34,6 +34,8 @@ private final class FakeGuest: VPhoneTemplateSetupMachine {
var skipFailures = 0
var unsettledAnswers = 1
var refusedApps: Set<String> = []
+ /// Apps vphoned had to unregister more than once, as it reports them.
+ var unregisterAttempts: [String: Int] = [:]
var servicesKeepRunning = false
var rebootNeverReturns = false
var stopsCleanly = true
@@ -124,7 +126,9 @@ private final class FakeGuest: VPhoneTemplateSetupMachine {
if refusedApps.contains(id) {
results.append(["bundle_id": id, "status": "failed", "removed": false, "error": "not in a bundle container"])
} else if installed.remove(id) != nil {
- results.append(["bundle_id": id, "status": "removed", "removed": true])
+ var row: [String: Any] = ["bundle_id": id, "status": "removed", "removed": true]
+ row["unregister_attempts"] = unregisterAttempts[id]
+ results.append(row)
} else {
results.append(["bundle_id": id, "status": "absent", "removed": false])
}
@@ -405,6 +409,34 @@ struct TemplateSetupBootTests {
#expect(outcome.removedApps.contains("com.apple.news"))
}
+ @Test func `apps unregistered after more than one attempt are logged and recorded`() throws {
+ let guest = FakeGuest(clock: FakeClock())
+ guest.unregisterAttempts = ["com.apple.findmy": 3, "com.apple.tv": 2]
+ var lines: [String] = []
+ let boot = VPhoneTemplateSetupBoot(
+ machine: guest,
+ plan: VPhoneTemplateSetupPlan(slimming: VPhoneTemplateSlimmingRequest.defaultSlimming, requiresEveryApp: true),
+ clock: guest.clock,
+ log: { lines.append($0) },
+ )
+ let outcome = try boot.run()
+
+ #expect(outcome.apps.first(where: { $0.bundleID == "com.apple.findmy" })?.unregisterAttempts == 3)
+ #expect(outcome.apps.first(where: { $0.bundleID == "com.apple.news" })?.unregisterAttempts == 1)
+ #expect(outcome.retriedUnregistrations == ["com.apple.findmy": 3, "com.apple.tv": 2])
+ #expect(lines.contains(" com.apple.findmy: unregistered after 3 attempts"))
+ #expect(lines.contains(" com.apple.tv: unregistered after 2 attempts"))
+ #expect(!lines.contains { $0.contains("com.apple.news: unregistered") })
+ // Recorded with the steps, outside the key.
+ let steps = outcome.applying(to: VPhoneMachineTemplateSteps())
+ #expect(steps.unregisterAttempts == ["com.apple.findmy": 3, "com.apple.tv": 2])
+ var without = steps
+ without.unregisterAttempts = [:]
+ #expect(without.slimming == steps.slimming)
+ let encoded = try PropertyListEncoder().encode(steps)
+ #expect(try PropertyListDecoder().decode(VPhoneMachineTemplateSteps.self, from: encoded) == steps)
+ }
+
@Test func `a VM that exits fails the step it was in`() throws {
let guest = FakeGuest(clock: FakeClock())
guest.exitsAfterStart = true