Skip to content

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

The launcher ships its build tools and Python, so a player needs no Homebrew

v0lumehi638b220ded6b
diff --git a/.github/workflows/build-mac-app.yml b/.github/workflows/build-mac-app.yml
index 6ae6907a..d3e9b7b0 100644
--- a/.github/workflows/build-mac-app.yml
+++ b/.github/workflows/build-mac-app.yml
@@ -8,13 +8,20 @@
# "up to date" — a silent failure of the update path for every existing install. Copies from before
# the app was renamed (NS Port Builder) look for NS-Port-Builder-macOS-arm64.zip, so that one goes up too.
#
+# The app also carries its build tools (zstd, glslangValidator, spirv-cross, xcodegen) and a Python with the packages the build scripts import,
+# so a player installs neither Homebrew nor Python (frontend/tools/bundle_tools.sh builds them from pinned, checksummed sources; check_bundle.sh
+# runs each from the assembled bundle with a clean PATH, checks the load paths and the signature).
+#
# - push a tag vX.Y.Z → builds and attaches the app to that release
# - workflow_dispatch → artifact only
+# - a pull request that touches frontend/ or this file → artifact only, so a change to the bundle is tested before a release needs it
name: Build nxnative (native macOS)
on:
push:
tags: ['v*']
+ pull_request:
+ paths: ['frontend/**', '.github/workflows/build-mac-app.yml']
workflow_dispatch:
permissions:
@@ -63,6 +70,9 @@ jobs:
mkdir -p "$APP/Contents/MacOS" "$APP/Contents/Resources"
cp .build/release/NSPortBuilder "$APP/Contents/MacOS/NSPortBuilder"
cp AppIcon.icns "$APP/Contents/Resources/AppIcon.icns"
+ # The build tools and the Python go into Resources before the bundle is signed (bundle_tools.sh signs each nested Mach-O file
+ # itself: --deep below does not reach code that sits in Resources).
+ tools/bundle_tools.sh "$APP/Contents/Resources" "$RUNNER_TEMP/bundle-tools-work"
V="${{ steps.ver.outputs.version }}"
cat > "$APP/Contents/Info.plist" <<PLIST
<?xml version="1.0" encoding="UTF-8"?>
@@ -86,9 +96,19 @@ jobs:
# Ad-hoc: the app is distributed as a zip and the user right-clicks → Open once, which is
# what the README says. A real Developer ID would need a certificate this repo has none of.
codesign --force --deep --sign - "$APP"
- codesign -v "$APP"
+ codesign -v --deep --strict "$APP"
plutil -p "$APP/Contents/Info.plist" | grep -i version
+ - name: Check the bundled tools from the assembled bundle
+ working-directory: frontend
+ shell: bash
+ run: |
+ set -euo pipefail
+ # zstd, glslangValidator, spirv-cross and xcodegen run by their bundle paths with a PATH of /usr/bin:/bin; the Python imports
+ # lz4, capstone, fontTools and nsz; no Mach-O file links into /opt/homebrew; the signature verifies.
+ tools/check_bundle.sh NX2Apple.app
+ codesign -v --deep --strict NX2Apple.app
+
- name: Package
working-directory: frontend
shell: bash
@@ -111,6 +131,7 @@ jobs:
(cd "legacy-$legacy" && ditto -c -k --keepParent "$legacy.app" "../${zname}-macOS-arm64.zip")
done
ls -la *.zip
+ du -sh "$APP/Contents/Resources/tools" "$APP/Contents/Resources/python"
- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
diff --git a/frontend/README.md b/frontend/README.md
index 2dee5b48..e5f95fa8 100644
--- a/frontend/README.md
+++ b/frontend/README.md
@@ -221,6 +221,19 @@ and picks the first interpreter that can really import
`lz4 capstone fontTools backports.zstd`. That same interpreter then runs the
build.
+### The bundled build tools and Python
+
+The release app (`NX2Apple.app`) carries `zstd`, `glslangValidator`, `spirv-cross`, `xcodegen` (in
+`Contents/Resources/tools/bin`) and a relocatable CPython 3.13 with `lz4 capstone fonttools
+backports.zstd nsz` (`Contents/Resources/python`), so a player needs no Homebrew and no Python.
+`tools/bundle_tools.sh` fills them in during the release workflow (pinned versions and sha256 of the
+sources, built for macOS 13 with static libraries; the Python packages come from
+`tools/bundled-python-requirements.txt`) and `tools/check_bundle.sh` runs each tool from the bundle
+with a clean PATH. The dependency check (`BundledTools.swift`) prefers them to Homebrew's and shows
+"bundled"; the build's PATH starts with them. Under `swift run`, or in a build without the bundle,
+nothing changes: Homebrew's tools, a system Python or the launcher's venv. To try the bundle by hand:
+`tools/bundle_tools.sh <folder> <work folder>`, then `tools/check_bundle.sh <folder>`.
+
## Language
The interface follows the system language at every launch: any Chinese variant
diff --git a/frontend/Sources/NSPortBuilder/BundledTools.swift b/frontend/Sources/NSPortBuilder/BundledTools.swift
new file mode 100644
index 00000000..b7a41aaf
--- /dev/null
+++ b/frontend/Sources/NSPortBuilder/BundledTools.swift
@@ -0,0 +1,47 @@
+import Foundation
+
+/// The build tools and the Python that the release app carries in Contents/Resources (frontend/tools/bundle_tools.sh fills them in):
+///
+/// tools/bin zstd, glslangValidator, spirv-cross, xcodegen
+/// python/ a relocatable CPython with lz4, capstone, fontTools and nsz installed
+///
+/// Every function takes the resources folder as a parameter (the tests pass a fake bundle) and defaults to this app's own. There is
+/// none under `swift run` or in a build that predates the bundle, and each function then answers nil, so everything else behaves as
+/// it did before: Homebrew's tools, a system Python or the launcher's venv.
+enum BundledTools {
+ /// This app's Resources folder, but only inside a .app: `swift run` gives the executable's own folder, which is not a bundle.
+ nonisolated static var resources: URL? {
+ guard Bundle.main.bundleURL.pathExtension == "app" else { return nil }
+ return Bundle.main.resourceURL
+ }
+
+ nonisolated static func isExecutable(_ url: URL) -> Bool { FileManager.default.isExecutableFile(atPath: url.path) }
+
+ /// tools/bin, when the bundle has it.
+ nonisolated static func binDirectory(in resources: URL? = resources) -> String? {
+ guard let dir = resources?.appendingPathComponent("tools/bin"),
+ (try? FileManager.default.contentsOfDirectory(atPath: dir.path))?.isEmpty == false else { return nil }
+ return dir.path
+ }
+
+ /// The path of one bundled tool (`binary` is the file name in tools/bin), when it is there and runs.
+ nonisolated static func tool(_ binary: String, in resources: URL? = resources) -> String? {
+ guard let url = resources?.appendingPathComponent("tools/bin/" + binary), isExecutable(url) else { return nil }
+ return url.path
+ }
+
+ /// The bundled interpreter, when it is there.
+ nonisolated static func python(in resources: URL? = resources) -> String? {
+ guard let url = resources?.appendingPathComponent("python/bin/python3"), isExecutable(url) else { return nil }
+ return url.path
+ }
+
+ /// A PATH for the processes that run the build: the bundled tools first, then the bundled Python's folder (so that a script that
+ /// starts `python3` by name gets this one and not the system's 3.9), then `base`. `base` unchanged when there is no bundle.
+ nonisolated static func path(_ base: String, in resources: URL? = resources) -> String {
+ var dirs: [String] = []
+ if let bin = binDirectory(in: resources) { dirs.append(bin) }
+ if let py = python(in: resources) { dirs.append((py as NSString).deletingLastPathComponent) }
+ return (dirs + [base]).joined(separator: ":")
+ }
+}
diff --git a/frontend/Sources/NSPortBuilder/ContentView.swift b/frontend/Sources/NSPortBuilder/ContentView.swift
index 14953155..9742fef0 100644
--- a/frontend/Sources/NSPortBuilder/ContentView.swift
+++ b/frontend/Sources/NSPortBuilder/ContentView.swift
@@ -364,6 +364,12 @@ final class BuildModel: ObservableObject {
["PATH": "/usr/bin:/bin:/opt/homebrew/bin:/usr/local/bin", "HOME": NSHomeDirectory()]
}
+ /// The PATH of the processes that run the build, installing packages and writing the RomFS image: the bundled tools in front of
+ /// `base` (BundledTools.swift), which is Homebrew's folders and the system's. One place, so that no environment forgets the bundle.
+ nonisolated static func toolPath(_ base: String = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin") -> String {
+ BundledTools.path(base)
+ }
+
/// Run a command with all output captured (no streaming; fetch / rev-list / pull print little).
nonisolated static func runQuiet(_ args: [String], env: [String: String]) -> (ok: Bool, out: String) {
let p = Process()
@@ -1072,7 +1078,7 @@ final class BuildModel: ObservableObject {
if compressed, !Self.runOK(py, ["-c", "import nsz"]) {
say(t("msg.installingNsz"))
let r = Self.runCaptured([py, "-m", "pip", "install", "nsz"],
- env: ["PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin",
+ env: ["PATH": Self.toolPath(),
"HOME": NSHomeDirectory()]) { line in
DispatchQueue.main.async { self.append(line + "\n") }
}
@@ -1128,13 +1134,16 @@ final class BuildModel: ObservableObject {
// (NuGet-Migrations) under $TMPDIR/.dotnet/shm, and with no TMPDIR it stats "" and dies with
// 'NuGet-Migrations' + lstat("") == ENOENT before any project is read. NSTemporaryDirectory()
// is the per-user temp folder whether or not the app's own environment carries one.
- var denv: [String: String] = ["PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
+ var denv: [String: String] = ["PATH": Self.toolPath("/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"),
"USER": NSUserName(), "HOME": NSHomeDirectory(), "LANG": "en_US.UTF-8",
"TMPDIR": NSTemporaryDirectory()]
if let droot = Self.dotnetRoot(for: dotnetPath.isEmpty ? "dotnet" : dotnetPath) {
denv["DOTNET_ROOT"] = droot // both variables carry the same root, as the apphost checks the arch-specific one first
denv["DOTNET_ROOT_ARM64"] = droot
}
+ // The bundled Python lives inside the signed app: a .pyc written there would change what the signature seals
+ // (the packages are compiled at bundle time).
+ if py == BundledTools.python() { denv["PYTHONDONTWRITEBYTECODE"] = "1" }
p.environment = denv
Self.inOwnGroup(p, python: py)
let pipe = Pipe()
@@ -1567,7 +1576,7 @@ final class BuildModel: ObservableObject {
p.executableURL = URL(fileURLWithPath: pythonPath.isEmpty ? "/usr/bin/python3" : pythonPath)
// dest/romfs.img: one file, which main.m's per-game lookup takes before any folder.
p.arguments = [repoPath + "/" + Self.romfsImageTool, "--reuse", romfs, dest + "/romfs.img"]
- p.environment = ["PATH": "/usr/bin:/bin:/usr/local/bin:/opt/homebrew/bin", "PYTHONPATH": repoPath + "/dm/tools"]
+ p.environment = ["PATH": Self.toolPath("/usr/bin:/bin:/usr/local/bin:/opt/homebrew/bin"), "PYTHONPATH": repoPath + "/dm/tools"]
Self.inOwnGroup(p, python: p.executableURL!.path)
let pipe = Pipe(); p.standardOutput = pipe; p.standardError = pipe
pipe.fileHandleForReading.readabilityHandler = { [weak self] h in
@@ -1929,7 +1938,7 @@ final class BuildModel: ObservableObject {
let p = Process(); p.executableURL = URL(fileURLWithPath: exe); p.arguments = args
let out = Pipe(), err = Pipe()
p.standardOutput = out; p.standardError = err; p.standardInput = FileHandle.nullDevice
- p.environment = ["PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin", "HOME": NSHomeDirectory()]
+ p.environment = ["PATH": toolPath(), "HOME": NSHomeDirectory()]
do { try p.run() } catch { log += "could not start \(exe): \(error.localizedDescription)\n"; return false }
// both pipes are drained on this thread (before waitUntilExit, so the child cannot
// block on a full pipe), and the log string keeps a single owner
@@ -1971,7 +1980,12 @@ final class BuildModel: ObservableObject {
/// Every python3 on this Mac, newest-looking first, each tried for a usable version and the
/// packages. Returns the one to build with, plus why the others were rejected for the message.
- nonisolated static func findPython() -> (path: String, ok: Bool) {
+ nonisolated static func findPython(resources: URL? = BundledTools.resources) -> (path: String, ok: Bool) {
+ // The release app's own Python (BundledTools.swift) has every package and is the one the build is tested with: it wins over
+ // any Python on this Mac and needs no venv. One that does not run (a damaged copy) falls through to the search below.
+ if let bundled = BundledTools.python(in: resources), pythonVersion(bundled).map({ $0 >= minPython }) == true, importsOK(bundled) {
+ return (bundled, true)
+ }
var cands: [String] = []
let fw = "/Library/Frameworks/Python.framework/Versions"
if let vers = try? FileManager.default.contentsOfDirectory(atPath: fw) {
@@ -2096,6 +2110,29 @@ final class BuildModel: ObservableObject {
return (defaults.string(forKey: "buildTarget") ?? "ios") != "mac-app"
}
+
+ /// The rows for the build tools (xcodegen, zstd, spirv-cross, glslangValidator) and the Homebrew row they may need.
+ /// A tool the app carries counts as present and says "bundled"; otherwise Homebrew's copy counts (`installed` answers
+ /// a binary name with its path in a Homebrew folder, or nil). The Homebrew row appears only when some tool is neither
+ /// bundled nor installed (with a bundle; with none the row stays, as before): it is the way to get that one.
+ nonisolated static func toolDeps(resources: URL?, installed: (String) -> String?, brew: String?) -> [Dep] {
+ var rows: [Dep] = []
+ var needsBrew = false, anyBundled = false
+ for (pkg, binary, key) in brewDeps {
+ let bundled = BundledTools.tool(binary, in: resources) != nil
+ let path = bundled ? nil : installed(binary)
+ if !bundled && path == nil { needsBrew = true }
+ if bundled { anyBundled = true }
+ rows.append(Dep(id: "brew:" + pkg, name: key, hint: key + ".hint", present: bundled || path != nil,
+ detail: bundled ? "dep.bundled" : (path ?? ""),
+ installCmd: [(brew ?? "/opt/homebrew/bin/brew"), "install", pkg]))
+ }
+ guard needsBrew || !anyBundled else { return rows } // without a bundle the row is always there, as it was
+ return [Dep(id: "brew", name: "dep.brew", hint: "dep.brew.hint", present: brew != nil,
+ installCmd: ["/bin/bash", "-c",
+ "NONINTERACTIVE=1 /bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\""])] + rows
+ }
+
nonisolated static func detectDepsSync(needsIOS: Bool = BuildModel.needsIOSPlatform()) -> [Dep] {
var out: [Dep] = []
@@ -2116,16 +2153,9 @@ final class BuildModel: ObservableObject {
out.append(Dep(id: "metal", name: "dep.metal", hint: "dep.metal.hint",
present: mt, installCmd: metalToolchainCmd))
- let brew = firstExisting(["/opt/homebrew/bin/brew", "/usr/local/bin/brew"])
- out.append(Dep(id: "brew", name: "dep.brew", hint: "dep.brew.hint", present: brew != nil,
- installCmd: ["/bin/bash", "-c",
- "NONINTERACTIVE=1 /bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\""]))
- for (pkg, binary, key) in brewDeps {
- let path = firstExisting(["/opt/homebrew/bin/\(binary)", "/usr/local/bin/\(binary)"])
- out.append(Dep(id: "brew:" + pkg, name: key, hint: key + ".hint", present: path != nil,
- detail: path ?? "",
- installCmd: [(brew ?? "/opt/homebrew/bin/brew"), "install", pkg]))
- }
+ out += toolDeps(resources: BundledTools.resources,
+ installed: { firstExisting(["/opt/homebrew/bin/\($0)", "/usr/local/bin/\($0)"]) },
+ brew: firstExisting(["/opt/homebrew/bin/brew", "/usr/local/bin/brew"]))
let (dn, dnOK) = findDotnet()
out.append(Dep(id: "dotnet", name: "dep.dotnet", hint: "dep.dotnet.hint",
@@ -2140,7 +2170,7 @@ final class BuildModel: ObservableObject {
// A version we cannot read means no interpreter ran at all (py is then the venv
// that does not exist yet), which is not the same as one that is too old.
let minVer = "\(minPython.0).\(minPython.1)"
- let pyDetail = pyOK ? py
+ let pyDetail = pyOK ? (py == BundledTools.python() ? "dep.bundled" : py)
: pythonVersion(py).map { $0 >= minPython
? "dep.python.missing:\(py) (\(pyVer))"
: "dep.python.old:\(pyVer):\(minVer)" }
diff --git a/frontend/Sources/NSPortBuilder/Localization.swift b/frontend/Sources/NSPortBuilder/Localization.swift
index d2f91a70..917e2569 100644
--- a/frontend/Sources/NSPortBuilder/Localization.swift
+++ b/frontend/Sources/NSPortBuilder/Localization.swift
@@ -522,6 +522,7 @@ enum L10n {
"dep.probe.metal.hint": ("验证 metal.exe 能产出 metallib",
"checks that metal.exe produces a metallib"),
"dep.optionalMissing": ("可选,未安装", "optional, not installed"),
+ "dep.bundled": ("随 App 附带", "bundled"),
"dep.glslang": ("brew: glslang", "brew: glslang"),
"dep.glslang.hint": ("编译 OpenGL 游戏的着色器;打包脚本的环境检查要求它", "compiles OpenGL games' shaders; the NSP script's environment check requires it"),
"dep.installTimeout": ("安装超时(30 分钟)——网络太慢或卡住了",
diff --git a/frontend/Tests/NSPortBuilderTests/BundledToolsTests.swift b/frontend/Tests/NSPortBuilderTests/BundledToolsTests.swift
new file mode 100644
index 00000000..429a0d80
--- /dev/null
+++ b/frontend/Tests/NSPortBuilderTests/BundledToolsTests.swift
@@ -0,0 +1,180 @@
+import XCTest
+@testable import NSPortBuilder
+
+/// The release app carries its build tools and a Python (BundledTools.swift): the dependency check prefers them to Homebrew's and to
+/// a system Python, and the build's PATH starts with them. A fake bundle stands in for Contents/Resources.
+final class BundledToolsTests: XCTestCase {
+ private var root: URL!
+
+ override func setUpWithError() throws {
+ root = FileManager.default.temporaryDirectory.appendingPathComponent("bundled-tools-\(UUID().uuidString)")
+ try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true)
+ }
+ override func tearDownWithError() throws { try? FileManager.default.removeItem(at: root) }
+
+ /// An executable file `relative` under the fake Resources folder; `script` is what it prints when it runs.
+ @discardableResult
+ private func install(_ relative: String, script: String = "#!/bin/sh\nexit 0\n") throws -> String {
+ let url = root.appendingPathComponent(relative)
+ try FileManager.default.createDirectory(at: url.deletingLastPathComponent(), withIntermediateDirectories: true)
+ try script.write(to: url, atomically: true, encoding: .utf8)
+ try FileManager.default.setAttributes([.posixPermissions: 0o755], ofItemAtPath: url.path)
+ return url.path
+ }
+ private func installAllTools() throws {
+ for (_, binary, _) in BuildModel.brewDeps { try install("tools/bin/" + binary) }
+ }
+ private func row(_ rows: [BuildModel.Dep], _ pkg: String) -> BuildModel.Dep? { rows.first { $0.id == "brew:" + pkg } }
+
+ // ---- what the bundle holds ----
+
+ func testNoBundleAnswersNil() {
+ XCTAssertNil(BundledTools.binDirectory(in: nil))
+ XCTAssertNil(BundledTools.tool("zstd", in: nil))
+ XCTAssertNil(BundledTools.python(in: nil))
+ XCTAssertNil(BundledTools.binDirectory(in: root), "a folder with no tools/bin")
+ XCTAssertNil(BundledTools.tool("zstd", in: root))
+ }
+
+ func testSwiftRunHasNoResources() {
+ // `swift test` and `swift run` execute outside a .app, so the launcher sees no bundle there
+ XCTAssertNil(BundledTools.resources)
+ }
+
+ func testToolAndPythonPaths() throws {
+ let zstd = try install("tools/bin/zstd")
+ let py = try install("python/bin/python3")
+ XCTAssertEqual(BundledTools.tool("zstd", in: root), zstd)
+ XCTAssertNil(BundledTools.tool("xcodegen", in: root))
+ XCTAssertEqual(BundledTools.python(in: root), py)
+ XCTAssertEqual(BundledTools.binDirectory(in: root), root.appendingPathComponent("tools/bin").path)
+ }
+
+ func testAFileWithoutTheExecuteBitIsNotATool() throws {
+ let url = root.appendingPathComponent("tools/bin/zstd")
+ try FileManager.default.createDirectory(at: url.deletingLastPathComponent(), withIntermediateDirectories: true)
+ try "x".write(to: url, atomically: true, encoding: .utf8)
+ XCTAssertNil(BundledTools.tool("zstd", in: root))
+ }
+
+ // ---- PATH ----
+
+ func testPathWithoutBundleIsTheBaseUnchanged() {
+ XCTAssertEqual(BundledTools.path("/usr/bin:/bin", in: nil), "/usr/bin:/bin")
+ XCTAssertEqual(BundledTools.path("/usr/bin:/bin", in: root), "/usr/bin:/bin")
+ }
+
+ func testPathPutsTheBundledToolsFirstThenItsPython() throws {
+ try install("tools/bin/zstd")
+ try install("python/bin/python3")
+ XCTAssertEqual(BundledTools.path("/opt/homebrew/bin:/usr/bin", in: root),
+ root.path + "/tools/bin:" + root.path + "/python/bin:/opt/homebrew/bin:/usr/bin")
+ }
+
+ func testPathWithToolsButNoPython() throws {
+ try install("tools/bin/zstd")
+ XCTAssertEqual(BundledTools.path("/usr/bin", in: root), root.path + "/tools/bin:/usr/bin")
+ }
+
+ func testBuildToolPathKeepsTheHomebrewBaseWithoutABundle() {
+ // under `swift test` there is no bundle: the helper is the old string
+ XCTAssertEqual(BuildModel.toolPath(), "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin")
+ XCTAssertEqual(BuildModel.toolPath("/usr/bin:/bin"), "/usr/bin:/bin")
+ }
+
+ // ---- the dependency rows ----
+
+ func testWithoutABundleTheRowsAreHomebrews() {
+ let rows = BuildModel.toolDeps(resources: nil, installed: { "/opt/homebrew/bin/" + $0 }, brew: "/opt/homebrew/bin/brew")
+ XCTAssertEqual(rows.map { $0.id }, ["brew"] + BuildModel.brewDeps.map { "brew:" + $0.formula })
+ XCTAssertTrue(rows.allSatisfy { $0.present })
+ XCTAssertEqual(row(rows, "zstd")?.detail, "/opt/homebrew/bin/zstd")
+ XCTAssertEqual(row(rows, "glslang")?.detail, "/opt/homebrew/bin/glslangValidator")
+ }
+
+ func testWithoutABundleOrHomebrewTheRowsAreMissing() {
+ let rows = BuildModel.toolDeps(resources: nil, installed: { _ in nil }, brew: nil)
+ XCTAssertFalse(rows.first { $0.id == "brew" }!.present)
+ XCTAssertTrue(BuildModel.brewDeps.allSatisfy { row(rows, $0.formula)?.present == false })
+ }
+
+ func testBundledToolsArePresentAndNeedNoHomebrew() throws {
+ try installAllTools()
+ let rows = BuildModel.toolDeps(resources: root, installed: { _ in nil }, brew: nil)
+ XCTAssertNil(rows.first { $0.id == "brew" }, "nothing needs Homebrew")
+ XCTAssertEqual(rows.count, BuildModel.brewDeps.count)
+ XCTAssertTrue(rows.allSatisfy { $0.present && $0.detail == "dep.bundled" })
+ }
+
+ func testBundledWinsOverHomebrews() throws {
+ try installAllTools()
+ let rows = BuildModel.toolDeps(resources: root, installed: { "/opt/homebrew/bin/" + $0 }, brew: "/opt/homebrew/bin/brew")
+ XCTAssertTrue(rows.allSatisfy { $0.detail == "dep.bundled" })
+ XCTAssertNil(rows.first { $0.id == "brew" })
+ }
+
+ func testOneMissingToolBringsBackTheHomebrewRowForThatTool() throws {
+ try installAllTools()
+ try FileManager.default.removeItem(at: root.appendingPathComponent("tools/bin/spirv-cross"))
+ let rows = BuildModel.toolDeps(resources: root, installed: { _ in nil }, brew: nil)
+ XCTAssertEqual(rows.first?.id, "brew")
+ XCTAssertFalse(rows.first!.present)
+ XCTAssertEqual(row(rows, "spirv-cross")?.present, false)
+ XCTAssertEqual(row(rows, "zstd")?.detail, "dep.bundled")
+ }
+
+ func testAMissingBundledToolFallsBackToHomebrewsCopy() throws {
+ try installAllTools()
+ try FileManager.default.removeItem(at: root.appendingPathComponent("tools/bin/xcodegen"))
+ let rows = BuildModel.toolDeps(resources: root, installed: { $0 == "xcodegen" ? "/opt/homebrew/bin/xcodegen" : nil },
+ brew: "/opt/homebrew/bin/brew")
+ XCTAssertEqual(row(rows, "xcodegen")?.detail, "/opt/homebrew/bin/xcodegen")
+ XCTAssertEqual(row(rows, "xcodegen")?.present, true)
+ XCTAssertNil(rows.first { $0.id == "brew" }, "every tool is bundled or installed")
+ }
+
+ func testBundledRowDetailIsLocalized() {
+ XCTAssertEqual(L10n.string("dep.bundled", .en), "bundled")
+ XCTAssertNotEqual(L10n.string("dep.bundled", .zh), "dep.bundled")
+ }
+
+ // ---- the Python ----
+
+ func testFindPythonUsesTheBundledOneThatRunsAndImports() throws {
+ // a stand-in interpreter that answers the version probe and accepts the import probe
+ let py = try install("python/bin/python3", script: """
+ #!/bin/sh
+ case "$2" in *sys.version_info*) echo 3.13;; esac
+ exit 0
+
+ """)
+ let found = BuildModel.findPython(resources: root)
+ XCTAssertEqual(found.path, py)
+ XCTAssertTrue(found.ok)
+ }
+
+ func testFindPythonSkipsABundledOneThatDoesNotRun() throws {
+ let py = try install("python/bin/python3", script: "#!/bin/sh\nexit 1\n")
+ XCTAssertNotEqual(BuildModel.findPython(resources: root).path, py)
+ }
+
+ func testFindPythonSkipsABundledOneThatIsTooOld() throws {
+ let py = try install("python/bin/python3", script: "#!/bin/sh\ncase \"$2\" in *sys.version_info*) echo 3.9;; esac\nexit 0\n")
+ XCTAssertNotEqual(BuildModel.findPython(resources: root).path, py)
+ }
+
+ // ---- the pinned packages ----
+
+ func testBundledPackagePinsCoverThePipPackages() throws {
+ // frontend/Tests/NSPortBuilderTests/BundledToolsTests.swift -> frontend/tools
+ var url = URL(fileURLWithPath: #filePath)
+ for _ in 0..<3 { url.deleteLastPathComponent() }
+ let text = try String(contentsOf: url.appendingPathComponent("tools/bundled-python-requirements.txt"), encoding: .utf8)
+ let pins = text.split(separator: "\n").filter { !$0.hasPrefix("#") }
+ let names = Set(pins.map { String($0.split(separator: "=", maxSplits: 1)[0]).lowercased() })
+ for pkg in BuildModel.pipPackages((3, 13)) {
+ XCTAssertTrue(names.contains(pkg.lowercased()), "\(pkg) is installed by the launcher's venv but not pinned for the bundle")
+ }
+ XCTAssertTrue(pins.allSatisfy { $0.contains("==") }, "every bundled package has an exact version")
+ }
+}
diff --git a/frontend/tools/bundle_tools.sh b/frontend/tools/bundle_tools.sh
new file mode 100755
index 00000000..788e8e77
--- /dev/null
+++ b/frontend/tools/bundle_tools.sh
@@ -0,0 +1,143 @@
+#!/bin/bash
+# Fills the launcher bundle's Resources folder with the build tools and a Python, so a player installs neither Homebrew nor Python:
+#
+# <Resources>/tools/bin zstd, glslangValidator, spirv-cross, xcodegen
+# <Resources>/tools/share xcodegen's SettingPresets (it looks for them beside its bin folder)
+# <Resources>/tools/licenses the license files of all of them
+# <Resources>/python CPython (python-build-standalone, relocatable) with the packages the build scripts import
+#
+# Usage: bundle_tools.sh <Resources folder> [work folder] (the work folder keeps the downloads and the builds; default: a temporary one)
+#
+# Why not Homebrew's bottles: a bottle is built for the macOS it is poured on (the bottles of 2026 say minos 15 or later, and this app runs
+# from macOS 13), and it links its siblings from /opt/homebrew (zstd: libzstd, liblzma, liblz4; glslang: libglslang, SPIRV-Tools). The tools
+# are built here from pinned, checksummed source with MACOSX_DEPLOYMENT_TARGET=13.0 and static libraries, so each is one file that links
+# only /usr/lib/libSystem and libc++ (otool -L; check_bundle.sh verifies it). xcodegen is the project's own release zip (Swift on the
+# system's libswift*), checked against its pinned sha256.
+#
+# Raising a pin: change the version and its sha256 below (the checksum of the release tarball), run this, then check_bundle.sh.
+set -euo pipefail
+
+ZSTD_VERSION=1.5.7
+ZSTD_SHA256=37d7284556b20954e56e1ca85b80226768902e2edabd3b649e9e72c0c9012ee3
+ZSTD_URL=https://github.com/facebook/zstd/archive/refs/tags/v$ZSTD_VERSION.tar.gz
+
+GLSLANG_VERSION=16.6.0
+GLSLANG_SHA256=9c09b901149c729df745057dafa815278aaa101b84d2b6e14f16a42de52f97f2
+GLSLANG_URL=https://github.com/KhronosGroup/glslang/archive/refs/tags/$GLSLANG_VERSION.tar.gz
+
+SPIRV_CROSS_TAG=vulkan-sdk-1.4.363.0 # the release the repo's own dm/gfx/tools/spirv_cross_bin/build.sh builds
+SPIRV_CROSS_SHA256=f708982e88b763ef5b0394ed468fc2c3628f68cdab89f2e7a946cd628c04e721
+SPIRV_CROSS_URL=https://github.com/KhronosGroup/SPIRV-Cross/archive/refs/tags/$SPIRV_CROSS_TAG.tar.gz
+
+XCODEGEN_VERSION=2.46.0
+XCODEGEN_SHA256=4d9e34b62172d645eed6457cac13fc222569974098ef4ee9c3368bedf0196806
+XCODEGEN_URL=https://github.com/yonaskolb/XcodeGen/releases/download/$XCODEGEN_VERSION/xcodegen.zip
+
+PYTHON_VERSION=3.13.18
+PYTHON_RELEASE=20261026
+PYTHON_SHA256=e5af2fde6a937a0e0c795a0c595c4efb70578d57463a2657c819992b9b9acbac
+PYTHON_URL=https://github.com/astral-sh/python-build-standalone/releases/download/$PYTHON_RELEASE/cpython-$PYTHON_VERSION+$PYTHON_RELEASE-aarch64-apple-darwin-install_only.tar.gz
+
+HERE=$(cd "$(dirname "$0")" && pwd)
+RES=${1:?usage: bundle_tools.sh <Resources folder> [work folder]}
+WORK=${2:-$(mktemp -d -t bundle-tools)}
+mkdir -p "$RES" "$WORK/dl"
+RES=$(cd "$RES" && pwd); WORK=$(cd "$WORK" && pwd)
+JOBS=$(sysctl -n hw.ncpu)
+export MACOSX_DEPLOYMENT_TARGET=13.0
+
+[ "$(uname -m)" = arm64 ] || { echo "[RED] this builds the arm64 app: run it on an Apple-silicon Mac" >&2; exit 1; }
+
+fetch() { # fetch <url> <sha256> -> the file in $WORK/dl
+ local f="$WORK/dl/$(basename "$1")"
+ if [ ! -f "$f" ]; then curl -fsSL --retry 3 -o "$f.part" "$1"; mv "$f.part" "$f"; fi
+ local got; got=$(shasum -a 256 "$f" | cut -c1-64)
+ [ "$got" = "$2" ] || { echo "[RED] $1: sha256 $got, pinned $2" >&2; rm -f "$f"; exit 1; }
+ echo "$f"
+}
+unpack() { # unpack <tarball> <dest> -> a fresh source folder
+ rm -rf "$2"; mkdir -p "$2"; tar -xzf "$1" -C "$2" --strip-components=1
+}
+
+BIN="$RES/tools/bin"; LIC="$RES/tools/licenses"
+rm -rf "$RES/tools" "$RES/python"
+mkdir -p "$BIN" "$LIC" "$RES/tools/share"
+
+# zstd: the command line tool alone, with its own library compiled in and no xz / lz4 / zlib to link
+echo "== zstd $ZSTD_VERSION"
+unpack "$(fetch "$ZSTD_URL" "$ZSTD_SHA256")" "$WORK/zstd"
+make -C "$WORK/zstd/programs" -j "$JOBS" zstd HAVE_ZLIB=0 HAVE_LZMA=0 HAVE_LZ4=0 > "$WORK/zstd.log" 2>&1 || { tail -30 "$WORK/zstd.log"; exit 1; }
+cp "$WORK/zstd/programs/zstd" "$BIN/zstd"
+cp "$WORK/zstd/LICENSE" "$LIC/zstd-LICENSE-BSD"; cp "$WORK/zstd/COPYING" "$LIC/zstd-COPYING-GPLv2"
+
+# glslang: glslangValidator alone (the SPIR-V optimizer is not built: gl_shaders.py only compiles with -V)
+echo "== glslang $GLSLANG_VERSION"
+unpack "$(fetch "$GLSLANG_URL" "$GLSLANG_SHA256")" "$WORK/glslang"
+cmake -S "$WORK/glslang" -B "$WORK/glslang-build" -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF -DENABLE_OPT=OFF -DBUILD_EXTERNAL=OFF \
+ -DENABLE_CTEST=OFF -DGLSLANG_TESTS=OFF -DCMAKE_OSX_ARCHITECTURES=arm64 -DCMAKE_OSX_DEPLOYMENT_TARGET=13.0 \
+ -DCMAKE_EXE_LINKER_FLAGS='-Wl,-S,-x' > "$WORK/glslang.log" 2>&1 \
+ && cmake --build "$WORK/glslang-build" --target glslang-standalone -j "$JOBS" >> "$WORK/glslang.log" 2>&1 || { tail -30 "$WORK/glslang.log"; exit 1; }
+cp -L "$WORK/glslang-build/StandAlone/glslang" "$BIN/glslangValidator" # glslang's own name for it is a link to the same program
+cp "$WORK/glslang/LICENSE.txt" "$LIC/glslang-LICENSE.txt"
+
+# SPIRV-Cross: the command line tool (static; the same options as the repo's spirv_cross_bin/build.sh, for arm64 only)
+echo "== spirv-cross $SPIRV_CROSS_TAG"
+unpack "$(fetch "$SPIRV_CROSS_URL" "$SPIRV_CROSS_SHA256")" "$WORK/spirv-cross"
+cmake -S "$WORK/spirv-cross" -B "$WORK/spirv-cross-build" -DCMAKE_BUILD_TYPE=Release -DSPIRV_CROSS_ENABLE_TESTS=OFF -DSPIRV_CROSS_SKIP_INSTALL=ON \
+ -DCMAKE_OSX_ARCHITECTURES=arm64 -DCMAKE_OSX_DEPLOYMENT_TARGET=13.0 -DCMAKE_EXE_LINKER_FLAGS='-Wl,-S,-x' > "$WORK/spirv-cross.log" 2>&1 \
+ && cmake --build "$WORK/spirv-cross-build" --target spirv-cross -j "$JOBS" >> "$WORK/spirv-cross.log" 2>&1 || { tail -30 "$WORK/spirv-cross.log"; exit 1; }
+cp "$WORK/spirv-cross-build/spirv-cross" "$BIN/spirv-cross"
+cp "$WORK/spirv-cross/LICENSE" "$LIC/spirv-cross-LICENSE"
+mkdir -p "$LIC/spirv-cross-LICENSES"; cp "$WORK/spirv-cross/LICENSES/"* "$LIC/spirv-cross-LICENSES/"
+
+# xcodegen: the release's bin/xcodegen and share/xcodegen (SettingPresets), which it finds at ../share/xcodegen from its own folder
+echo "== xcodegen $XCODEGEN_VERSION"
+rm -rf "$WORK/xcodegen"; mkdir -p "$WORK/xcodegen"
+ditto -x -k "$(fetch "$XCODEGEN_URL" "$XCODEGEN_SHA256")" "$WORK/xcodegen"
+XG=$(find "$WORK/xcodegen" -name xcodegen -type f -perm -u+x -path '*/bin/*' | head -1)
+[ -n "$XG" ] || { echo "[RED] no bin/xcodegen in the release zip" >&2; exit 1; }
+XGROOT=$(dirname "$(dirname "$XG")")
+cp "$XG" "$BIN/xcodegen"; chmod 755 "$BIN/xcodegen"
+cp -R "$XGROOT/share/xcodegen" "$RES/tools/share/xcodegen"
+cp "$XGROOT/LICENSE" "$LIC/xcodegen-LICENSE" 2>/dev/null || curl -fsSL "https://raw.githubusercontent.com/yonaskolb/XcodeGen/$XCODEGEN_VERSION/LICENSE" -o "$LIC/xcodegen-LICENSE"
+
+# Python: python-build-standalone's install_only build runs from wherever it is (its libpython is @executable_path/../lib), and the packages
+# are installed into it now, from the pinned list, so nothing is downloaded on the player's Mac.
+echo "== python $PYTHON_VERSION"
+PYTAR=$(fetch "$PYTHON_URL" "$PYTHON_SHA256")
+rm -rf "$WORK/python-x"; mkdir -p "$WORK/python-x"; tar -xzf "$PYTAR" -C "$WORK/python-x"
+mv "$WORK/python-x/python" "$RES/python"
+PY="$RES/python/bin/python3"
+"$PY" -I -m pip install --disable-pip-version-check --no-warn-script-location --only-binary :all: -r "$HERE/bundled-python-requirements.txt" > "$WORK/pip.log" 2>&1 || { tail -30 "$WORK/pip.log"; exit 1; }
+# pip writes console scripts (nsz, fonttools, ...) whose first line names this build's absolute path: they cannot work from the player's copy
+# (the build script starts nsz as `python -c`, and nothing else is called by name), so they go. A script of python-build-standalone's own
+# (pip3) is a /bin/sh stub and stays.
+for s in "$RES/python/bin/"*; do
+ [ -f "$s" ] && [ ! -L "$s" ] && head -c 2 "$s" | grep -q '#!' && grep -q "$RES" "$s" && rm -f "$s"
+done
+# What a build never runs: Python's own test suite, IDLE, the turtle demos and Tk (the NSP script has no window)
+SITE="$RES/python/lib/python${PYTHON_VERSION%.*}"
+rm -rf "$SITE/test" "$SITE/idlelib" "$SITE/turtledemo" "$SITE/tkinter" "$SITE/lib-dynload/_tkinter"*.so \
+ "$RES/python/lib/tcl"* "$RES/python/lib/tk"* "$RES/python/lib/itcl"* "$RES/python/lib/thread"* "$RES/python/lib/libtcl"* "$RES/python/lib/libtk"* "$RES/python/share/man" 2>/dev/null || true
+find "$RES/python" -type d -name tests -path '*site-packages*' -prune -exec rm -rf {} + 2>/dev/null || true
+cp "$SITE/LICENSE.txt" "$LIC/python-LICENSE.txt" 2>/dev/null || true
+mkdir -p "$LIC/python-packages"
+for d in "$SITE/site-packages/"*.dist-info; do
+ n=$(basename "$d" .dist-info); mkdir -p "$LIC/python-packages/$n"
+ find "$d" -maxdepth 2 \( -iname 'LICEN[SC]E*' -o -iname 'COPYING*' -o -iname 'NOTICE*' \) -type f -exec cp {} "$LIC/python-packages/$n/" \;
+done
+"$PY" -I - <<'PYEOF'
+import lz4.block, capstone, fontTools, nsz, ssl, sqlite3, zlib, lzma, bz2
+try: from compression import zstd
+except ImportError: from backports import zstd
+PYEOF
+
+# Every Mach-O file is signed on its own first: `codesign --deep` of the app signs only code in the places a bundle names (MacOS,
+# Frameworks, ...), not what sits in Resources, and a copy of a binary whose load paths or content changed keeps its old signature.
+echo "== ad-hoc signing the nested code"
+n=0
+while IFS= read -r -d '' f; do
+ if file -b "$f" | grep -q 'Mach-O'; then codesign --force --sign - "$f" 2> /dev/null && n=$((n + 1)); fi
+done < <(find "$RES/tools" "$RES/python" -type f -print0)
+echo "signed $n Mach-O files"
+du -sh "$RES/tools" "$RES/python"
diff --git a/frontend/tools/bundled-python-requirements.txt b/frontend/tools/bundled-python-requirements.txt
new file mode 100644
index 00000000..f0f2300c
--- /dev/null
+++ b/frontend/tools/bundled-python-requirements.txt
@@ -0,0 +1,15 @@
+# The Python packages bundled into the launcher (bundle_tools.sh installs them with --only-binary into the bundled CPython).
+# The first five are what BuildModel.pipPackages names (BundledToolsTests keeps them equal); backports.zstd is for Python before 3.14 and
+# the bundled one is 3.13. The rest are what nsz needs, pinned as resolved on 2026-10-28 (pip freeze of a clean install).
+backports.zstd==1.8.0
+capstone==5.0.9
+fonttools==4.68.0
+lz4==4.4.5
+nsz==5.0.0
+blessed==1.52.0
+enlighten==1.14.1
+jinxed==2.1.0
+prefixed==0.9.0
+pycryptodome==4.2.0
+wcwidth==0.9.4
+zstandard==0.25.0
diff --git a/frontend/tools/check_bundle.sh b/frontend/tools/check_bundle.sh
new file mode 100755
index 00000000..36944982
--- /dev/null
+++ b/frontend/tools/check_bundle.sh
@@ -0,0 +1,43 @@
+#!/bin/bash
+# Checks an assembled launcher bundle the way a player's Mac uses it: every bundled tool starts from the bundle with a clean PATH (nothing of
+# Homebrew or the system Python), nothing links into /opt/homebrew or /usr/local, and the code signature holds.
+# Usage: check_bundle.sh <NX2Apple.app or a folder that holds tools/ and python/> [--sign] (--sign: also ad-hoc sign the app and verify it)
+set -uo pipefail
+APP=${1:?usage: check_bundle.sh <app> [--sign]}
+if [ -d "$APP/Contents/Resources" ]; then RES="$APP/Contents/Resources"; else RES="$APP"; fi
+fail=0
+ok() { echo "ok $*"; }
+bad() { echo "FAIL $*"; fail=1; }
+clean() { env -i PATH=/usr/bin:/bin HOME="${TMPDIR:-/tmp}" "$@"; } # no PATH entry but the system's, and the tool by its full path
+
+T="$RES/tools/bin"
+v=$(clean "$T/zstd" --version 2>&1) && ok "zstd: $v" || bad "zstd --version: $v"
+v=$(clean "$T/glslangValidator" --version 2>&1 | head -2 | tr '\n' ' ') && [ -n "$v" ] && ok "glslangValidator: $v" || bad "glslangValidator --version"
+v=$(clean "$T/spirv-cross" --help 2>&1); echo "$v" | grep -qi 'usage' && ok "spirv-cross --help: $(echo "$v" | grep -i usage | head -1)" || bad "spirv-cross --help: $v"
+v=$(clean "$T/xcodegen" --version 2>&1) && ok "xcodegen: $v" || bad "xcodegen --version: $v"
+# the tools by name, from a PATH that has only the bundle and the system (what the launcher passes)
+for t in zstd glslangValidator spirv-cross xcodegen; do
+ p=$(env -i PATH="$T:/usr/bin:/bin" /usr/bin/which "$t") && [ "$p" = "$T/$t" ] && ok "PATH finds $t in the bundle" || bad "PATH finds $t at '$p'"
+done
+PY="$RES/python/bin/python3"
+v=$(clean "$PY" -I -c "import sys, lz4.block, capstone, fontTools, nsz; from compression import zstd" 2>&1 \
+ || clean "$PY" -I -c "import lz4.block, capstone, fontTools, nsz; from backports import zstd" 2>&1) && ok "python imports lz4, capstone, fontTools, nsz, zstd" || bad "python imports: $v"
+v=$(clean "$PY" -I -c "import sys; print(sys.version.split()[0], sys.prefix)" 2>&1); echo "$v" | grep -q "$RES/python" && ok "python runs from the bundle: $v" || bad "python prefix is not the bundle: $v"
+
+# load paths: only the system's (a library's or extension's own install name is not a dependency)
+links=0
+while IFS= read -r -d '' f; do
+ file -b "$f" | grep -q 'Mach-O' || continue
+ out=$(otool -L "$f" 2>/dev/null | tail -n +2 | awk '{print $1}' | grep -v -x -F "$f" | grep -v -e '^/usr/lib/' -e '^/System/Library/' -e '^@rpath/' -e '^@loader_path/' -e '^@executable_path/') || true
+ [ -z "$out" ] || { bad "${f#$RES/} links: $(echo "$out" | tr '\n' ' ')"; links=1; }
+ min=$(otool -l "$f" 2>/dev/null | awk '/minos/{print $2; exit}')
+ [ -z "$min" ] || [ "$(printf '%s\n13.0\n' "$min" | sort -V | tail -1)" = 13.0 ] || { bad "${f#$RES/} needs macOS $min (the app runs from 13.0)"; links=1; }
+ otool -L "$f" 2>/dev/null | grep -q -e '/opt/homebrew' -e '/usr/local' && { bad "${f#$RES/} links into Homebrew"; links=1; }
+done < <(find "$RES/tools" "$RES/python" -type f -print0)
+[ "$links" = 0 ] && ok "no Mach-O file links outside the system or the bundle, and none needs macOS later than 13.0"
+
+if [ "${2:-}" = "--sign" ] && [ -d "$APP/Contents" ]; then
+ codesign --force --deep --sign - "$APP" 2>&1 | tail -3
+ codesign -v --deep --strict "$APP" 2>&1 && ok "codesign -v --deep --strict" || bad "codesign -v --deep --strict"
+fi
+exit $fail