Skip to content

Play your own Switch games on iPhone/iPad — one-click macOS app, no terminal. | 把 Switch 游戏装进 iPhone:图形界面一键构建,不用命令行。Bring your own game.

NSPB_ONBOARDING_FORCE=1 shows the real setup on a set-up Mac without leaving a trace

v0lumehi949eb59a716a
diff --git a/frontend/Onboarding.md b/frontend/Onboarding.md
index 03df3fd6..1048e583 100644
--- a/frontend/Onboarding.md
+++ b/frontend/Onboarding.md
@@ -21,6 +21,8 @@ NSPB_ONBOARDING_DEMO=noGames swift run
Set up later preserves an in-memory snapshot; Resume setup restores it. The mock persists nothing; the real driver does (below).
+`NSPB_ONBOARDING_FORCE=1 swift run` shows the real flow (the live driver, real detection) on launch even when setup is complete or marked done. It writes nothing until the player finishes or picks "Set up later": no `onboarding.completed`, step, platform or build target, and nothing is installed until an install action (Get Xcode, Finish setup, Retry) is pressed. Quitting in between leaves no trace.
+
## Wiring contract
`OnboardingView<Driver: OnboardingDriver>` observes a driver on the main actor. A real `ObservableObject` should publish `OnboardingState` as one value and implement these intents:
diff --git a/frontend/Sources/NSPortBuilder/ContentView.swift b/frontend/Sources/NSPortBuilder/ContentView.swift
index ffa12b77..e1aabdd9 100644
--- a/frontend/Sources/NSPortBuilder/ContentView.swift
+++ b/frontend/Sources/NSPortBuilder/ContentView.swift
@@ -2089,6 +2089,7 @@ final class BuildModel: ObservableObject {
/// Whether the xcode row asks for the iOS SDK. Always, as before, unless the guided setup stored a Mac-only choice
/// and builds are for the Mac: upstream no longer needs the iOS SDK for a Mac build (c464cb24).
nonisolated static func needsIOSPlatform(defaults: UserDefaults = .standard) -> Bool {
+ if OnboardingDefaults.sessionPlatform == "mac" { return false } // a forced run's choice, not stored yet
guard defaults.string(forKey: OnboardingDefaults.platform) == "mac" else { return true }
return (defaults.string(forKey: "buildTarget") ?? "ios") != "mac-app"
}
diff --git a/frontend/Sources/NSPortBuilder/LiveOnboardingDriver.swift b/frontend/Sources/NSPortBuilder/LiveOnboardingDriver.swift
index f48d9c7a..bb8b3cbd 100644
--- a/frontend/Sources/NSPortBuilder/LiveOnboardingDriver.swift
+++ b/frontend/Sources/NSPortBuilder/LiveOnboardingDriver.swift
@@ -3,6 +3,8 @@ import Combine
/// UserDefaults keys of the guided setup. `platform` is also read by `BuildModel.needsIOSPlatform`.
enum OnboardingDefaults {
+ /// An NSPB_ONBOARDING_FORCE run's platform choice, in memory only (nothing is stored until it finishes).
+ static var sessionPlatform: String?
static let completed = "onboarding.completed"
static let step = "onboarding.step"
static let platform = "onboarding.platform"
@@ -165,7 +167,9 @@ enum OnboardingLaunch {
/// Setup counts as complete when the tools are all present, a keys file is known and a games folder is set. A player
/// who has built a game already has all three in effect.
static func setupComplete(depsPresent: Bool, keysKnown: Bool, gamesKnown: Bool) -> Bool { depsPresent && keysKnown && gamesKnown }
- static func shouldShow(completed: Bool, setupComplete: Bool) -> Bool { !completed && !setupComplete }
+ /// `force` (NSPB_ONBOARDING_FORCE=1) shows it whatever the state.
+ static func shouldShow(completed: Bool, setupComplete: Bool, force: Bool = false) -> Bool { force || (!completed && !setupComplete) }
+ static func forced(_ environment: [String: String] = ProcessInfo.processInfo.environment) -> Bool { environment["NSPB_ONBOARDING_FORCE"] == "1" }
}
/// The real driver: the guided setup over the launcher's own `BuildModel` (detection and installs) and `GameLibrary`.
@@ -194,13 +198,40 @@ enum OnboardingLaunch {
private var suppressAdvance = false
private var tasks: [String: Task<Void, Never>] = [:]
private var subscription: AnyCancellable?
+ private let ephemeral: Bool
+ private var installApproved: Bool // background installs may start (always, except in an ephemeral run before an install action)
+ private var pending: [String: Any] = [:] // an ephemeral run's preference writes, applied by `flush`
+ private var pendingTarget: String?
+
+ /// A preference write; an ephemeral run holds it back.
+ private func store(_ value: Any?, _ key: String) {
+ if ephemeral { pending[key] = value ?? NSNull(); return }
+ if let value { env.defaults.set(value, forKey: key) } else { env.defaults.removeObject(forKey: key) }
+ }
+
+ /// The held-back writes, once the player finishes or sets up later.
+ private func flush() {
+ guard ephemeral else { return }
+ for (key, value) in pending { if value is NSNull { env.defaults.removeObject(forKey: key) } else { env.defaults.set(value, forKey: key) } }
+ pending.removeAll()
+ OnboardingDefaults.sessionPlatform = nil
+ if let target = pendingTarget { model.target = target; pendingTarget = nil }
+ }
private func t(_ key: String) -> String { L10n.string(key, model.lang) }
/// `fresh` ignores a stored step (Run setup again); otherwise a stored, unfinished run resumes where it stopped.
- init(model: BuildModel, library: GameLibrary, env: OnboardingEnvironment = OnboardingEnvironment(), fresh: Bool = false) {
- self.model = model; self.library = library; self.env = env
+ /// `ephemeral` (NSPB_ONBOARDING_FORCE) starts from Welcome, keeps every preference write in memory until the player finishes
+ /// or picks Set up later, and installs nothing until an install action is pressed, so a test leaves no trace.
+ init(model: BuildModel, library: GameLibrary, env: OnboardingEnvironment = OnboardingEnvironment(), fresh: Bool = false,
+ ephemeral: Bool = false) {
+ self.model = model; self.library = library; self.env = env; self.ephemeral = ephemeral
+ installApproved = !ephemeral
let d = env.defaults
+ if ephemeral {
+ updateWelcome()
+ return
+ }
if fresh {
d.removeObject(forKey: OnboardingDefaults.step); d.removeObject(forKey: OnboardingDefaults.platform)
d.set(false, forKey: OnboardingDefaults.inProgress)
@@ -234,19 +265,17 @@ enum OnboardingLaunch {
func start() {
guard state.step == .welcome, state.exit == nil else { return }
- env.defaults.set(true, forKey: OnboardingDefaults.inProgress)
+ store(true, OnboardingDefaults.inProgress)
next()
}
func choosePlatform(_ platform: OnboardingPlatform) {
guard state.step == .platform, state.exit == nil else { return }
state.platform = .selected(platform)
- env.defaults.set(platform.rawValue, forKey: OnboardingDefaults.platform) // before the detection below reads it
- switch platform { // the Builds page's target follows the choice; "both" leaves it as it is
- case .mac: model.target = "mac-app"
- case .iphone: model.target = "ios"
- case .both: break
- }
+ store(platform.rawValue, OnboardingDefaults.platform) // before the detection below reads it
+ if ephemeral { OnboardingDefaults.sessionPlatform = platform.rawValue } // the detection reads it from here
+ let target: String? = platform == .mac ? "mac-app" : (platform == .iphone ? "ios" : nil) // "both" leaves the target as it is
+ if let target { if ephemeral { pendingTarget = target } else { model.target = target } }
updateWelcome()
backgroundStarted = true
spawn("platform") { d in
@@ -257,6 +286,7 @@ enum OnboardingLaunch {
func getXcode() {
guard state.step == .xcode, state.xcode == .missing, state.exit == nil else { return }
+ installApproved = true
waitingForXcode = true
state.xcode = .downloading
env.openURL(URL(string: "macappstore://apps.apple.com/app/id497799835")!)
@@ -265,6 +295,7 @@ enum OnboardingLaunch {
func finishXcodeSetup() {
guard state.step == .xcode, state.xcode == .needsSetup, state.exit == nil else { return }
+ installApproved = true
state.xcode = .settingUp
xcodeBusy = true
spawn("finish") { d in await d.runFinishXcode() }
@@ -274,6 +305,7 @@ enum OnboardingLaunch {
guard state.step == step, state.exit == nil else { return }
switch step {
case .xcode:
+ installApproved = true
failedDeps.removeAll()
if case .failed = state.xcode { state.xcode = .needsSetup }
xcodeBusy = false
@@ -319,15 +351,17 @@ enum OnboardingLaunch {
func skipForLater() {
guard state.exit == nil else { return }
persistStep()
- env.defaults.set(true, forKey: OnboardingDefaults.inProgress)
+ store(true, OnboardingDefaults.inProgress)
+ flush()
close(.later)
}
func openLibrary() {
guard state.step == .done, state.primaryEnabled else { return }
- env.defaults.set(true, forKey: OnboardingDefaults.completed)
- env.defaults.set(false, forKey: OnboardingDefaults.inProgress)
- env.defaults.removeObject(forKey: OnboardingDefaults.step)
+ store(true, OnboardingDefaults.completed)
+ store(false, OnboardingDefaults.inProgress)
+ store(nil, OnboardingDefaults.step)
+ flush()
if library.selectedID == nil { library.selectedID = library.games.first?.id }
close(.library)
}
@@ -346,7 +380,7 @@ enum OnboardingLaunch {
for _ in 0..<6 { for task in Array(tasks.values) { await task.value } }
}
- private func persistStep() { env.defaults.set(state.step.rawValue, forKey: OnboardingDefaults.step) }
+ private func persistStep() { store(state.step.rawValue, OnboardingDefaults.step) }
private func spawn(_ name: String, _ body: @escaping (LiveOnboardingDriver) async -> Void) {
tasks[name]?.cancel()
@@ -553,7 +587,7 @@ enum OnboardingLaunch {
/// One install at a time, in the order Python, .NET, tools. Homebrew and its formulas need Xcode's command line tools,
/// so they wait for Xcode to be ready; the other two start at once.
func pumpInstalls() {
- guard backgroundStarted, model.depsChecked, currentInstall == nil, state.exit == nil else { return }
+ guard installApproved, backgroundStarted, model.depsChecked, currentInstall == nil, state.exit == nil else { return }
for task in OnboardingBackgroundTask.allCases {
if task == .tools && state.xcode != .ready { continue }
guard let next = deps(for: task).first(where: { !$0.present && failedDeps[$0.id] == nil && !$0.installing }) else { continue }
diff --git a/frontend/Sources/NSPortBuilder/OnboardingRoot.swift b/frontend/Sources/NSPortBuilder/OnboardingRoot.swift
index 021073a9..a3b7e107 100644
--- a/frontend/Sources/NSPortBuilder/OnboardingRoot.swift
+++ b/frontend/Sources/NSPortBuilder/OnboardingRoot.swift
@@ -34,6 +34,8 @@ struct RootView: View {
/// anything else starts or resumes the guided setup.
private func decide() async {
let defaults = UserDefaults.standard
+ // NSPB_ONBOARDING_FORCE=1: the real flow with real detection whatever the state, leaving no trace until it is finished
+ if OnboardingLaunch.forced() { show(fresh: false, ephemeral: true); return }
if defaults.bool(forKey: OnboardingDefaults.completed) { mode = .launcher; return }
await model.refreshDepsAndWait()
let env = OnboardingEnvironment()
@@ -48,8 +50,8 @@ struct RootView: View {
}
}
- private func show(fresh: Bool) {
- let d = LiveOnboardingDriver(model: model, library: library, fresh: fresh)
+ private func show(fresh: Bool, ephemeral: Bool = false) {
+ let d = LiveOnboardingDriver(model: model, library: library, fresh: fresh, ephemeral: ephemeral)
d.onExit = { _ in mode = .launcher; driver = nil }
driver = d
mode = .onboarding
diff --git a/frontend/Tests/NSPortBuilderTests/LiveOnboardingDriverTests.swift b/frontend/Tests/NSPortBuilderTests/LiveOnboardingDriverTests.swift
index 8a3649fc..87a67f06 100644
--- a/frontend/Tests/NSPortBuilderTests/LiveOnboardingDriverTests.swift
+++ b/frontend/Tests/NSPortBuilderTests/LiveOnboardingDriverTests.swift
@@ -25,6 +25,7 @@ import XCTest
var home: URL!
override func setUp() {
+ OnboardingDefaults.sessionPlatform = nil
let target = UserDefaults.standard.object(forKey: "buildTarget") // choosePlatform sets the Builds page's target
addTeardownBlock { UserDefaults.standard.set(target, forKey: "buildTarget") }
let suite = "onboarding.tests." + UUID().uuidString
@@ -129,6 +130,43 @@ import XCTest
}
}
+ func testForceShowsTheSetupWhateverTheState() {
+ XCTAssertTrue(OnboardingLaunch.shouldShow(completed: true, setupComplete: true, force: true))
+ XCTAssertFalse(OnboardingLaunch.shouldShow(completed: true, setupComplete: true, force: false))
+ XCTAssertTrue(OnboardingLaunch.forced(["NSPB_ONBOARDING_FORCE": "1"]))
+ XCTAssertFalse(OnboardingLaunch.forced(["NSPB_ONBOARDING_FORCE": "0"]))
+ XCTAssertFalse(OnboardingLaunch.forced([:]))
+ }
+
+ func testForcedRunLeavesNoTraceInstallsNothingUntilAskedAndFlushesOnLater() async {
+ let fake = Fake()
+ defaults.set(true, forKey: OnboardingDefaults.completed)
+ let (live, model) = make(fake, deps: [dep("xcode", present: true), dep("metal", present: true), dep("python", present: false)])
+ _ = live
+ var env = OnboardingEnvironment(); env.defaults = defaults; env.home = home.path
+ env.freeBytes = { 100_000_000_000 }; env.xcodeProbe = { fake.probe }; env.xcodeInstalled = { true }; env.xcodeFolderExists = { true }
+ env.detectDeps = { _ in }; env.installDep = { _, d in fake.installed.append(d.id) }
+ env.advanceDelay = 0
+ let driver = LiveOnboardingDriver(model: model, library: GameLibrary(file: home.appendingPathComponent("l.json")), env: env, ephemeral: true)
+ XCTAssertEqual(driver.state.step, .welcome, "a forced run starts from Welcome whatever is stored")
+ driver.start(); driver.choosePlatform(.mac)
+ driver.next()
+ driver.activate()
+ await driver.settle()
+ XCTAssertTrue(fake.installed.isEmpty, "nothing installs before an install action")
+ XCTAssertNil(defaults.string(forKey: OnboardingDefaults.step))
+ XCTAssertNil(defaults.string(forKey: OnboardingDefaults.platform))
+ XCTAssertFalse(defaults.bool(forKey: OnboardingDefaults.inProgress))
+ XCTAssertTrue(BuildModel.needsIOSPlatform(defaults: defaults) == false, "the session's Mac-only choice is in effect")
+ driver.retry(.xcode)
+ await driver.settle()
+ XCTAssertEqual(fake.installed, ["python"])
+ driver.skipForLater()
+ XCTAssertEqual(defaults.string(forKey: OnboardingDefaults.platform), "mac", "Set up later stores it")
+ XCTAssertEqual(defaults.string(forKey: OnboardingDefaults.step), "xcode")
+ XCTAssertNil(OnboardingDefaults.sessionPlatform)
+ }
+
// MARK: The driver
func testWelcomeShowsMeasuredFreeSpace() {