Run a virtual iPhone on an Apple Silicon Mac.
Swift
import Darwin
import Foundation
// MARK: - Tier
/// How much of the guest's System volume a template build deletes offline,
/// after `cfw install`. Each tier removes everything the one before it does.
///
/// The files go for good: a clone cannot get them back, so the tier is part
/// of the template key. They also free nothing while the CFW-renamed
/// `orig-fs.disabled.rn-*` snapshot still references them, and only the guest
/// can delete that snapshot (vphoned `apfs.snapshot.delete`, during the
/// template's setup boot). A trimmed template is therefore frozen only once
/// its snapshot is gone; see ``VPhoneMachineTemplateSteps/problems``.
public enum VPhoneSystemTrimTier: String, CaseIterable, Comparable, Sendable {
case none
/// `usr/standalone/update`: the software-update ramdisk and baseband
/// firmware. About 0.35 GB.
case conservative
/// Conservative, plus the AirPods/Beats pairing assets, the watch faces
/// and the linguistic data of languages not kept. About 1.2 GB.
case standard
/// Reserved: other languages' `.lproj`, Health assets, some fonts. Not
/// validated on a guest, so not offered.
case aggressive
/// Whether this version can apply the tier.
public var isSupported: Bool {
self != .aggressive
}
private var rank: Int {
Self.allCases.firstIndex(of: self) ?? 0
}
public static func < (lhs: Self, rhs: Self) -> Bool {
lhs.rank < rhs.rank
}
/// Parses a tier a user typed. `aggressive` is recognized and refused.
public static func parse(_ text: String) throws -> Self {
guard let tier = Self(rawValue: text.lowercased()) else {
throw VPhoneSystemTrimError.unknownTier(text)
}
guard tier.isSupported else {
throw VPhoneSystemTrimError.unsupportedTier(tier.rawValue)
}
return tier
}
}
// MARK: - Entry
/// One place on the System volume a tier deletes from.
public struct VPhoneSystemTrimEntry: Equatable, Sendable {
public enum Selection: Equatable, Sendable {
/// The item at `path` itself.
case item
/// Everything inside the folder at `path`; the folder stays.
case contents
/// The children of the folder at `path` named `prefix + language +
/// suffix` whose language is not in `keeping`. Other children stay.
case languageBundles(prefix: String, suffix: String, keeping: [String])
}
/// Relative to the System volume's root.
public let path: String
public let selection: Selection
/// The lowest tier that deletes it.
public let tier: VPhoneSystemTrimTier
/// Why it can go, for logs and docs.
public let note: String
/// Whether a direct child of the folder at `path`, by name, is deleted.
/// Never for `.item`, which names its target itself.
public func selects(child name: String) -> Bool {
guard VPhoneSystemTrim.isSingleComponent(name) else { return false }
switch selection {
case .item:
return false
case .contents:
return true
case let .languageBundles(prefix, suffix, keeping):
guard name.hasPrefix(prefix), name.hasSuffix(suffix), name.count > prefix.count + suffix.count else {
return false
}
let language = String(name.dropFirst(prefix.count).dropLast(suffix.count))
return !keeping.contains(language)
}
}
}
// MARK: - Spec
/// One trim: a tier, the version of the list it was taken from, and the
/// languages a language-removing tier keeps. ``keyValue`` is what a template
/// key and its recorded steps store as `trimTier`, so templates trimmed by a
/// different list or keeping other languages never match each other.
public struct VPhoneSystemTrimSpec: Equatable, Hashable, Sendable {
public let tier: VPhoneSystemTrimTier
public let listVersion: Int
/// Sorted. Empty for a tier that removes no language data.
public let keptLanguages: [String]
public static let none = VPhoneSystemTrimSpec(uncheckedTier: .none, listVersion: VPhoneSystemTrim.listVersion, keptLanguages: [])
/// The standard tier keeping ``VPhoneSystemTrim/defaultKeptLanguages``:
/// the default for a template that gets its setup boot.
public static let standard = VPhoneSystemTrimSpec(
uncheckedTier: .standard,
listVersion: VPhoneSystemTrim.listVersion,
keptLanguages: Array(Set(VPhoneSystemTrim.defaultKeptLanguages + ["en"])).sorted(),
)
/// `--trim` and `--keep-languages` as typed: a tier name, and an optional
/// comma-separated language list, which only a language-removing tier
/// takes.
public static func parse(tier text: String, keptLanguages list: String? = nil) throws -> Self {
let tier = try VPhoneSystemTrimTier.parse(text)
guard let list else { return try Self(tier: tier) }
guard tier >= .standard else {
throw VPhoneSystemTrimError.languagesUnused(tier.rawValue)
}
let languages = list.split(separator: ",").map { $0.trimmingCharacters(in: .whitespaces) }.filter { !$0.isEmpty }
return try Self(tier: tier, keptLanguages: languages)
}
/// Validates the tier and languages. English is always kept.
public init(tier: VPhoneSystemTrimTier, keptLanguages: [String] = VPhoneSystemTrim.defaultKeptLanguages) throws {
guard tier.isSupported else {
throw VPhoneSystemTrimError.unsupportedTier(tier.rawValue)
}
for language in keptLanguages where !VPhoneSystemTrim.isLanguageIdentifier(language) {
throw VPhoneSystemTrimError.invalidLanguage(language)
}
let removesLanguages = tier >= .standard
self.init(
uncheckedTier: tier,
listVersion: VPhoneSystemTrim.listVersion,
keptLanguages: removesLanguages ? Array(Set(keptLanguages + ["en"])).sorted() : [],
)
}
private init(uncheckedTier tier: VPhoneSystemTrimTier, listVersion: Int, keptLanguages: [String]) {
self.tier = tier
self.listVersion = listVersion
self.keptLanguages = keptLanguages
}
/// `none`, `conservative/1`, `standard/1/en,zh,zh-Hans`.
public var keyValue: String {
guard tier != .none else { return "none" }
var parts = [tier.rawValue, String(listVersion)]
if !keptLanguages.isEmpty {
parts.append(keptLanguages.joined(separator: ","))
}
return parts.joined(separator: "/")
}
/// Reads a ``keyValue`` back. Only the current list version can be
/// applied; an older one is still a valid key, but no longer a trim.
public init(keyValue: String) throws {
let parts = keyValue.split(separator: "/", omittingEmptySubsequences: false).map(String.init)
guard let tier = VPhoneSystemTrimTier(rawValue: parts[0]) else {
throw VPhoneSystemTrimError.unknownTier(keyValue)
}
if tier == .none {
guard parts.count == 1 else { throw VPhoneSystemTrimError.unknownTier(keyValue) }
self = .none
return
}
guard parts.count >= 2, let version = Int(parts[1]) else {
throw VPhoneSystemTrimError.unknownTier(keyValue)
}
guard version == VPhoneSystemTrim.listVersion else {
throw VPhoneSystemTrimError.unavailableListVersion(version)
}
let languages = parts.count > 2 ? parts[2].split(separator: ",").map(String.init) : []
try self.init(tier: tier, keptLanguages: languages)
guard self.keyValue == keyValue else {
throw VPhoneSystemTrimError.unknownTier(keyValue)
}
}
/// The tier named by a `trimTier` value, whatever its list version.
public static func tier(ofKeyValue value: String) -> VPhoneSystemTrimTier? {
value.split(separator: "/", maxSplits: 1).first.flatMap { VPhoneSystemTrimTier(rawValue: String($0)) }
}
/// Whether a machine whose steps record `recorded` may take this trim.
/// A trim cannot be undone, so only `none` to anything, the same trim
/// again (which deletes whatever is left), or conservative to a heavier
/// tier, which contains it.
public func canFollow(recorded: String) -> Bool {
if recorded == "none" || recorded == keyValue {
return true
}
guard let previous = Self.tier(ofKeyValue: recorded) else { return false }
return previous == .conservative && tier > .conservative
}
/// The entries this trim deletes, in the order they are applied.
public var entries: [VPhoneSystemTrimEntry] {
VPhoneSystemTrim.entries(keptLanguages: keptLanguages).filter { tier != .none && $0.tier <= tier }
}
/// Whether deleting `relative` (a path on the System volume) is part of
/// this trim: one of its `.item` paths, or a direct child its entry
/// selects. Everything the trim deletes passes this check first.
public func permits(_ relative: String) -> Bool {
guard VPhoneSystemTrim.isSafeRelativePath(relative) else { return false }
for entry in entries {
switch entry.selection {
case .item:
if relative == entry.path {
return true
}
case .contents, .languageBundles:
let prefix = entry.path + "/"
guard relative.hasPrefix(prefix) else { continue }
let child = String(relative.dropFirst(prefix.count))
if entry.selects(child: child) {
return true
}
}
}
return false
}
}
// MARK: - Lists
public enum VPhoneSystemTrim {
/// Raised whenever an entry is added, removed or changes what it
/// selects. Part of ``VPhoneSystemTrimSpec/keyValue``.
public static let listVersion = 1
/// The languages the standard tier keeps by default: English, and the
/// Simplified Chinese bundle with the `zh` bundle it shares data with.
public static let defaultKeptLanguages = ["en", "zh-Hans", "zh"]
/// List version 1, measured on iPhone17,3 iOS 27.0 (24A435) and booted
/// after deletion (see `Research/Host/machine_templates.md`). Never on
/// the list: the dyld shared cache and its `.symbols` (CFW's cache
/// patcher resolves symbols from it), ML models, `/Applications`.
static func entries(keptLanguages: [String]) -> [VPhoneSystemTrimEntry] {
[
VPhoneSystemTrimEntry(
path: "usr/standalone/update",
selection: .contents,
tier: .conservative,
note: "software-update ramdisk and baseband firmware; a VM has no baseband and OTA is blocked",
),
VPhoneSystemTrimEntry(
path: "System/Library/PreinstalledAssetsV2/RequiredByOs/com_apple_MobileAsset_SharingDeviceAssets",
selection: .item,
tier: .standard,
note: "AirPods and Beats pairing artwork",
),
VPhoneSystemTrimEntry(
path: "System/Library/NanoTimeKit/FaceBundles",
selection: .contents,
tier: .standard,
note: "Apple Watch faces; a VM pairs no watch",
),
VPhoneSystemTrimEntry(
path: "System/Library/LinguisticData",
selection: .languageBundles(prefix: "RequiredAssets_", suffix: ".bundle", keeping: keptLanguages),
tier: .standard,
note: "linguistic data of languages not kept",
),
]
}
/// A file on the System volume that only an iOS System volume has,
/// checked before anything is deleted.
public static let systemVolumeMarker = "System/Library/CoreServices/SystemVersion.plist"
// MARK: Path rules
/// Non-empty, relative, no empty, `.` or `..` component, no NUL.
public static func isSafeRelativePath(_ path: String) -> Bool {
guard !path.isEmpty, !path.hasPrefix("/"), !path.contains("\0") else { return false }
return path.split(separator: "/", omittingEmptySubsequences: false).allSatisfy {
isSingleComponent(String($0))
}
}
static func isSingleComponent(_ name: String) -> Bool {
!name.isEmpty && name != "." && name != ".." && !name.contains("/") && !name.contains("\0")
}
/// `en`, `zh-Hans`, `pt_BR`: letters, digits, `-` and `_`, up to 16.
public static func isLanguageIdentifier(_ text: String) -> Bool {
(1 ... 16).contains(text.utf8.count) && text.utf8.allSatisfy { byte in
(byte >= 0x30 && byte <= 0x39) || (byte >= 0x41 && byte <= 0x5A)
|| (byte >= 0x61 && byte <= 0x7A) || byte == 0x2D || byte == 0x5F
}
}
}
// MARK: - Applying
/// What a trim deleted from one entry.
public struct VPhoneSystemTrimEntryResult: Codable, Equatable, Sendable {
public var path: String
/// Names deleted: the item itself, or the selected children.
public var removed: [String]
/// Allocated bytes of what was deleted (`st_blocks`), counting a file
/// with more than one hard link as nothing.
public var bytes: UInt64
/// The entry's path did not exist (already trimmed, or another release).
public var absent: Bool
}
public struct VPhoneSystemTrimResult: Codable, Equatable, Sendable {
public var trim: String
public var entries: [VPhoneSystemTrimEntryResult]
public var bytes: UInt64 {
entries.reduce(0) { $0 + $1.bytes }
}
public init(trim: String, entries: [VPhoneSystemTrimEntryResult]) {
self.trim = trim
self.entries = entries
}
private enum CodingKeys: String, CodingKey {
case trim, entries, bytes
}
public init(from decoder: any Decoder) throws {
let container = try decoder.container(keyedBy: CodingKeys.self)
trim = try container.decode(String.self, forKey: .trim)
entries = try container.decode([VPhoneSystemTrimEntryResult].self, forKey: .entries)
}
/// With the total, for callers that read only that.
public func encode(to encoder: any Encoder) throws {
var container = encoder.container(keyedBy: CodingKeys.self)
try container.encode(trim, forKey: .trim)
try container.encode(entries, forKey: .entries)
try container.encode(bytes, forKey: .bytes)
}
}
public extension VPhoneSystemTrimSpec {
/// Deletes this trim from a System volume opened at `root` (the mounted
/// volume's root, by descriptor). Nothing is followed: every path is
/// walked with `O_NOFOLLOW` and refused if it passes through a symbolic
/// link or leaves the volume, a link is deleted as a link, and each
/// deletion must be ``permits(_:)``-ed first. Refused outright when
/// `root` is not an iOS System volume.
func apply(to root: VPhoneConfinedDirectory, log: (String) -> Void = { _ in }) throws -> VPhoneSystemTrimResult {
guard (try? root.isRegularFile(VPhoneSystemTrim.systemVolumeMarker)) == true else {
throw VPhoneSystemTrimError.notSystemVolume
}
var results: [VPhoneSystemTrimEntryResult] = []
for entry in entries {
var result = VPhoneSystemTrimEntryResult(path: entry.path, removed: [], bytes: 0, absent: false)
switch entry.selection {
case .item:
guard try root.exists(entry.path) else {
result.absent = true
break
}
guard permits(entry.path) else { throw VPhoneSystemTrimError.notPermitted(entry.path) }
result.bytes = try root.removeItem(entry.path)
result.removed = [(entry.path as NSString).lastPathComponent]
case .contents, .languageBundles:
let folder: VPhoneConfinedDirectory
do {
folder = try root.directory(entry.path)
} catch VPhoneConfinedDirectoryError.missing {
result.absent = true
break
}
for child in try folder.entries() where entry.selects(child: child) {
let relative = "\(entry.path)/\(child)"
guard permits(relative) else { throw VPhoneSystemTrimError.notPermitted(relative) }
result.bytes += try folder.removeItem(child)
result.removed.append(child)
}
}
log(Self.describe(result))
results.append(result)
}
return VPhoneSystemTrimResult(trim: keyValue, entries: results)
}
static func describe(_ result: VPhoneSystemTrimEntryResult) -> String {
if result.absent {
return "\(result.path): not present"
}
let count = result.removed.count
return "\(result.path): removed \(count) item\(count == 1 ? "" : "s"), \(VPhoneSystemTrim.formatBytes(result.bytes))"
}
}
public extension VPhoneSystemTrim {
/// `353.2 MB`, decimal like the rest of the CLI's sizes.
static func formatBytes(_ bytes: UInt64) -> String {
if bytes >= 1_000_000_000 {
return String(format: "%.2f GB", Double(bytes) / 1_000_000_000)
}
return String(format: "%.1f MB", Double(bytes) / 1_000_000)
}
}
// MARK: - Disk layout
/// Reading `diskutil image attach` and `diskutil` output to find a guest
/// image's System volume by its APFS role, not by slice number.
public enum VPhoneGuestDiskLayout {
/// The attached image's whole disk and its APFS physical store, from
/// `diskutil image attach -noMount` output: one `<device>\t<content>` line
/// per device (`/dev/disk8 \tGUID_partition_scheme`,
/// `/dev/disk8s1\tApple_APFS`), then the synthesized container's own
/// lines (`Apple_APFS_Container`, `Apple_APFS_Volume`), which are neither
/// and may also come first.
public static func attachedDisks(fromAttachOutput output: String) -> (wholeDisk: String?, store: String?) {
let devices = output.split(whereSeparator: \.isNewline).compactMap { line -> (device: String, type: String)? in
let fields = line.split(whereSeparator: \.isWhitespace)
guard fields.count >= 2, fields[0].hasPrefix("/dev/disk") else { return nil }
return (String(fields[0].dropFirst("/dev/".count)), String(fields[1]))
}
let store = devices.first(where: { $0.type == "Apple_APFS" })?.device
let whole = devices.first(where: { $0.type == "GUID_partition_scheme" })?.device
?? store.flatMap { device in
device.range(of: "s", options: .backwards).map { String(device[..<$0.lowerBound]) }
}
return (whole, store)
}
/// The device of the one volume with the `System` role in `container`,
/// from `diskutil apfs list -plist <container>`, after checking the
/// container sits on `physicalStore` (the disk just attached, not
/// another container that happens to have the same number).
public static func systemVolume(fromAPFSList data: Data, container: String, physicalStore: String) throws -> String {
guard
let plist = try? PropertyListSerialization.propertyList(from: data, format: nil) as? [String: Any],
let containers = plist["Containers"] as? [[String: Any]],
let entry = containers.first(where: { $0["ContainerReference"] as? String == container }),
let stores = entry["PhysicalStores"] as? [[String: Any]],
stores.contains(where: { $0["DeviceIdentifier"] as? String == physicalStore }),
let volumes = entry["Volumes"] as? [[String: Any]]
else {
throw VPhoneSystemTrimError.layout("the APFS container \(container) is not on the attached disk \(physicalStore)")
}
let systems = volumes.filter { ($0["Roles"] as? [String])?.contains("System") == true }
guard systems.count == 1, let device = systems[0]["DeviceIdentifier"] as? String,
device.hasPrefix("\(container)s"), isDeviceName(device)
else {
throw VPhoneSystemTrimError.layout("container \(container) has \(systems.count) System-role volumes, not one")
}
return device
}
/// `disk12s1`.
public static func isDeviceName(_ text: String) -> Bool {
text.range(of: #"^disk[0-9]+(s[0-9]+)?$"#, options: .regularExpression) != nil
}
}
// MARK: - Error
public enum VPhoneSystemTrimError: Error, Equatable {
case unknownTier(String)
case unsupportedTier(String)
case invalidLanguage(String)
case languagesUnused(String)
case unavailableListVersion(Int)
case notSystemVolume
case notPermitted(String)
case layout(String)
case downgrade(machine: String, recorded: String, requested: String)
case clonedFromTemplate(machine: String, template: String)
}
extension VPhoneSystemTrimError: CustomStringConvertible, LocalizedError {
public var description: String {
switch self {
case let .unknownTier(text):
"'\(text)' is not a trim tier. Use none, conservative or standard."
case let .unsupportedTier(tier):
"Trim tier \(tier) is reserved and not supported yet: it has not been validated on a guest. Use none, conservative or standard."
case let .invalidLanguage(text):
"'\(text)' is not a language identifier (letters, digits, - and _, such as en or zh-Hans)."
case let .languagesUnused(tier):
"--keep-languages applies to the standard tier, which removes language data; \(tier) removes none."
case let .unavailableListVersion(version):
"Trim list version \(version) is not this vphone-cli's (\(VPhoneSystemTrim.listVersion)); it can no longer be applied."
case .notSystemVolume:
"The mounted volume is not an iOS System volume (no \(VPhoneSystemTrim.systemVolumeMarker)). Nothing was deleted."
case let .notPermitted(path):
"Refusing to delete \(path): it is not on the trim list."
case let .layout(reason):
"Cannot find the guest's System volume: \(reason)."
case let .downgrade(machine, recorded, requested):
"VM '\(machine)' is already trimmed (\(recorded)); a trim cannot be undone or narrowed, so it cannot take \(requested). Build another template for that."
case let .clonedFromTemplate(machine, template):
"VM '\(machine)' was cloned from template \(template) and shares its system files; trimming it would free nothing. Trim a template build instead."
}
}
public var errorDescription: String? {
description
}
}