Run a virtual iPhone on an Apple Silicon Mac.
Swift
import Foundation
// MARK: - VPhoneFirmwareSupport
/// How much confidence this project has in one downloadable iPhone firmware.
///
/// `supported` means the compatibility guide's "Tested Environments" table records a boot on
/// that exact version/build; `notTested` means Apple still serves it but nobody
/// wrote a row for it. `unsupported` is never a table verdict — it is the
/// prefix the selector puts on "nothing matched", and it exists here only
/// because it shares the colour table with the other two.
public enum VPhoneFirmwareSupport: String, Sendable, CaseIterable {
case supported = "Supported"
case notTested = "Not Tested"
case unsupported = "Unsupported"
/// SGR introducer for this verdict. Green/amber/red, matching the palette
/// the rest of the tool uses for status.
var ansiColor: String {
switch self {
case .supported: "\u{1B}[32m"
case .notTested: "\u{1B}[33m"
case .unsupported: "\u{1B}[31m"
}
}
}
// MARK: - VPhoneStatusStyle
/// Whether ANSI colour may be written to one particular stream.
///
/// Three checks that have to stay together, and the order matters:
///
/// 1. `NO_COLOR` set to a non-empty value wins over everything.
/// 2. Otherwise colour follows `isatty` **of this stream**, not of the process.
/// 3. `CLICOLOR_FORCE=1` turns colour on even when the stream is a pipe.
///
/// The per-stream part is not a detail: the firmware listing styles stdout, the
/// selector's failure paths style stderr, and a run that pipes one and not the
/// other has to get a different answer for each. Getting this wrong means
/// escape codes land in a pipe, or colour disappears in a terminal.
public struct VPhoneStatusStyle: Sendable, Equatable {
public let isColored: Bool
public init(isColored: Bool) {
self.isColored = isColored
}
/// The policy above, resolved for one file descriptor.
public static func forStream(
_ fileDescriptor: Int32,
environment: [String: String] = ProcessInfo.processInfo.environment,
) -> VPhoneStatusStyle {
if let noColor = environment["NO_COLOR"], !noColor.isEmpty {
return VPhoneStatusStyle(isColored: false)
}
if isatty(fileDescriptor) != 0 {
return VPhoneStatusStyle(isColored: true)
}
return VPhoneStatusStyle(isColored: environment["CLICOLOR_FORCE"] == "1")
}
/// `status`, left-justified to `width` and only then wrapped in colour.
///
/// The padding goes *inside* the escape sequence. That is deliberate: it is
/// where the shell's Python put it, and it keeps the plain and coloured
/// renderings the same width on screen, so the STATUS column lines up in
/// both. Moving the padding outside would change every byte of the output.
public func render(_ status: VPhoneFirmwareSupport, width: Int = 0) -> String {
let text = VPhoneFirmwareMatrix.leftJustified(status.rawValue, width)
guard isColored else { return text }
return "\(status.ansiColor)\(text)\u{1B}[0m"
}
}
// MARK: - VPhoneFirmwareRelease
/// One downloadable restore image, as named by its own URL.
public struct VPhoneFirmwareRelease: Sendable, Hashable {
public let version: String
public let build: String
public let url: String
public init(version: String, build: String, url: String) {
self.version = version
self.build = build
self.url = url
}
}
// MARK: - VPhoneFirmwareBuildID
/// The (version, build) pair the compatibility table and the URL list are joined on.
public struct VPhoneFirmwareBuildID: Sendable, Hashable {
public let version: String
public let build: String
public init(version: String, build: String) {
self.version = version
self.build = build
}
}
// MARK: - VPhoneFirmwareListing
/// Result of the `--list` path.
public enum VPhoneFirmwareListing: Sendable, Equatable {
/// The rendered matrix. Goes to stdout; exit 0.
case matrix(String)
/// Nothing downloadable for the device. Goes to stderr; exit 1.
case nothingDownloadable(String)
}
// MARK: - VPhoneFirmwareSelection
/// Result of resolving a version/build selector against the download list.
public enum VPhoneFirmwareSelection: Sendable, Equatable {
/// One firmware and its verdict. Goes to stdout as `resolvedLine`; exit 0.
case selected(release: VPhoneFirmwareRelease, support: VPhoneFirmwareSupport)
/// A bare version that maps to several builds. Goes to stderr; exit 2 —
/// `fw_prepare.sh` forwards that 2 so a caller can tell "ambiguous" from
/// "no such firmware".
case ambiguous(String)
/// Nothing matched. Goes to stderr; exit 1.
case unmatched(String)
/// `version\tbuild\turl\tstatus`, which `fw_prepare.sh` reads back with
/// `IFS=$'\t' read -r`.
///
/// Plain even when the rest of the run is coloured. The shell echoes field
/// 4 through its own `style_status`, so an escape sequence here would be
/// wrapped in a second one.
public var resolvedLine: String? {
guard case let .selected(release, support) = self else { return nil }
return "\(release.version)\t\(release.build)\t\(release.url)\t\(support.rawValue)\n"
}
}
// MARK: - VPhoneFirmwareMatrix
/// The firmware support matrix: the compatibility guide's "Tested Environments" table joined
/// against the restore images Apple still serves.
///
/// This replaces the two Python heredocs that used to live inside
/// `scripts/fw_prepare.sh` (`list_firmwares` and `resolve_selector_from_downloads`).
/// They were 166 lines that duplicated the same three parsers — the Markdown
/// section scan, the URL scan, and the version sort — once each, so this is one
/// parser with two renderers on top of it.
public enum VPhoneFirmwareMatrix {
// MARK: Parsing
/// Every `(version, build)` the compatibility guide's "Tested Environments" section
/// records for `device`.
///
/// The section runs from the `## Tested Environments` heading to the next
/// `## ` heading. Inside it, any backticked `17,3_26.1_23B85` cell whose
/// device part equals `device` minus its `iPhone` prefix counts as tested;
/// the cloudOS column uses `26.1-23B85`, which cannot match. A missing
/// guide is not an error — it just means nothing is known to be tested.
public static func testedBuilds(readme: String?, device: String) -> Set<VPhoneFirmwareBuildID> {
guard let readme else { return [] }
let deviceSuffix = device.hasPrefix("iPhone")
? String(device.dropFirst("iPhone".count))
: device
guard let cell = try? NSRegularExpression(
pattern: "`(\\d+,\\d+)_([^_`]+)_([A-Za-z0-9]+)`",
) else { return [] }
var tested: Set<VPhoneFirmwareBuildID> = []
var inSection = false
for line in normalizedLines(of: readme) {
if line.hasPrefix("## Tested Environments") {
inSection = true
continue
}
if inSection, line.hasPrefix("## ") {
break
}
guard inSection else { continue }
for match in cell.matches(in: line, range: NSRange(line.startIndex..., in: line)) {
guard let device = group(1, of: match, in: line),
let version = group(2, of: match, in: line),
let build = group(3, of: match, in: line),
device == deviceSuffix
else { continue }
tested.insert(VPhoneFirmwareBuildID(version: version, build: build))
}
}
return tested
}
/// Every restore image for `device` named by the `ipsw download … --urls`
/// output, in the order the lines arrive and with duplicates dropped.
///
/// A line counts when it *ends* with `/<device>_<version>_<build>_Restore.ipsw`,
/// so the surrounding CDN path — which differs per release and is sometimes
/// a bare UUID — is ignored. An IPSW shared by several models names them
/// all, comma-separated (`iPad16,1,iPad16,2_…`); `device` may be any of them.
/// A few IPSWs carry a family name instead (`iPad_Pro_M4_…`), which
/// `sharedIPSWNames` maps to its models.
public static func releases(downloadURLs: String, device: String) -> [VPhoneFirmwareRelease] {
var models = "(?:[^/_]*,)?" + NSRegularExpression.escapedPattern(for: device) + "(?:,[^/_]*)?"
for (name, devices) in sharedIPSWNames where devices.contains(device) {
models = "(?:\(models)|\(NSRegularExpression.escapedPattern(for: name)))"
}
let pattern = "/(\(models)_([^_]+)_([A-Za-z0-9]+)_Restore\\.ipsw)$"
guard let name = try? NSRegularExpression(pattern: pattern) else { return [] }
var seen: Set<VPhoneFirmwareRelease> = []
var found: [VPhoneFirmwareRelease] = []
for rawLine in normalizedLines(of: downloadURLs) {
let line = rawLine.trimmingCharacters(in: .whitespacesAndNewlines)
guard let match = name.firstMatch(in: line, range: NSRange(line.startIndex..., in: line)),
let version = group(2, of: match, in: line),
let build = group(3, of: match, in: line)
else { continue }
let release = VPhoneFirmwareRelease(version: version, build: build, url: line)
if seen.insert(release).inserted {
found.append(release)
}
}
return found
}
/// IPSW names that name a device family rather than its models, and the
/// models each covers.
static let sharedIPSWNames: [String: [String]] = [
"iPad_Pro_M4": ["iPad16,3", "iPad16,4", "iPad16,5", "iPad16,6"],
]
/// The verdict for one release, given what the compatibility guide records.
public static func support(
of release: VPhoneFirmwareRelease,
tested: Set<VPhoneFirmwareBuildID>,
) -> VPhoneFirmwareSupport {
tested.contains(VPhoneFirmwareBuildID(version: release.version, build: release.build))
? .supported
: .notTested
}
// MARK: Rendering — the listing
/// The full `--list` report, rendered for a stream with `style`'s colour policy.
public static func listing(
device: String,
readme: String?,
downloadURLs: String,
style: VPhoneStatusStyle,
) -> VPhoneFirmwareListing {
let releases = releases(downloadURLs: downloadURLs, device: device)
guard !releases.isEmpty else {
return .nothingDownloadable("No downloadable IPSWs found for \(device)\n")
}
let tested = testedBuilds(readme: readme, device: device)
let rows = releases.sorted { isNewer($0, than: $1) }
var out = "Available downloadable IPSWs for \(device):\n"
out += "\n"
out += "Status: \(style.render(.supported, width: statusWidth))"
+ " \(style.render(.notTested, width: statusWidth))"
+ " \(style.render(.unsupported, width: statusWidth))\n"
out += "\n"
out += "\(leftJustified("VERSION", versionWidth)) \(leftJustified("BUILD", buildWidth)) STATUS\n"
for row in rows {
let status = support(of: row, tested: tested)
out += "\(leftJustified(row.version, versionWidth))"
+ " \(leftJustified(row.build, buildWidth))"
+ " \(style.render(status, width: statusWidth))\n"
}
return .matrix(out)
}
// MARK: Rendering — the selector
/// Resolve a version and/or build selector against the download list.
///
/// Empty strings mean "unconstrained", which is how the shell passes an
/// unset `IPHONE_VERSION`/`IPHONE_BUILD`. A bare version that matches more
/// than one build is reported as ambiguous rather than guessed at; anything
/// else resolves to the highest build that matched.
public static func selection(
device: String,
version: String,
build: String,
readme: String?,
downloadURLs: String,
style: VPhoneStatusStyle,
) -> VPhoneFirmwareSelection {
let matches = releases(downloadURLs: downloadURLs, device: device).filter {
(version.isEmpty || $0.version == version) && (build.isEmpty || $0.build == build)
}
guard !matches.isEmpty else {
let prefix = style.render(.unsupported)
let selector = if !version.isEmpty, !build.isEmpty {
"device=\(device) version=\(version) build=\(build)"
} else if !build.isEmpty {
"device=\(device) build=\(build)"
} else {
"device=\(device) version=\(version)"
}
return .unmatched("\(prefix): no downloadable IPSW matched \(selector)\n")
}
let tested = testedBuilds(readme: readme, device: device)
let byBuild = matches.sorted { hasHigherBuild($0, than: $1) }
if !version.isEmpty, build.isEmpty, Set(matches.map(\.build)).count > 1 {
var out = "Version \(version) is ambiguous for \(device); specify one of these builds:\n"
out += "\(leftJustified("BUILD", buildWidth)) STATUS\n"
for match in byBuild {
out += "\(leftJustified(match.build, buildWidth)) \(style.render(support(of: match, tested: tested)))\n"
}
return .ambiguous(out)
}
let selected = byBuild[0]
return .selected(release: selected, support: support(of: selected, tested: tested))
}
// MARK: Ordering
/// One dot-separated component of a version, compared the way the shell's
/// Python compared it: numerically where it parses as a number, textually
/// otherwise.
///
/// The Python built a tuple and let Python compare it, which *raises* on a
/// number-against-text comparison (`26.1` vs `26.beta`). Nothing Apple
/// serves produces that, and raising is not a behaviour worth porting, so
/// numbers sort before text here.
enum VersionPart: Comparable {
case number(Int)
case text(String)
static func < (lhs: VersionPart, rhs: VersionPart) -> Bool {
switch (lhs, rhs) {
case let (.number(l), .number(r)): l < r
case let (.text(l), .text(r)): codePointsAscending(l, r)
case (.number, .text): true
case (.text, .number): false
}
}
}
/// `"26.4.1"` → `[26, 4, 1]`. Shorter sorts before longer on a common
/// prefix, so `26.4` < `26.4.1`.
static func versionKey(_ version: String) -> [VersionPart] {
version.components(separatedBy: ".").map { part in
if let number = Int(part) {
.number(number)
} else {
.text(part)
}
}
}
/// Newest first: version descending, then build descending.
///
/// URL breaks the remaining ties. The Python had nothing there — it sorted
/// a `set`, so two rows sharing a version *and* a build came out in hash
/// order, which is to say a different order per run. That is not a
/// behaviour to reproduce, so the order here is total and reproducible.
static func isNewer(_ lhs: VPhoneFirmwareRelease, than rhs: VPhoneFirmwareRelease) -> Bool {
let (l, r) = (versionKey(lhs.version), versionKey(rhs.version))
for (lp, rp) in zip(l, r) where lp != rp {
return rp < lp
}
if l.count != r.count {
return r.count < l.count
}
return hasHigherBuild(lhs, than: rhs)
}
/// Build descending, URL descending as the tie-break.
static func hasHigherBuild(_ lhs: VPhoneFirmwareRelease, than rhs: VPhoneFirmwareRelease) -> Bool {
if lhs.build != rhs.build {
return codePointsAscending(rhs.build, lhs.build)
}
return codePointsAscending(rhs.url, lhs.url)
}
// MARK: Text helpers
static let versionWidth = 12
static let buildWidth = 10
static let statusWidth = 11
/// `String.padding(toLength:)` truncates; this does not, which is what the
/// `f"{value:<12}"` it replaces did. Width is counted in code points, again
/// to match.
static func leftJustified(_ text: String, _ width: Int) -> String {
let count = text.unicodeScalars.count
guard count < width else { return text }
return text + String(repeating: " ", count: width - count)
}
/// Code-point order, not Swift's canonical `String` ordering, because the
/// comparison it stands in for was Python's.
static func codePointsAscending(_ lhs: String, _ rhs: String) -> Bool {
var left = lhs.unicodeScalars.makeIterator()
var right = rhs.unicodeScalars.makeIterator()
while true {
switch (left.next(), right.next()) {
case (nil, nil): return false
case (nil, .some): return true
case (.some, nil): return false
case let (.some(l), .some(r)):
if l.value != r.value {
return l.value < r.value
}
}
}
}
/// Text-mode line splitting: CRLF and CR collapse to LF, and a trailing
/// newline does not produce a final empty line.
static func normalizedLines(of text: String) -> [String] {
var normalized = text.replacingOccurrences(of: "\r\n", with: "\n")
normalized = normalized.replacingOccurrences(of: "\r", with: "\n")
if normalized.hasSuffix("\n") {
normalized.removeLast()
}
if normalized.isEmpty {
return []
}
return normalized.components(separatedBy: "\n")
}
private static func group(_ index: Int, of match: NSTextCheckingResult, in text: String) -> String? {
guard let range = Range(match.range(at: index), in: text) else { return nil }
return String(text[range])
}
}
// MARK: - VPhoneFirmwareMatrixCommandLine
/// The two entry points `scripts/fw_prepare.sh` calls, including which stream
/// each half writes to and what it exits with.
///
/// Stream choice is load-bearing twice over. The listing styles **stdout**, so
/// `--list | less` gets plain text; every selector failure styles **stderr**,
/// so an error stays coloured even when the resolved URL is being captured in a
/// `$( … )`. Both are resolved independently, per stream.
public enum VPhoneFirmwareMatrixCommandLine {
/// Print the support matrix. 0 on success, 1 when the device has nothing
/// downloadable.
public static func list(
device: String,
readmePath: String,
downloadURLs: String,
environment: [String: String] = ProcessInfo.processInfo.environment,
stdout: FileHandle = .standardOutput,
stderr: FileHandle = .standardError,
) -> Int32 {
let readme = try? String(contentsOfFile: readmePath, encoding: .utf8)
switch VPhoneFirmwareMatrix.listing(
device: device,
readme: readme,
downloadURLs: downloadURLs,
style: .forStream(stdout.fileDescriptor, environment: environment),
) {
case let .matrix(text):
write(text, to: stdout)
return 0
case let .nothingDownloadable(text):
write(text, to: stderr)
return 1
}
}
/// Resolve a selector to `version\tbuild\turl\tstatus` on stdout. 0 on a
/// hit, 2 when a bare version is ambiguous, 1 when nothing matched.
public static func resolve(
device: String,
version: String,
build: String,
readmePath: String,
downloadURLs: String,
environment: [String: String] = ProcessInfo.processInfo.environment,
stdout: FileHandle = .standardOutput,
stderr: FileHandle = .standardError,
) -> Int32 {
let readme = try? String(contentsOfFile: readmePath, encoding: .utf8)
let selection = VPhoneFirmwareMatrix.selection(
device: device,
version: version,
build: build,
readme: readme,
downloadURLs: downloadURLs,
style: .forStream(stderr.fileDescriptor, environment: environment),
)
switch selection {
case .selected:
write(selection.resolvedLine ?? "", to: stdout)
return 0
case let .ambiguous(text):
write(text, to: stderr)
return 2
case let .unmatched(text):
write(text, to: stderr)
return 1
}
}
private static func write(_ text: String, to handle: FileHandle) {
guard !text.isEmpty else { return }
handle.write(Data(text.utf8))
}
}