Play your own Switch games on iPhone/iPad — one-click macOS app, no terminal. | 把 Switch 游戏装进 iPhone:图形界面一键构建,不用命令行。Bring your own game.
Swift apple-siliconcustom-formathomebrewiosipaipadipadosiphonemetalnative-portnintendo-switchnxnativeromfsswitch-games
import Foundation
import CryptoKit
// The launcher's self-update, the parts that decide what may be installed and when. `AppUpdateStore` (NXModel) drives it;
// everything here works on data and paths it is given, so the tests run it on bundles in a temporary folder, never on the
// running app or the network.
//
// The rules:
// - What is installed is what GitHub says the release is: the zip's SHA-256 matches the asset's `digest`
// ("sha256:<hex>", in the release API since 2025), and the app inside it carries the running app's bundle
// identifier, an executable and the release's version. An automatic install also needs the digest to be
// there; the Update button, pressed by hand, still installs a release without one (older releases have none).
// - Only a released copy replaces itself: a launcher built from the repository (swift run, a bundle assembled in
// frontend/, an Xcode build) keeps the developer's build in place.
// - Never while a build runs: the swap ends with a relaunch (exit), and a build is a process group of the app's.
package enum AppUpdate {
/// The latest release, as the check found it.
package struct Release: Equatable {
package init(tag: String, url: String, digest: String?, notes: String = "") {
self.tag = tag; self.url = url; self.digest = digest; self.notes = notes
}
package let tag: String
package let url: String
package let digest: String? // "sha256:<hex>"; nil when the API gave none
/// The release body, shown by the update sheet before anything is downloaded: "a new version
/// is out" alone told a user nothing about what they would get.
package var notes: String = ""
}
/// A release downloaded, verified and unpacked, waiting to be swapped in.
package struct Staged: Equatable {
package init(release: Release, app: URL) { self.release = release; self.app = app }
package let release: Release
package let app: URL
}
// ---- What was downloaded ----
package enum DigestCheck: Equatable { case match, mismatch, missing }
/// The SHA-256 of a file, as lowercase hex, read in pieces (the zip is tens of megabytes).
package static func sha256(of file: URL) -> String? {
guard let handle = try? FileHandle(forReadingFrom: file) else { return nil }
defer { try? handle.close() }
var hasher = SHA256()
while true {
let chunk = handle.readData(ofLength: 1 << 20)
if chunk.isEmpty { break }
hasher.update(data: chunk)
}
return hasher.finalize().map { String(format: "%02x", $0) }.joined()
}
/// The file against the asset's digest. A digest in any other algorithm, or none, counts as missing: there is
/// nothing to compare with, which an automatic install refuses.
package static func checkDigest(_ file: URL, expected: String?) -> DigestCheck {
guard let expected, expected.lowercased().hasPrefix("sha256:") else { return .missing }
let want = expected.dropFirst("sha256:".count).trimmingCharacters(in: .whitespaces).lowercased()
guard want.count == 64, let have = sha256(of: file) else { return want.isEmpty ? .missing : .mismatch }
return have == want ? .match : .mismatch
}
package enum BundleProblem: Error, Equatable { case noInfo, wrongIdentifier, noExecutable, wrongVersion }
/// Whether `app` is an NX2Apple launcher of the release `tag`: the running app's bundle identifier (a zip of
/// something else must not take its place), an executable where its Info.plist says, and the release's version
/// (the release workflow writes the tag into the plist; another number would be a different build).
package static func bundleProblem(_ app: URL, expectedID: String, tag: String) -> BundleProblem? {
let contents = app.appendingPathComponent("Contents")
guard let data = try? Data(contentsOf: contents.appendingPathComponent("Info.plist")),
let info = try? PropertyListSerialization.propertyList(from: data, format: nil) as? [String: Any]
else { return .noInfo }
guard !expectedID.isEmpty, info["CFBundleIdentifier"] as? String == expectedID else { return .wrongIdentifier }
guard let exe = info["CFBundleExecutable"] as? String, !exe.isEmpty, !exe.contains("/"),
FileManager.default.isExecutableFile(atPath: contents.appendingPathComponent("MacOS/" + exe).path)
else { return .noExecutable }
let version = tag.hasPrefix("v") ? String(tag.dropFirst()) : tag
guard info["CFBundleShortVersionString"] as? String == version else { return .wrongVersion }
return nil
}
// ---- What the running macOS can open ----
/// "26.6" or "26.6.1" as an OS version; nil for anything else.
package static func parseOSVersion(_ s: String) -> OperatingSystemVersion? {
let n = s.trimmingCharacters(in: .whitespaces).split(separator: ".", omittingEmptySubsequences: false).map { Int($0) }
guard (1...3).contains(n.count), n.allSatisfy({ $0 != nil && $0! >= 0 }) else { return nil }
return OperatingSystemVersion(majorVersion: n[0]!, minorVersion: n.count > 1 ? n[1]! : 0, patchVersion: n.count > 2 ? n[2]! : 0)
}
/// `a` is older than `b`, field by field (major, minor, patch).
package static func isOlder(_ a: OperatingSystemVersion, than b: OperatingSystemVersion) -> Bool {
(a.majorVersion, a.minorVersion, a.patchVersion) < (b.majorVersion, b.minorVersion, b.patchVersion)
}
package static func describe(_ v: OperatingSystemVersion) -> String {
v.patchVersion == 0 ? "\(v.majorVersion).\(v.minorVersion)" : "\(v.majorVersion).\(v.minorVersion).\(v.patchVersion)"
}
/// The staged app's `LSMinimumSystemVersion`, as written ("26.6"), when it is above `running`: the release cannot be
/// opened on this Mac, so it must not replace the launcher that can. nil when it opens here, or names no minimum
/// (macOS then applies none) or one that cannot be read (the release workflow writes it; an unreadable value is
/// not a reason to keep a Mac from updating).
package static func minimumOSAbove(_ running: OperatingSystemVersion, app: URL) -> String? {
guard let data = try? Data(contentsOf: app.appendingPathComponent("Contents/Info.plist")),
let info = try? PropertyListSerialization.propertyList(from: data, format: nil) as? [String: Any],
let text = info["LSMinimumSystemVersion"] as? String, let min = parseOSVersion(text)
else { return nil }
return isOlder(running, than: min) ? describe(min) : nil
}
// ---- What may replace itself ----
package enum Installability: Equatable {
case ok
case developer // built from the repository: never replaces itself
case readOnly // a released copy that cannot be replaced where it is (translocated, or a folder without write access)
}
/// Whether the launcher at `bundle` may replace itself. A released copy is an `.app` whose Info.plist has a bundle
/// identifier and, as its version, this binary's own release number (the release workflow stops when the two
/// differ), and which is not where a developer's build sits: in SwiftPM's .build, Xcode's DerivedData, or beside
/// the Package.swift it was built from (frontend/NX2Apple.app, which the README's own recipe makes). `swift run`
/// runs a bare executable with no bundle at all.
package static func installability(_ bundle: URL, appVersion: String) -> Installability {
let path = bundle.standardizedFileURL.path
guard bundle.pathExtension == "app" else { return .developer }
let parts = bundle.standardizedFileURL.pathComponents
if parts.contains(".build") || parts.contains("DerivedData") { return .developer }
let parent = bundle.standardizedFileURL.deletingLastPathComponent()
if FileManager.default.fileExists(atPath: parent.appendingPathComponent("Package.swift").path) { return .developer }
guard isReleaseVersion(appVersion),
let data = try? Data(contentsOf: bundle.appendingPathComponent("Contents/Info.plist")),
let info = try? PropertyListSerialization.propertyList(from: data, format: nil) as? [String: Any],
let id = info["CFBundleIdentifier"] as? String, !id.isEmpty,
info["CFBundleShortVersionString"] as? String == appVersion
else { return .developer }
// Gatekeeper runs a quarantined app opened from Downloads from a read-only copy: the swap cannot reach the real one
if path.contains("/AppTranslocation/") { return .readOnly }
if !FileManager.default.isWritableFile(atPath: parent.path) { return .readOnly }
return .ok
}
/// "1.2.3": digits and dots, nothing else (a dev build might say "dev", "0.0.0-local" or nothing).
package static func isReleaseVersion(_ v: String) -> Bool {
let parts = v.split(separator: ".", omittingEmptySubsequences: false)
return parts.count >= 2 && parts.allSatisfy { !$0.isEmpty && $0.allSatisfy(\.isASCII) && $0.allSatisfy(\.isNumber) }
}
// ---- When ----
package enum InstallError: Error, Equatable { case buildRunning, failed(String) }
/// Swap `staged` in at `current`: copied in beside it first (from there on every step stays on one volume), then
/// exchanged with it in one replace, so a failure anywhere leaves a working app at `current`. The old bundle goes
/// to the Trash (`trashOld`; the tests remove it instead), and the new one loses the quarantine flag, so its first
/// launch shows no Gatekeeper prompt (the release is ad-hoc signed, not notarized).
///
/// Refused while a build runs: the caller relaunches (or the app is quitting), and either ends the build's process group.
/// Where the staged release goes: its own bundle name when it differs from the running copy's,
/// else the current URL.
///
/// The two-name case is a rename era (nxnative → NS Port Builder → NX2Apple). Replacing in place
/// would keep the old folder's name for ever: the app inside is the new version, but the
/// Finder, the Dock and /Applications keep saying the old name, which read as "the update did
/// not happen" (a 0.4.6 install updated to 0.4.8 and still saw NS Port Builder). Under the new
/// name the old bundle is removed; the Dock entry pointing at it goes stale once, which a log
/// line names — the alternative was the old name for ever.
package static func installTarget(for staged: URL, current: URL) -> URL {
staged.lastPathComponent == current.lastPathComponent
? current
: current.deletingLastPathComponent().appendingPathComponent(staged.lastPathComponent)
}
/// Install the staged app and return where it ended up (the caller relaunches that path).
package static func install(_ staged: URL, over current: URL, buildRunning: Bool, trashOld: Bool = true,
runner: ProcessRunner = SystemProcessRunner()) throws -> URL {
guard !buildRunning else { throw InstallError.buildRunning }
let fm = FileManager.default
let dir = current.deletingLastPathComponent()
let target = installTarget(for: staged, current: current)
if target != current {
// A rename: place the staged bundle under its own name, then retire the old-named one.
// The running copy is trashed last — on macOS a running executable survives the removal
// of its bundle (the kernel holds the vnode), and the quit-time path runs this as the
// app is exiting anyway.
try? fm.removeItem(at: target)
try fm.copyItem(at: staged, to: target)
clearQuarantine(target, runner: runner)
if trashOld { try? fm.trashItem(at: current, resultingItemURL: nil) }
return target
}
let name = current.deletingPathExtension().lastPathComponent
let incoming = dir.appendingPathComponent(name + " (new).app")
let backupName = name + " (old).app"
try? fm.removeItem(at: incoming)
try? fm.removeItem(at: dir.appendingPathComponent(backupName))
do {
try fm.copyItem(at: staged, to: incoming)
let placed = try fm.replaceItemAt(current, withItemAt: incoming, backupItemName: backupName, options: [.withoutDeletingBackupItem])
let backup = dir.appendingPathComponent(backupName)
if fm.fileExists(atPath: backup.path) {
if trashOld { try? fm.trashItem(at: backup, resultingItemURL: nil) } else { try? fm.removeItem(at: backup) }
}
clearQuarantine(placed ?? current, runner: runner)
return current
} catch {
try? fm.removeItem(at: incoming)
throw InstallError.failed(error.localizedDescription)
}
}
/// The shell script behind `relaunch`: wait until `$1` (a pid) has exited, at most `$3` ticks of 0.2 s,
/// then open `$2` with `$4`. The paths arrive as arguments, never spliced into the script, so spaces and
/// quotes in them are safe.
package static let relaunchScript = """
n=0
while kill -0 "$1" 2>/dev/null && [ "$n" -lt "$3" ]; do sleep 0.2; n=$((n+1)); done
sleep 0.5
exec "$4" "$2"
"""
/// Start the new copy once this one is gone. `NSWorkspace.openApplication` cannot do it while the old
/// instance runs: LaunchServices finds the same bundle id and only activates that instance. So a detached
/// shell waits for the pid to exit, then runs `open`. The caller terminates the app right after.
@discardableResult
package static func relaunch(_ app: URL, afterExitOf pid: Int32 = ProcessInfo.processInfo.processIdentifier,
timeout: TimeInterval = 30, opener: String = "/usr/bin/open") -> Bool {
let p = Process()
p.executableURL = URL(fileURLWithPath: "/bin/sh")
p.arguments = ["-c", relaunchScript, "sh", String(pid), app.path, String(Int(timeout / 0.2)), opener]
p.standardInput = FileHandle.nullDevice
p.standardOutput = FileHandle.nullDevice
p.standardError = FileHandle.nullDevice
do { try p.run(); return true } catch { return false }
}
private static func clearQuarantine(_ app: URL, runner: ProcessRunner) {
_ = runner.capture(ProcessLaunch(executable: "/usr/bin/xattr", arguments: ["-dr", "com.apple.quarantine", app.path]))
}
// ---- Which release is the latest ----
/// The download names this build accepts, newest first. Every release must carry at least one of
/// them or an install from that era cannot update itself: NX2Apple is current, nxnative is for
/// installs from before the rename to NX2Apple, NS-Port-Builder for installs before that.
package static let assetNames = ["NX2Apple-macOS-arm64.zip", "nxnative-macOS-arm64.zip", "NS-Port-Builder-macOS-arm64.zip"]
/// `tag` ("v0.4.10") is a later version than `current` ("0.4.8"), compared number by number.
package static func isNewer(_ tag: String, than current: String) -> Bool {
func nums(_ s: String) -> [Int] { s.split(separator: ".").map { Int($0.filter { $0.isNumber }) ?? 0 } }
let a = nums(tag), b = nums(current)
for i in 0..<max(a.count, b.count) {
let x = i < a.count ? a[i] : 0, y = i < b.count ? b[i] : 0
if x != y { return x > y }
}
return false
}
/// The release's asset this app installs, with its digest: NX2Apple-macOS-arm64.zip, or the zip under an older
/// name (releases from before each rename).
package static func release(fromJSON obj: [String: Any]) -> Release? {
let tag = obj["tag_name"] as? String ?? ""
guard let assets = obj["assets"] as? [[String: Any]] else { return nil }
for name in assetNames {
for a in assets where (a["name"] as? String) == name {
if let u = a["browser_download_url"] as? String { return Release(tag: tag, url: u, digest: a["digest"] as? String) }
}
}
return nil
}
/// What the check of the latest release found.
package enum Check: Equatable {
/// The answer never came (no network, a timeout).
case unreachable
case upToDate
/// A newer release exists, with the asset this app installs and the notes.
case found(Release)
/// A newer release exists but carries no download this build can name. That is NOT "up to date": it is the
/// difference between a user who updates and one who sits on 0.4.6 for ever, because 0.4.6 and 0.4.7 look for
/// exactly "NS-Port-Builder-macOS-arm64.zip" and would report "up to date" and stop.
case noAsset(tag: String)
}
/// The answer of GitHub's "latest release" call (`nil` when there was none) against the running version.
package static func check(latest data: Data?, current: String) -> Check {
guard let data else { return .unreachable }
guard let obj = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else { return .upToDate }
let tag = obj["tag_name"] as? String ?? ""
guard isNewer(tag, than: current) else { return .upToDate }
guard var r = release(fromJSON: obj) else { return .noAsset(tag: tag) }
r.notes = (obj["body"] as? String) ?? ""
return .found(r)
}
// ---- What was downloaded, to a staged app ----
/// Why staging stopped: each case is the localization key of its message (a format with the release's tag).
package enum StageFailure: Error, Equatable {
case network, noDigest, mismatch, unpack, notOurApp
/// The release's LSMinimumSystemVersion is above the running macOS (the string is that minimum).
case needsNewerMacOS(String)
package var key: String {
switch self {
case .network: return "app.stageNetFail"
case .noDigest: return "app.noDigest"
case .mismatch: return "app.digestMismatch"
case .unpack: return "app.unpackFail"
case .notOurApp: return "app.notOurApp"
case .needsNewerMacOS: return "app.needsNewerMacOS"
}
}
}
/// The folder staging works in, in the temporary directory and emptied first.
package static func freshStagingRoot(in temporary: URL = FileManager.default.temporaryDirectory) -> URL {
let fm = FileManager.default
let root = temporary.appendingPathComponent("nspb-update", isDirectory: true)
try? fm.removeItem(at: root)
try? fm.createDirectory(at: root, withIntermediateDirectories: true)
return root
}
/// A downloaded zip to a staged app: its digest first, then unzip (ditto, as the release was packed), then the app inside.
package static func stage(zip: URL, release: Release, in root: URL, expectedID: String, requireDigest: Bool,
runningOS: OperatingSystemVersion = ProcessInfo.processInfo.operatingSystemVersion,
runner: ProcessRunner = SystemProcessRunner()) -> Result<Staged, StageFailure> {
let fm = FileManager.default
switch checkDigest(zip, expected: release.digest) {
case .match: break
case .mismatch: try? fm.removeItem(at: zip); return .failure(.mismatch)
case .missing: if requireDigest { try? fm.removeItem(at: zip); return .failure(.noDigest) }
}
let dir = root.appendingPathComponent("app", isDirectory: true)
try? fm.removeItem(at: dir)
try? fm.createDirectory(at: dir, withIntermediateDirectories: true)
let unzip = runner.capture(ProcessLaunch(executable: "/usr/bin/ditto", arguments: ["-x", "-k", zip.path, dir.path]))
guard unzip.started else { return .failure(.unpack) }
try? fm.removeItem(at: zip)
// The archive holds one app: NX2Apple.app, or the bundle under an older name in a release from before a rename
guard unzip.status == 0,
let app = ((try? fm.contentsOfDirectory(at: dir, includingPropertiesForKeys: nil)) ?? []).first(where: { $0.pathExtension == "app" })
else { return .failure(.unpack) }
if bundleProblem(app, expectedID: expectedID, tag: release.tag) != nil {
try? fm.removeItem(at: dir)
return .failure(.notOurApp)
}
// Not a release this Mac cannot open: it would replace a launcher that works with an app that will not start
if let min = minimumOSAbove(runningOS, app: app) {
try? fm.removeItem(at: dir)
return .failure(.needsNewerMacOS(min))
}
return .success(Staged(release: release, app: app))
}
}