Skip to content

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

iOS shell: let each game framework carry its own host (#451)

LNPANDYaf24bd435895
diff --git a/frontend-ios/Sources/ShellHost/GameCatalogue.swift b/frontend-ios/Sources/ShellHost/GameCatalogue.swift
index 17a15dd5..ad4fb511 100644
--- a/frontend-ios/Sources/ShellHost/GameCatalogue.swift
+++ b/frontend-ios/Sources/ShellHost/GameCatalogue.swift
@@ -249,12 +249,12 @@ public enum DataLocator {
}
/// Derives the state a tile shows from what is present: a bundle that cannot run is broken with its reason, a game
-/// built for another chain or a newer OS needs an app update, a game without reachable data needs game data.
+/// built for another chain (when its framework has no host of its own) or a newer OS needs an app update, a game without reachable data needs game data.
public enum GameStateResolver {
public static func state(for entry: CatalogueEntry, data: DataResolution, environment: HostEnvironment) -> GameState {
if let problem = entry.problem { return problem.state }
guard let manifest = entry.manifest else { return GameProblem(cause: .manifestMissing, reason: hostText("Game manifest missing")).state }
- if let chain = environment.chain, chain != manifest.chain { return .needsAppUpdate }
+ if manifest.loader != "FH", let chain = environment.chain, chain != manifest.chain { return .needsAppUpdate }
if let min = manifest.minOSVersion, !isVersion(environment.osVersion, atLeast: min) { return .needsAppUpdate }
return data.found ? .playable : .needsGameData
}
diff --git a/frontend-ios/Tests/ShellHostTests/CatalogueStateTests.swift b/frontend-ios/Tests/ShellHostTests/CatalogueStateTests.swift
index cf1e784c..d600a8c4 100644
--- a/frontend-ios/Tests/ShellHostTests/CatalogueStateTests.swift
+++ b/frontend-ios/Tests/ShellHostTests/CatalogueStateTests.swift
@@ -71,6 +71,10 @@ import ShellUI
#expect(GameStateResolver.state(for: entry(Fixtures.chain), data: .missing, environment: env) == .needsAppUpdate)
// A host without an engine (the demo) skips the chain check.
#expect(GameStateResolver.state(for: entry(Fixtures.chain), data: found, environment: HostEnvironment(chain: nil, osVersion: env.osVersion)) == .playable)
+ // A framework that carries its own host (loader FH, #451) runs on any shell chain.
+ var fh = entry(Fixtures.chain); fh.manifest?.loader = "FH"
+ #expect(GameStateResolver.state(for: fh, data: found, environment: env) == .playable)
+ #expect(GameStateResolver.state(for: fh, data: .missing, environment: env) == .needsGameData)
}
@Test func brokenBundlesAreBrokenWhateverElseIsPresent() {
diff --git a/frontend/Sources/NXCore/StaleFrameworks.swift b/frontend/Sources/NXCore/StaleFrameworks.swift
index a2cd3eb9..e42b29a0 100644
--- a/frontend/Sources/NXCore/StaleFrameworks.swift
+++ b/frontend/Sources/NXCore/StaleFrameworks.swift
@@ -1,9 +1,9 @@
import Foundation
-/// LNPANDY/NX2Apple#449: the shared iPhone and iPad app takes frameworks of one shader chain only. After an engine update that
-/// changes the chain, the frameworks already in the shell folder are stale, and build_shell.sh refuses them at the last step.
-/// This finds them before the long steps. The chain of the engine is the `DMSH_CHAIN` of `dm/gfx/nvn/dmsh_chain.h` (the
-/// `b-<chain>` folder name), the chain of a framework is the `chain` of its `game.manifest.json`, the two values the script compares.
+/// LNPANDY/NX2Apple#449, #451: each game framework built for the shared app now carries its own host (`loader == "FH"` in
+/// `game.manifest.json`), so an engine update that changes the shader chain leaves every installed game working. Only a
+/// framework built before #451 (`loader != "FH"`, no host in the framework) is refused by `build_shell.sh` and found here
+/// before the long build steps.
package enum StaleFrameworks {
package struct Entry: Equatable {
package var titleID: String
@@ -23,20 +23,22 @@ package enum StaleFrameworks {
return nil
}
- /// The manifest of a framework folder: its `chain`, `title_id` and `name`. nil when it has none or it cannot be read.
- private static func manifest(of framework: String) -> (chain: String, titleID: String, name: String)? {
+ /// The manifest of a framework folder: its `chain`, `title_id`, `name` and `loader`. nil when it has none or it cannot be read.
+ private static func manifest(of framework: String) -> (chain: String, titleID: String, name: String, loader: String)? {
guard let data = FileManager.default.contents(atPath: framework + "/game.manifest.json"),
let json = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any],
let chain = json["chain"] as? String else { return nil }
- return (chain, json["title_id"] as? String ?? "", json["name"] as? String ?? "")
+ return (chain, json["title_id"] as? String ?? "", json["name"] as? String ?? "", json["loader"] as? String ?? "FR")
}
- /// The frameworks of another chain than `chain`: those in the shell folder's mirror (`<root>/frameworks`) and those the
- /// library names (`known`: title ID, name and framework folder of each game in shell.json). One entry per title ID, with every
- /// folder that holds it. A framework whose manifest cannot be read is not decided here: build_shell.sh's own check stays
- /// for it. `except` is the game being built now, whose framework this build replaces.
+ /// The frameworks built without a host of their own (`loader != "FH"`): those in the shell folder's mirror
+ /// (`<root>/frameworks`) and those the library names (`known`: title ID, name and framework folder of each game in
+ /// `shell.json`). Frameworks with `loader == "FH"` carry their own host and stay valid across shader chain updates (#451).
+ /// One entry per title ID, with every folder that holds it. A framework whose manifest cannot be read is not decided here:
+ /// `build_shell.sh`'s own check stays for it. `except` is the game being built now, whose framework this build replaces.
package static func find(root: String, chain: String, known: [(titleID: String, name: String, framework: String)],
except: String? = nil) -> [Entry] {
+ _ = chain
let fm = FileManager.default
let mirror = root + "/frameworks"
var folders = known.map(\.framework)
@@ -46,7 +48,7 @@ package enum StaleFrameworks {
var entries: [Entry] = []
var seen = Set<String>()
for folder in folders where seen.insert(folder).inserted && fm.fileExists(atPath: folder) {
- guard let m = manifest(of: folder), m.chain != chain else { continue }
+ guard let m = manifest(of: folder), m.loader != "FH" else { continue }
let id = m.titleID.isEmpty ? titleID(ofFolder: folder) : m.titleID
if let except, except.caseInsensitiveCompare(id) == .orderedSame { continue }
if let i = entries.firstIndex(where: { $0.titleID.caseInsensitiveCompare(id) == .orderedSame }) {
diff --git a/frontend/Tests/NX2AppleTests/StaleFrameworksTests.swift b/frontend/Tests/NX2AppleTests/StaleFrameworksTests.swift
index 66c087be..e5a005f1 100644
--- a/frontend/Tests/NX2AppleTests/StaleFrameworksTests.swift
+++ b/frontend/Tests/NX2AppleTests/StaleFrameworksTests.swift
@@ -20,10 +20,10 @@ import NXModel
override func tearDownWithError() throws { try? FileManager.default.removeItem(atPath: tmp) }
- private func framework(_ titleID: String, name: String, chain: String) throws -> String {
+ private func framework(_ titleID: String, name: String, chain: String, loader: String = "FH") throws -> String {
let fw = tmp + "/shell/frameworks/DmGame\(titleID).framework"
try FileManager.default.createDirectory(atPath: fw, withIntermediateDirectories: true)
- let manifest = ["title_id": titleID, "name": name, "chain": chain, "framework": "DmGame\(titleID).framework"]
+ let manifest = ["title_id": titleID, "name": name, "chain": chain, "loader": loader, "framework": "DmGame\(titleID).framework"]
try JSONSerialization.data(withJSONObject: manifest).write(to: URL(fileURLWithPath: fw + "/game.manifest.json"))
try "binary".write(toFile: fw + "/DmGame\(titleID)", atomically: true, encoding: .utf8)
return fw
@@ -32,8 +32,8 @@ import NXModel
private func exists(_ path: String) -> Bool { FileManager.default.fileExists(atPath: path) }
private func shell() throws -> (stale: String, fresh: String) {
- let stale = try framework(oldID, name: "Old Game", chain: old)
- let fresh = try framework(newID, name: "Fresh Game", chain: current)
+ let stale = try framework(oldID, name: "Old Game", chain: old, loader: "FR")
+ let fresh = try framework(newID, name: "Fresh Game", chain: current, loader: "FH")
var library = ShellLibrary()
library.add(ShellLibrary.Game(titleID: oldID, name: "Old Game", framework: stale))
library.add(ShellLibrary.Game(titleID: newID, name: "Fresh Game", framework: fresh))
@@ -60,8 +60,9 @@ import NXModel
XCTAssertEqual(entries.first?.chain, old)
}
- func testNothingIsAskedWhenEveryFrameworkIsCurrent() throws {
- _ = try framework(newID, name: "Fresh Game", chain: current)
+ func testNothingIsAskedWhenEveryFrameworkCarriesItsOwnHostEvenAcrossChains() throws {
+ _ = try framework(oldID, name: "Old Chain Game", chain: old, loader: "FH")
+ _ = try framework(newID, name: "Fresh Game", chain: current, loader: "FH")
XCTAssertEqual(found(), [])
XCTAssertEqual(StaleFrameworks.find(root: tmp + "/empty", chain: current, known: []), [])
}
diff --git a/patches/0075-host-read-embedded-sections-from-the-image-that.patch b/patches/0075-host-read-embedded-sections-from-the-image-that.patch
new file mode 100644
index 00000000..f28df168
--- /dev/null
+++ b/patches/0075-host-read-embedded-sections-from-the-image-that.patch
@@ -0,0 +1,182 @@
+From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
+From: LNPANDY <[email protected]>
+Date: Thu, 5 Nov 2026 23:02:30 +0800
+Subject: [PATCH] host: read embedded sections from the image that holds the
+ host (DM_HOST_IMAGE)
+
+Define DM_HOST_IMAGE as &__dso_handle in dm/host/host_image.h and pass it to getsectiondata and loader image checks in hle.c, loader.c, hle_jit.c, hle_nvn.c, hle_vk.m and hle_gl.m. In the main executable __dso_handle aliases _mh_execute_header; in a dynamic framework it resolves to that framework's Mach-O header so the HLE registration tables (__DATA,swhle, __DATA,swforce, __DATA,swnvn, __DATA,swvk and __DATA,swgl) are found in the image that holds the host.
+
+Upstream-Status: pending
+Reason: Let the host read its Mach-O sections when linked into a dynamic framework as well as the main executable
+Issue: LNPANDY/NX2Apple#451
+---
+ dm/gfx/gl/hle_gl.m | 5 ++---
+ dm/gfx/nvn/hle_nvn.c | 5 ++---
+ dm/gfx/vk/hle_vk.m | 5 ++---
+ dm/host/hle.c | 5 ++---
+ dm/host/hle_jit.c | 5 ++---
+ dm/host/host_image.h | 8 ++++++++
+ dm/host/loader.c | 7 +++----
+ 7 files changed, 21 insertions(+), 19 deletions(-)
+ create mode 100644 dm/host/host_image.h
+
+diff --git a/dm/gfx/gl/hle_gl.m b/dm/gfx/gl/hle_gl.m
+index f3e38a1..dc6edac 100644
+--- a/dm/gfx/gl/hle_gl.m
++++ b/dm/gfx/gl/hle_gl.m
+@@ -23,8 +23,7 @@
+ #import <Metal/Metal.h>
+ #include <CommonCrypto/CommonDigest.h>
+ #include <mach/mach.h>
+-#include <mach-o/getsect.h>
+-#include <mach-o/ldsyms.h>
++#include "../../host/host_image.h"
+ #include <math.h>
+ #include <stdatomic.h>
+ #include <time.h>
+@@ -2025,7 +2024,7 @@ static void frame_end(void) {
+ // eglGetProcAddress: GL names from the same table as direct imports; anything else is null (the game's loader asks for every GL name it knows)
+ static void *gl_lookup(const char *name) {
+ static const hle_ent *sec; static unsigned long sz;
+- if (!sec) sec = (const hle_ent *)getsectiondata(&_mh_execute_header, "__DATA", "swhle", &sz);
++ if (!sec) sec = (const hle_ent *)getsectiondata(DM_HOST_IMAGE, "__DATA", "swhle", &sz);
+ for (unsigned long i = 0; i < sz / sizeof *sec; i++) if (!strcmp(sec[i].name, name)) return sec[i].fn;
+ return NULL;
+ }
+diff --git a/dm/gfx/nvn/hle_nvn.c b/dm/gfx/nvn/hle_nvn.c
+index 381c3c8..6e4a638 100644
+--- a/dm/gfx/nvn/hle_nvn.c
++++ b/dm/gfx/nvn/hle_nvn.c
+@@ -38,8 +38,7 @@
+ #include <mach/thread_policy.h>
+ #include <assert.h>
+ #include <stdatomic.h>
+-#include <mach-o/getsect.h>
+-#include <mach-o/ldsyms.h>
++#include "../../host/host_image.h"
+
+ // ---------- Slot table, thunks, unimplemented stubs ----------
+ typedef struct { _Atomic uint64_t cnt; void *fn; } nvn_slot_t;
+@@ -95,7 +94,7 @@ static void nvn_init_slots(void) {
+ static int done; if (done) return; done = 1;
+ g_log = getenv("DM_NVN_LOG") != NULL;
+ unsigned long sz;
+- const nvn_impl *im = (const nvn_impl *)getsectiondata(&_mh_execute_header, "__DATA", "swnvn", &sz);
++ const nvn_impl *im = (const nvn_impl *)getsectiondata(DM_HOST_IMAGE, "__DATA", "swnvn", &sz);
+ unsigned nim = im ? (unsigned)(sz / sizeof *im) : 0, hit = 0;
+ for (unsigned i = 0; i < NVN_NFUNC; i++) nvn_slot[i].fn = (void *)nvn_unimpl_entry;
+ for (unsigned k = 0; k < nim; k++) {
+diff --git a/dm/gfx/vk/hle_vk.m b/dm/gfx/vk/hle_vk.m
+index 3728dff..bbe5bba 100644
+--- a/dm/gfx/vk/hle_vk.m
++++ b/dm/gfx/vk/hle_vk.m
+@@ -21,8 +21,7 @@
+ #import <Metal/Metal.h>
+ #include <CommonCrypto/CommonDigest.h>
+ #include <CoreFoundation/CoreFoundation.h>
+-#include <mach-o/getsect.h>
+-#include <mach-o/ldsyms.h>
++#include "../../host/host_image.h"
+ #include <math.h>
+ #include <stdatomic.h>
+ #include <time.h>
+@@ -1743,7 +1742,7 @@ static void frame_end(void) {
+ static void *vk_lookup(const char *name) {
+ static const hle_ent *sec; static unsigned long sz;
+ if (!name || strncmp(name, "vk", 2)) return NULL;
+- if (!sec) sec = (const hle_ent *)getsectiondata(&_mh_execute_header, "__DATA", "swhle", &sz);
++ if (!sec) sec = (const hle_ent *)getsectiondata(DM_HOST_IMAGE, "__DATA", "swhle", &sz);
+ void *fn = NULL; size_t n = strlen(name);
+ for (int pass = 0; pass < 2 && !fn; pass++) {
+ size_t len = pass ? n - 3 : n;
+diff --git a/dm/host/hle.c b/dm/host/hle.c
+index 672c16a..50bd6e6 100644
+--- a/dm/host/hle.c
++++ b/dm/host/hle.c
+@@ -1,7 +1,6 @@
+ // Import resolution (implemented ones go to the host, the rest go to named stubs) and host gate dispatch.
+ #include "hle.h"
+-#include <mach-o/getsect.h>
+-#include <mach-o/ldsyms.h>
++#include "host_image.h"
+ #include <dlfcn.h>
+ #include <time.h>
+
+@@ -32,7 +31,7 @@ static unsigned *g_hle_idx, g_hle_mask; static const hle_ent *g_hle_sec;
+ static const hle_ent *hle_find(const char *name) {
+ if (!g_hle_mask) {
+ unsigned long secsz;
+- g_hle_sec = (const hle_ent *)getsectiondata(&_mh_execute_header, "__DATA", "swhle", &secsz);
++ g_hle_sec = (const hle_ent *)getsectiondata(DM_HOST_IMAGE, "__DATA", "swhle", &secsz);
+ unsigned n = g_hle_sec ? (unsigned)(secsz / sizeof *g_hle_sec) : 0;
+ unsigned cap = 16; while (cap < n * 2) cap <<= 1;
+ g_hle_idx = calloc(cap, sizeof *g_hle_idx); g_hle_mask = cap - 1;
+diff --git a/dm/host/hle_jit.c b/dm/host/hle_jit.c
+index 6e1d614..aa99f11 100644
+--- a/dm/host/hle_jit.c
++++ b/dm/host/hle_jit.c
+@@ -145,15 +145,14 @@ static const jit_req *jit_find(const char *key) { for (int i = 0; i < g_nreq; i+
+ // The image at the layout's base: the Mac maps jit.img read + execute, iOS remaps the executable's signed __TEXT,__dm<tag>_jit pages there (as loader.c remaps the modules)
+ #if TARGET_OS_IPHONE
+ #include <mach/mach.h>
+-#include <mach-o/getsect.h>
+-#include <mach-o/ldsyms.h>
++#include "host_image.h"
+ #endif
+ static void jit_map_image(uint8_t *at, const char *dir) {
+ if (!g_img_size) return;
+ #if TARGET_OS_IPHONE
+ (void)dir; unsigned long z = 0; char sn[17]; const char *tg = getenv("DM_EMBED_TAG"); // an app of several programs tags each one's sections (gen_embed.py --tag)
+ snprintf(sn, sizeof sn, "__dm%s_jit", tg ? tg : "");
+- const uint8_t *sec = getsectiondata(&_mh_execute_header, "__TEXT", sn, &z);
++ const uint8_t *sec = getsectiondata(DM_HOST_IMAGE, "__TEXT", sn, &z);
+ if (!sec || z < g_img_size || ((uintptr_t)sec & 0x3fff)) die("jit: the image is not in the executable (__TEXT,%s), or smaller than jit.tsv says", sn);
+ vm_address_t a = (vm_address_t)at; vm_prot_t cur = 0, max = 0;
+ if (vm_remap(mach_task_self(), &a, g_img_size, 0, VM_FLAGS_FIXED | VM_FLAGS_OVERWRITE, mach_task_self(), (vm_address_t)sec, FALSE, &cur, &max, VM_INHERIT_NONE) != KERN_SUCCESS || a != (vm_address_t)at || !(cur & VM_PROT_EXECUTE))
+diff --git a/dm/host/host_image.h b/dm/host/host_image.h
+new file mode 100644
+index 0000000..9dde850
+--- /dev/null
++++ b/dm/host/host_image.h
+@@ -0,0 +1,8 @@
++// The Mach-O header of the image that holds the host: the executable in a normal build, the framework's dylib when the host is
++// linked as a framework. The linker defines __dso_handle at the start of every image, executable and dylib alike, and
++// getsectiondata() takes it as the mach_header_64 *.
++#pragma once
++#include <mach-o/getsect.h>
++
++extern const struct mach_header_64 __dso_handle;
++#define DM_HOST_IMAGE (&__dso_handle)
+diff --git a/dm/host/loader.c b/dm/host/loader.c
+index 5bc0117..1187658 100644
+--- a/dm/host/loader.c
++++ b/dm/host/loader.c
+@@ -8,9 +8,8 @@
+ #include <sys/stat.h>
+ #include <unistd.h>
+ #include <limits.h>
+-#include <mach-o/getsect.h>
+-#include <mach-o/ldsyms.h>
+ #include "hle.h"
++#include "host_image.h"
+ #if TARGET_OS_IPHONE
+ #include <mach/mach.h>
+ #endif
+@@ -214,7 +213,7 @@ static uint64_t resolve_sym(module_t *m, const char *name) {
+ static const hle_force_ent *g_force; static unsigned g_nforce; static unsigned *g_force_hits;
+ static unsigned *g_fidx, g_fmask; // name hash over the table: force_lookup runs for every named relocation, and each lookup used to strcmp its way through all 722 entries (the swhle table's scan is hashed the same way, hle.c)
+ static void force_init(void) {
+- unsigned long sz; g_force = (const hle_force_ent *)getsectiondata(&_mh_execute_header, "__DATA", "swforce", &sz);
++ unsigned long sz; g_force = (const hle_force_ent *)getsectiondata(DM_HOST_IMAGE, "__DATA", "swforce", &sz);
+ g_nforce = g_force ? (unsigned)(sz / sizeof *g_force) : 0;
+ g_force_hits = calloc(g_nforce + 1, sizeof *g_force_hits);
+ unsigned cap = 16; while (cap < g_nforce * 2) cap <<= 1;
+@@ -707,7 +706,7 @@ static void remap_at(module_t *m, vm_address_t to, const void *from, unsigned lo
+ }
+ // The image the module sections are read from (front.h dm_set_game_image_header). getsectiondata takes any loaded image's header and applies its slide
+ #include "front.h"
+-static const struct mach_header_64 *g_game_image = &_mh_execute_header;
++static const struct mach_header_64 *g_game_image = DM_HOST_IMAGE;
+ void dm_set_game_image_header(const void *mh) { g_game_image = mh; }
+ #define IMAGE_MH g_game_image
+ // The NRO modules (loader.c "NRO modules") are packed instead of getting sections of their own: a Mach-O file has at most 255 sections, and Super Smash Bros. Ultimate's 98 NROs would
diff --git a/patches/0076-ios-shell-link-the-host-into-each-game-s-framewo.patch b/patches/0076-ios-shell-link-the-host-into-each-game-s-framewo.patch
new file mode 100644
index 00000000..0a6c0db1
--- /dev/null
+++ b/patches/0076-ios-shell-link-the-host-into-each-game-s-framewo.patch
@@ -0,0 +1,631 @@
+From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
+From: LNPANDY <[email protected]>
+Date: Thu, 5 Nov 2026 23:34:11 +0800
+Subject: [PATCH] iOS shell: link the host into each game's framework so engine
+ updates keep installed games playable
+
+Add the DmShellGame target in project-framework.yml and dm/ios/framework/ShellGlue.m so build_ipa.sh DM_FRAMEWORK_ONLY builds each shell game's DmGame<title ID>.framework with its own host, shader chain and compiled game_profile.h (manifest loader FH), compiling Sources/GameMenu.swift and Sources/LauncherSettings.swift directly into DmShellGame. Trim DmShell in project-shell.yml, build_shell.sh and ShellMain.m to a thin launcher that dlopens the chosen game's framework and enters its host through dm_glue_start_game, dm_glue_present_game and dm_glue_focus_event.
+
+Upstream-Status: fork-only
+Reason: Each shell framework links its own host so engine updates never invalidate installed games
+Issue: LNPANDY/NX2Apple#451
+---
+ dm/ios/Shell/Shell-Bridging-Header.h | 1 -
+ dm/ios/Shell/ShellGlue.h | 11 +++
+ dm/ios/Shell/ShellMain.m | 101 ++++++++++-----------------
+ dm/ios/framework/ShellGlue.m | 77 ++++++++++++++++++++
+ dm/ios/project-framework.yml | 56 +++++++++++++++
+ dm/ios/project-shell.yml | 12 +---
+ dm/ios/tests/test_framework_link.py | 66 +++++++++++++++++
+ dm/ios/tests/test_shell_build.py | 31 ++++----
+ dm/ios/tools/build_ipa.sh | 7 +-
+ dm/ios/tools/build_shell.sh | 18 ++---
+ dm/ios/tools/gen_manifest.py | 4 +-
+ 11 files changed, 282 insertions(+), 102 deletions(-)
+ create mode 100644 dm/ios/Shell/ShellGlue.h
+ create mode 100644 dm/ios/framework/ShellGlue.m
+
+diff --git a/dm/ios/Shell/Shell-Bridging-Header.h b/dm/ios/Shell/Shell-Bridging-Header.h
+index d7f5196..bf778b2 100644
+--- a/dm/ios/Shell/Shell-Bridging-Header.h
++++ b/dm/ios/Shell/Shell-Bridging-Header.h
+@@ -1,3 +1,2 @@
+ // What ShellApp.swift calls in the engine glue (ShellMain.m).
+ #include "ShellEngine.h"
+-#include "../Sources/DmGameMenu.h" // GameMenu.swift, the in-game menu (dm/ios/Sources)
+diff --git a/dm/ios/Shell/ShellGlue.h b/dm/ios/Shell/ShellGlue.h
+new file mode 100644
+index 0000000..e5b52e2
+--- /dev/null
++++ b/dm/ios/Shell/ShellGlue.h
+@@ -0,0 +1,11 @@
++// Route C shell (LNPANDY/NX2Apple#451): the entry points each game's DmGame<title ID>.framework exports for ShellMain.m to
++// look up with dlsym on the handle it dlopens at Play. Each game framework links its own dm/host, front_ios.m and shaders, so an
++// engine update never invalidates the games already in the shell.
++#pragma once
++
++// Bumped only when a signature below changes: a shell refuses a framework whose dm_glue_version does not match.
++#define DM_GLUE_VERSION 1
++
++typedef const char *(*dm_glue_start_fn)(const char *const *argv, int argc, const void *game_image);
++typedef void (*dm_glue_present_fn)(void *window);
++typedef void (*dm_glue_focus_fn)(int ev);
+diff --git a/dm/ios/Shell/ShellMain.m b/dm/ios/Shell/ShellMain.m
+index 77d7ca3..7fb0bfc 100644
+--- a/dm/ios/Shell/ShellMain.m
++++ b/dm/ios/Shell/ShellMain.m
+@@ -1,29 +1,22 @@
+-// Route C shell (docs/launcher-c-plan.md M2): the app that hosts the engine and several games' frameworks. It starts on the
++// Route C shell (docs/launcher-c-plan.md M2, LNPANDY/NX2Apple#451): the app that hosts several games' frameworks. It starts on the
+ // library (frontend-ios's ShellHost views, ShellApp.swift) instead of booting a game at launch as dm/ios/Sources/main.m does, and
+-// when the player presses Play, dm_shell_start_game() does what main.m's boot_env() does before UIApplicationMain, for the chosen
+-// game: the log, the environment (EngineLaunchPlan in ShellHost computes it), dlopen of the game's framework and its mach header for
+-// the loader, and the host's early loading. dm_shell_present_game() then hands the window to front_ios.m's game view, which starts
+-// dm_main on the big-stack thread through front_ios_boot() below.
++// when the player presses Play, dm_shell_start_game() sets the log and the environment (EngineLaunchPlan in ShellHost computes it),
++// dlopens the chosen game's DmGame<title ID>.framework (which links its own dm/host, front_ios.m and shaders), and calls its
++// dm_glue_start_game() entry point (ShellGlue.h, framework/ShellGlue.m). dm_shell_present_game() then hands the window to the
++// framework's dm_glue_present_game(), which shows front_ios.m's game view and starts dm_main on the big-stack thread.
+ // One game per process: dm_profile() and dm_host_preload_start() run once, so returning to the library is a relaunch of the app.
+-// This file provides the symbols front_ios.m takes from main.m and Launcher.swift in the one-game app (front_ios_boot,
+-// front_ios_boot_ok, front_ios_boot_message, front_ios_device_check, dm_locate_game_data, dm_show_launcher): the shell compiles front_ios.m unchanged.
+ #import <UIKit/UIKit.h>
+ #include <dlfcn.h>
+-#include <pthread.h>
+-#include <signal.h>
+ #include <stdio.h>
+ #include <string.h>
+-#include <sys/stat.h>
+ #include <unistd.h>
+-#include "front.h"
+ #include "ShellEngine.h"
++#include "ShellGlue.h"
+ #import "DmShell-Swift.h"
+
+-int dm_main(int argc, char **argv); // dm/host/main.c compiled in with -Dmain=dm_main
+-UIViewController *front_ios_root(void);
+-void front_ios_focus_event(int ev);
+-
+-static char **g_argv; static int g_argc; static int g_boot_ok;
++static dm_glue_present_fn g_present;
++static dm_glue_focus_fn g_focus;
++static int g_boot_ok;
+
+ static NSString *documents(void) { return NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES)[0]; }
+
+@@ -52,10 +45,9 @@ static void log_to(NSString *log) {
+ fprintf(stderr, "boot: %s=%s\n", keys[i], values[i]); // every one: a report then shows which of the game's settings reached the engine
+ }
+ if (cwd && *cwd) chdir(cwd);
+- front_hud_env(); // before the early loading below can make a device (main.m's order)
+- // dlopen + dlsym + dladdr hand the framework's mach header to the loader, after the environment and before loading starts
+- // (the design's order, FrameworkBootstrap.m in the one-game app). RTLD_LAZY: only its sections and the marker are needed.
+- void *h = dlopen(executable, RTLD_LAZY);
++ // dlopen + dlsym + dladdr verify the framework's image and find its own host's entry points (ShellGlue.h, framework/ShellGlue.m),
++ // after the environment is set and before the framework's host starts loading.
++ void *h = dlopen(executable, RTLD_LAZY | RTLD_LOCAL);
+ if (!h) {
+ snprintf(err, sizeof err, "The game's code could not be loaded: %s", dlerror() ?: "no reason given");
+ fprintf(stderr, "[RED] boot: dlopen %s failed: %s\n", executable, err);
+@@ -69,11 +61,25 @@ static void log_to(NSString *log) {
+ fprintf(stderr, "[RED] boot: %s: %s\n", executable, err);
+ return err;
+ }
+- dm_set_game_image_header(info.dli_fbase); // valid for the process's life: the framework is never dlclose()d
+- fprintf(stderr, "boot: game framework %s (handle %p, image base %p)\n", executable, h, info.dli_fbase);
+- g_argc = argc; g_argv = calloc((size_t)argc + 1, sizeof(char *));
+- for (int i = 0; i < argc; i++) g_argv[i] = strdup(argv[i]);
+- dm_host_preload_start(g_argc, g_argv); // module tables, relocation and take-over in the background while the game view comes up
++ const int *ver = dlsym(h, "dm_glue_version");
++ dm_glue_start_fn start = (dm_glue_start_fn)dlsym(h, "dm_glue_start_game");
++ dm_glue_present_fn present = (dm_glue_present_fn)dlsym(h, "dm_glue_present_game");
++ dm_glue_focus_fn focus = (dm_glue_focus_fn)dlsym(h, "dm_glue_focus_event");
++ if (!ver || *ver != DM_GLUE_VERSION || !start || !present || !focus) {
++ snprintf(err, sizeof err, "This game's framework was built without its host (glue version %d, expected %d). Rebuild the game in the launcher.",
++ ver ? *ver : 0, DM_GLUE_VERSION);
++ fprintf(stderr, "[RED] boot: %s: %s\n", executable, err);
++ return err;
++ }
++ fprintf(stderr, "boot: game framework %s (handle %p, image base %p, glue v%d)\n", executable, h, info.dli_fbase, *ver);
++ const char *why = start(argv, argc, info.dli_fbase);
++ if (why) {
++ snprintf(err, sizeof err, "%s", why);
++ fprintf(stderr, "[RED] boot: %s: %s\n", executable, err);
++ return err;
++ }
++ g_present = present;
++ g_focus = focus;
+ g_boot_ok = 1;
+ return NULL;
+ }
+@@ -82,40 +88,9 @@ void dm_shell_present_game(void) {
+ UIWindow *window = nil;
+ for (UIScene *s in UIApplication.sharedApplication.connectedScenes)
+ if ([s isKindOfClass:UIWindowScene.class]) for (UIWindow *w in ((UIWindowScene *)s).windows) if (w.isKeyWindow || !window) window = w;
+- if (!window) { fprintf(stderr, "[RED] shell: no window for the game view\n"); return; }
+- UIViewController *game = front_ios_root(); // DmRootVC: landscape, its viewDidAppear starts the game (no settings screen: dm_show_launcher)
+- window.rootViewController = game;
+- [game setNeedsUpdateOfSupportedInterfaceOrientations];
+- [window.windowScene requestGeometryUpdateWithPreferences:[[UIWindowSceneGeometryPreferencesIOS alloc] initWithInterfaceOrientations:UIInterfaceOrientationMaskLandscape]
+- errorHandler:^(NSError *e) { fprintf(stderr, "shell: landscape request: %s\n", e.localizedDescription.UTF8String); }];
+-}
+-
+-// ---- what front_ios.m takes from main.m and Launcher.swift ----
+-static void *boot_thread(void *p) {
+- (void)p;
+- static char alt[65536]; stack_t ss = {.ss_sp = alt, .ss_size = sizeof alt}; sigaltstack(&ss, 0); // crash printing must work on the host thread too
+- int rc = dm_main(g_argc, g_argv);
+- fprintf(stderr, "boot: dm_main returned %d\n", rc);
+- return NULL;
+-}
+-void front_ios_boot(void) { // front_ios.m, once the game view exists
+- static int once; if (once++ || !g_boot_ok) return;
+- void front_ios_audio_session(void); front_ios_audio_session();
+- pthread_attr_t a; pthread_attr_init(&a); pthread_attr_setstacksize(&a, 64u << 20);
+- pthread_t t; pthread_create(&t, &a, boot_thread, NULL); pthread_detach(t);
+-}
+-int front_ios_boot_ok(void) { return g_boot_ok; }
+-const char *front_ios_boot_message(void) { return NULL; }
+-const char *front_ios_device_check(void) { return NULL; } // main.m checks the GPU for the games (no BC textures, seedds#704) when Play is pressed, the shell does its own device handling: NULL = supported
+-// The shell found the data before Play (DataLocator, EngineLaunchPlan): DM_ROMFS is set and the game view only checks it is still there
+-int dm_locate_game_data(void) {
+- const char *r = getenv("DM_ROMFS"); struct stat st;
+- if (r && !stat(r, &st)) return 1;
+- fprintf(stderr, "[RED] shell: the game data at %s is gone\n", r ?: "(not set)");
+- return 0;
++ if (!window || !g_present) { fprintf(stderr, "[RED] shell: no window for the game view\n"); return; }
++ g_present((__bridge void *)window);
+ }
+-// The shell showed its own settings before Play: the game view starts the game at once
+-bool dm_show_launcher(void *view_controller, void (*done)(void)) { (void)view_controller; (void)done; return false; }
+
+ @interface App : UIResponder <UIApplicationDelegate>
+ @end
+@@ -145,11 +120,11 @@ - (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session op
+ self.window.rootViewController = [ShellLibrary makeController];
+ [self.window makeKeyAndVisible];
+ }
+-// front_ios.m ignores these until the game view exists
+-- (void)sceneWillResignActive:(UIScene *)s { front_ios_focus_event(0); }
+-- (void)sceneDidEnterBackground:(UIScene *)s { front_ios_focus_event(1); }
+-- (void)sceneWillEnterForeground:(UIScene *)s { front_ios_focus_event(2); }
+-- (void)sceneDidBecomeActive:(UIScene *)s { front_ios_focus_event(3); }
++// Forwarded to the running game framework's front_ios.m once a game has started
++- (void)sceneWillResignActive:(UIScene *)s { (void)s; if (g_focus) g_focus(0); }
++- (void)sceneDidEnterBackground:(UIScene *)s { (void)s; if (g_focus) g_focus(1); }
++- (void)sceneWillEnterForeground:(UIScene *)s { (void)s; if (g_focus) g_focus(2); }
++- (void)sceneDidBecomeActive:(UIScene *)s { (void)s; if (g_focus) g_focus(3); }
+ @end
+
+ // The performance HUD (the per-game setting DM_METAL_HUD) needs MTL_HUD_ENABLED in the environment before Metal starts in this
+diff --git a/dm/ios/framework/ShellGlue.m b/dm/ios/framework/ShellGlue.m
+new file mode 100644
+index 0000000..810c4ad
+--- /dev/null
++++ b/dm/ios/framework/ShellGlue.m
+@@ -0,0 +1,77 @@
++// Route C shell (LNPANDY/NX2Apple#451): compiled into each game's DmGame<title ID>.framework (project-framework.yml DmShellGame)
++// alongside dm/host, front_ios.m and Gen/embed.S. ShellMain.m sets the environment, dlopens the chosen game's framework and calls
++// dm_glue_start_game and dm_glue_present_game through dlsym.
++// This file also provides the symbols front_ios.m takes from main.m and Launcher.swift in the one-game app, so the framework
++// compiles front_ios.m, DmGamepad.m and GameMenu.swift unchanged.
++#import <UIKit/UIKit.h>
++#include <pthread.h>
++#include <signal.h>
++#include <stdio.h>
++#include <stdlib.h>
++#include <string.h>
++#include <sys/stat.h>
++#include "front.h"
++#include "../Shell/ShellGlue.h"
++
++int dm_main(int argc, char **argv); // dm/host/main.c compiled in with -Dmain=dm_main
++UIViewController *front_ios_root(void);
++void front_ios_focus_event(int ev);
++
++__attribute__((used, visibility("default"))) const int dm_glue_version = DM_GLUE_VERSION;
++
++static char **g_argv; static int g_argc; static int g_boot_ok;
++
++__attribute__((used, visibility("default")))
++const char *dm_glue_start_game(const char *const *argv, int argc, const void *game_image) {
++ if (argc < 2 || !game_image) return "The game's start arguments are incomplete.";
++ front_hud_env(); // before the early loading below can make a device (main.m's order)
++ dm_set_game_image_header(game_image);
++ g_argc = argc; g_argv = calloc((size_t)argc + 1, sizeof(char *));
++ for (int i = 0; i < argc; i++) g_argv[i] = strdup(argv[i]);
++ dm_host_preload_start(g_argc, g_argv); // module tables, relocation and take-over in the background while the game view comes up
++ g_boot_ok = 1;
++ return NULL;
++}
++
++__attribute__((used, visibility("default")))
++void dm_glue_present_game(void *win) {
++ UIWindow *window = (__bridge UIWindow *)win;
++ if (!window) { fprintf(stderr, "[RED] shell: no window for the game view\n"); return; }
++ UIViewController *game = front_ios_root(); // DmRootVC: landscape, its viewDidAppear starts the game (no settings screen: dm_show_launcher)
++ window.rootViewController = game;
++ [game setNeedsUpdateOfSupportedInterfaceOrientations];
++ [window.windowScene requestGeometryUpdateWithPreferences:[[UIWindowSceneGeometryPreferencesIOS alloc] initWithInterfaceOrientations:UIInterfaceOrientationMaskLandscape]
++ errorHandler:^(NSError *e) { fprintf(stderr, "shell: landscape request: %s\n", e.localizedDescription.UTF8String); }];
++}
++
++__attribute__((used, visibility("default")))
++void dm_glue_focus_event(int ev) {
++ front_ios_focus_event(ev);
++}
++
++// ---- what front_ios.m takes from main.m and Launcher.swift ----
++static void *boot_thread(void *p) {
++ (void)p;
++ static char alt[65536]; stack_t ss = {.ss_sp = alt, .ss_size = sizeof alt}; sigaltstack(&ss, 0); // crash printing must work on the host thread too
++ int rc = dm_main(g_argc, g_argv);
++ fprintf(stderr, "boot: dm_main returned %d\n", rc);
++ return NULL;
++}
++void front_ios_boot(void) { // front_ios.m, once the game view exists
++ static int once; if (once++ || !g_boot_ok) return;
++ void front_ios_audio_session(void); front_ios_audio_session();
++ pthread_attr_t a; pthread_attr_init(&a); pthread_attr_setstacksize(&a, 64u << 20);
++ pthread_t t; pthread_create(&t, &a, boot_thread, NULL); pthread_detach(t);
++}
++int front_ios_boot_ok(void) { return g_boot_ok; }
++const char *front_ios_boot_message(void) { return NULL; }
++const char *front_ios_device_check(void) { return NULL; } // main.m checks the GPU for the games (no BC textures, seedds#704) when Play is pressed, the shell does its own device handling: NULL = supported
++// The shell found the data before Play (DataLocator, EngineLaunchPlan): DM_ROMFS is set and the game view only checks it is still there
++int dm_locate_game_data(void) {
++ const char *r = getenv("DM_ROMFS"); struct stat st;
++ if (r && !stat(r, &st)) return 1;
++ fprintf(stderr, "[RED] shell: the game data at %s is gone\n", r ?: "(not set)");
++ return 0;
++}
++// The shell showed its own settings before Play: the game view starts the game at once
++bool dm_show_launcher(void *view_controller, void (*done)(void)) { (void)view_controller; (void)done; return false; }
+diff --git a/dm/ios/project-framework.yml b/dm/ios/project-framework.yml
+index d5d00b3..89a2df5 100644
+--- a/dm/ios/project-framework.yml
++++ b/dm/ios/project-framework.yml
+@@ -131,6 +131,62 @@ targets:
+ # No SYMROOT/OBJROOT/CONFIGURATION_BUILD_DIR of its own: the framework builds where the app does (xcodebuild's
+ # SYMROOT in build_ipa.sh, the pinned DerivedData of a prepared workspace in Xcode), and the app's embed phase copies
+ # it from there. The app target keeps project.yml's paths, which reference the generated DM_XCODE_OUTPUT_ROOT.
++ DmShellGame:
++ type: framework
++ platform: iOS
++ # Route C shell (LNPANDY/NX2Apple#451): each game's DmGame<title ID>.framework links its own dm/host, front_ios.m and
++ # embedded modules (Gen/dm.xcconfig: gen_build.py's header paths, defines and frameworks + gen_embed.py's segment flags),
++ # so an engine update never invalidates the games already in the shell.
++ configFiles:
++ Release: Gen/dm.xcconfig
++ Debug: Gen/dm.xcconfig
++ sources:
++ - path: Gen/embed.S
++ - path: Gen/src
++ - path: Gen/main/main.c
++ compilerFlags: "-Dmain=dm_main"
++ - path: framework/DmGameMarker.m
++ - path: framework/ShellGlue.m
++ - path: Sources/front_ios.m
++ - path: Sources/DmGamepad.m
++ - path: Sources/GameMenu.swift
++ - path: Sources/LauncherSettings.swift
++ - path: Sources/CloudSaves.m
++ - path: Sources/SaveSync.m
++ - path: Sources/DataBookmark.m
++ - path: Gen/framework/dm
++ type: folder
++ buildPhase: resources
++ - path: Gen/framework/profile.tsv
++ buildPhase: resources
++ - path: Gen/framework/game.manifest.json
++ buildPhase: resources
++ info:
++ path: Gen/framework/ShellGame-Info.plist
++ properties:
++ CFBundleDisplayName: ${DM_DISPLAY_NAME}
++ CFBundleVersion: $(CURRENT_PROJECT_VERSION)
++ CFBundleShortVersionString: $(MARKETING_VERSION)
++ settings:
++ PRODUCT_BUNDLE_IDENTIFIER: ${DM_BUNDLE_ID}.DmGame
++ PRODUCT_NAME: DmGame
++ MARKETING_VERSION: ${DM_APP_VERSION}
++ CURRENT_PROJECT_VERSION: ${DM_APP_VERSION}
++ DEVELOPMENT_TEAM: ${DM_TEAM_ID}
++ CODE_SIGN_STYLE: Automatic
++ CODE_SIGN_ENTITLEMENTS: ""
++ SKIP_INSTALL: YES
++ DYLIB_INSTALL_NAME_BASE: "@rpath"
++ DEFINES_MODULE: NO
++ ENABLE_BITCODE: NO
++ GCC_C_LANGUAGE_STANDARD: gnu11
++ SWIFT_VERSION: "5.0"
++ OTHER_SWIFT_FLAGS: $(inherited) -import-objc-header $(SRCROOT)/Sources/DmGameMenu.h
++ OTHER_CFLAGS: $(inherited) -mcpu=apple-a18
++ OTHER_LDFLAGS: $(inherited) -framework UIKit -framework UserNotifications
++ CLANG_ENABLE_OBJC_ARC: YES
++ DEBUG_INFORMATION_FORMAT: dwarf
++ GCC_WARN_INHIBIT_ALL_WARNINGS: YES
+ schemes:
+ ${DM_SCHEME_NAME}:
+ build:
+diff --git a/dm/ios/project-shell.yml b/dm/ios/project-shell.yml
+index 92a36e8..60fda10 100644
+--- a/dm/ios/project-shell.yml
++++ b/dm/ios/project-shell.yml
+@@ -23,21 +23,11 @@ targets:
+ platform: iOS
+ sources:
+ - path: Shell # the shell's main, its scene, the library and the real GameLauncher (dm/ios/Shell)
+- - path: Sources/front_ios.m # the game view, unchanged from the one-game app; ShellMain.m provides what it takes from main.m
+- - path: Sources/DmGamepad.m
+- - path: Sources/GameMenu.swift # the in-game menu the gamepad's gear opens: in the shell the layouts and Quit (no settings screen model)
+- - path: Sources/LauncherSettings.swift # GameMenu.swift's model type
+- - path: Sources/CloudSaves.m
+- - path: Sources/SaveSync.m
+- - path: Sources/DataBookmark.m
+- - path: Gen/dm # the host's shared files (dm/font for DM_FONT_DIR); every game's tables are in its framework
++ - path: Gen/dm # the host's shared files (dm/font for DM_FONT_DIR); every game's host and tables live in its framework
+ type: folder
+ buildPhase: resources
+ - path: Gen/Assets.xcassets
+ - path: ${DM_SHELL_PACKAGE}/AppIcon.icon # the app icon, an Icon Composer document, shared with the demo app
+- - path: Gen/src
+- - path: Gen/main/main.c
+- compilerFlags: "-Dmain=dm_main"
+ dependencies:
+ - package: ShellUI
+ product: ShellUI
+diff --git a/dm/ios/tests/test_framework_link.py b/dm/ios/tests/test_framework_link.py
+index ccbba80..5c6d3d0 100644
+--- a/dm/ios/tests/test_framework_link.py
++++ b/dm/ios/tests/test_framework_link.py
+@@ -120,6 +120,72 @@ class FrameworkLinkTests(unittest.TestCase):
+ self.assertIn(pair, got, f'{pair[0]},{pair[1]} is not a section of the framework')
+ self.assertIn('@rpath/DmGame.framework/DmGame', run('otool', '-D', binary).stdout)
+
++ def test_the_shell_framework_carries_its_own_host_and_the_module_sections(self):
++ root = Path(tempfile.mkdtemp()).resolve()
++ self.addCleanup(shutil.rmtree, root)
++ project, gen = root / 'project', root / 'project/Gen'
++ (gen / 'dm').mkdir(parents=True)
++ (gen / 'Assets.xcassets').mkdir()
++ (gen / 'Assets.xcassets/Contents.json').write_text(json.dumps({'info': {'author': 'xcode', 'version': 1}}))
++ for name in ('Sources', 'tools', 'framework', 'Shell'):
++ (project / name).symlink_to(REPO / 'dm/ios' / name, target_is_directory=True)
++ shutil.copyfile(REPO / 'dm/ios/project-framework.yml', project / 'project.yml')
++
++ patched = root / 'patched'
++ patched.mkdir()
++ for name in ('main', 'nrotest'):
++ (patched / f'{name}.patched.bin').write_bytes(bytes(0x10000))
++ (patched / f'{name}.fixups.tsv').write_text('# TEXT_END 0x4000\n# PATCH_OFF 0xc000\n# KEY_PAGE_OFF 0x8000\n# KEY_PAGE_SIZE 0x4000\n')
++ (patched / 'nro.tsv').write_text('nrotest\tfixture.nro\n')
++ flags = run(sys.executable, REPO / 'dm/ios/tools/gen_embed.py', patched, gen / 'embed.S', 'main', 'nrotest')
++ self.assertEqual(flags.returncode, 0, fail_tail(flags))
++
++ env = dict(os.environ, GAME=GAME, DM_GAME=GAME, DM_BUNDLE_ID='org.nxnative.fixture', DM_DISPLAY_NAME='Fixture Game',
++ DM_APP_VERSION='1.0', DM_APP_CATEGORY='action', DM_TEAM_ID='', DM_SCHEME_NAME='DmIOS', DM_APPICON='',
++ DM_SHOW_FPS='NO', DM_LANG='en-US')
++ build_cfg = run(sys.executable, REPO / 'dm/ios/tools/gen_build.py', REPO / 'dm/host', gen, env=env)
++ self.assertEqual(build_cfg.returncode, 0, fail_tail(build_cfg))
++ (gen / 'dm.xcconfig').write_text(build_cfg.stdout + f'OTHER_LDFLAGS = $(inherited) $(DM_FRAMEWORKS) {flags.stdout.strip()}\n')
++ (gen / 'framework.xcconfig').write_text(f'OTHER_LDFLAGS = $(inherited) {flags.stdout.strip()}\n')
++ (gen / 'framework/dm').mkdir(parents=True)
++ for name in ('main.fixups.tsv', 'nrotest.fixups.tsv', 'nro.tsv'):
++ shutil.copyfile(patched / name, gen / 'dm' / name)
++ shutil.copyfile(patched / name, gen / 'framework/dm' / name)
++ (gen / 'dm/shader_map.tsv').write_text('key\tfixture\n')
++ (gen / 'framework/dm/shader_map.tsv').write_text('key\tfixture\n')
++ profile = run(sys.executable, REPO / 'dm/games/game.py', 'profile', GAME, gen / 'framework/profile.tsv')
++ self.assertEqual(profile.returncode, 0, fail_tail(profile))
++ chain = next(line.split('"')[1] for line in (REPO / 'dm/gfx/nvn/dmsh_chain.h').read_text().splitlines()
++ if line.startswith('#define DMSH_CHAIN "'))
++ fw_name = f'DmGame{GAME}'
++ manifest = run(sys.executable, REPO / 'dm/ios/tools/gen_manifest.py', gen / 'framework/game.manifest.json', '--game', GAME,
++ '--name', 'Fixture Game', '--display-version', '1.0', '--package-version', 'v0', '--modules', 'main',
++ '--nro-table', patched / 'nro.tsv', '--chain', 'b-' + chain, '--romfs-marker', 'marker',
++ '--framework-name', fw_name, '--loader', 'FH')
++ self.assertEqual(manifest.returncode, 0, fail_tail(manifest))
++
++ generated = run('xcodegen', 'generate', cwd=project, env=env)
++ self.assertEqual(generated.returncode, 0, fail_tail(generated))
++ derived = root / 'derived'
++ built = run('xcodebuild', '-project', project / 'DmIOS.xcodeproj', '-target', 'DmShellGame', '-configuration', 'Release',
++ '-sdk', 'iphoneos', f'PRODUCT_NAME={fw_name}', f'PRODUCT_BUNDLE_IDENTIFIER=org.nxnative.fixture.game',
++ f'SYMROOT={derived}/Build/Products', f'OBJROOT={derived}/Build/Intermediates.noindex',
++ 'CODE_SIGNING_ALLOWED=NO', 'CODE_SIGNING_REQUIRED=NO', 'CODE_SIGN_IDENTITY=', 'build', cwd=project, env=env)
++ self.assertEqual(built.returncode, 0, fail_tail(built))
++ framework = derived / f'Build/Products/Release-iphoneos/{fw_name}.framework'
++ binary = framework / fw_name
++ self.assertTrue(binary.is_file(), f'no {binary}')
++ self.assertEqual(json.loads((framework / 'game.manifest.json').read_text())['loader'], 'FH')
++ got = sections(binary)
++ for pair in [('__TEXT', '__dmmainx0'), ('__DMmainW', '__img'), ('__TEXT', '__dmmainx1'),
++ ('__DATA', '__dm_nro_tab'), ('__DATA', 'swhle'), ('__DATA', 'swforce'), ('__DATA', 'swnvn')]:
++ self.assertIn(pair, got, f'{pair[0]},{pair[1]} is not a section of the shell framework')
++ exported = run('nm', '-gU', binary).stdout
++ for sym in ('_dmgame_image_marker', '_dm_glue_version', '_dm_glue_start_game', '_dm_glue_present_game', '_dm_glue_focus_event', '_dm_game_menu'):
++ self.assertIn(sym, exported, f'{sym} is not exported by the shell framework')
++ undef = run('nm', '-u', binary).stdout
++ self.assertNotIn('__mh_execute_header', undef, 'the framework must read its own image header (__dso_handle), not the executable\'s')
++
+
+ if __name__ == '__main__':
+ unittest.main()
+diff --git a/dm/ios/tests/test_shell_build.py b/dm/ios/tests/test_shell_build.py
+index a2d527c..2f5b1ad 100644
+--- a/dm/ios/tests/test_shell_build.py
++++ b/dm/ios/tests/test_shell_build.py
+@@ -35,14 +35,14 @@ def font_python():
+ return None
+
+
+-def framework(root, title=GAME, chain=CHAIN, name=None, executable=True, compile_it=False):
++def framework(root, title=GAME, chain=CHAIN, loader='FH', name=None, executable=True, compile_it=False):
+ """A framework folder as build_ipa.sh DM_FRAMEWORK_ONLY writes it, with a manifest and, optionally, a real arm64 dylib."""
+ name = name or f'DmGame{title}'
+ fw = Path(root) / f'{name}.framework'
+ (fw / 'dm').mkdir(parents=True)
+ exe = f'DmGame{title}'
+ manifest = {'schema': 1, 'title_id': title, 'name': f'Fixture {title}', 'display_version': '1.0', 'package_version': 'v0',
+- 'modules': ['main'], 'nro_count': 0, 'chain': chain, 'loader': 'FR', 'framework': f'DmGame{title}.framework',
++ 'modules': ['main'], 'nro_count': 0, 'chain': chain, 'loader': loader, 'framework': f'DmGame{title}.framework',
+ 'framework_executable': exe, 'image_marker': 'dmgame_image_marker', 'profile': 'profile.tsv',
+ 'shader_map': 'dm/shader_map.tsv', 'launcher': 'dm/launcher.json', 'romfs_marker': 'fixture.marker',
+ 'romfs_identity': '', 'min_os': '26.0'}
+@@ -82,20 +82,21 @@ class FrameworkChecks(unittest.TestCase):
+ self.assertIn(text, r.stdout + r.stderr)
+ self.assertFalse((self.shell / 'Gen').exists(), 'nothing is generated for a refused set')
+
+- def test_another_chain_is_refused(self):
+- self.refused([framework(self.root, chain='b-000000000000')], 'built for shader chain b-000000000000')
++ def test_a_framework_without_its_host_is_refused(self):
++ self.refused([framework(self.root, loader='FR')], 'built without a host in the framework')
+
+ def test_two_frameworks_of_one_title_are_refused(self):
+ a = framework(self.root / 'a')
+ b = framework(self.root / 'b')
+ self.refused([a, b], f'title ID {GAME} is already in the shell')
+
+- def test_two_games_go_into_one_shell(self):
+- # Checked only up to the frameworks list here (the generation needs XcodeGen): both games, the first one's profile compiled in
+- r = run_script('--prepare-xcode', [framework(self.root / 'a'), framework(self.root / 'b', title=OTHER)], self.shell, PATH='/usr/bin:/bin')
++ def test_two_games_of_different_chains_go_into_one_shell(self):
++ # Checked only up to the frameworks list here (the generation needs XcodeGen): each framework carries its own host,
++ # so two games built on different shader chains go into one shell together
++ r = run_script('--prepare-xcode', [framework(self.root / 'a', chain='b-000000000000'), framework(self.root / 'b', title=OTHER, chain=CHAIN)],
++ self.shell, PATH='/usr/bin:/bin')
+ rows = (self.shell / 'frameworks.txt').read_text().splitlines()
+ self.assertEqual([row.split('\t')[0] for row in rows], [GAME, OTHER], r.stdout)
+- self.assertIn(f'compiled defaults of {GAME}', r.stdout)
+
+ def test_a_folder_the_manifest_does_not_name_is_refused(self):
+ self.refused([framework(self.root, name='Renamed')], f'the manifest names DmGame{GAME}.framework')
+@@ -113,15 +114,17 @@ class FrameworkChecks(unittest.TestCase):
+
+
+ class ShellMainProvidesWhatFrontIosTakes(unittest.TestCase):
+- """front_ios.m is compiled into the shell unchanged and main.m is not linked, so ShellMain.m has to define every function
+- front_ios.m declares as coming from main.m (a missing one is a link error of every shell build, found only on a device build)."""
+- def test_every_symbol_front_ios_takes_from_main_m_is_defined(self):
++ """front_ios.m is compiled into each game's framework unchanged and main.m is not linked, so ShellGlue.m has to
++ define every function front_ios.m declares as coming from main.m and the glue symbols ShellMain.m looks up with dlsym."""
++ def test_every_symbol_front_ios_and_shell_main_take_is_defined(self):
+ front = (REPO / 'dm/ios/Sources/front_ios.m').read_text()
+ wanted = re.findall(r'^[A-Za-z_][\w \t\*]*?\b(\w+)\([^)]*\);[ \t]*//[^\n]*\bmain\.m\b', front, re.M)
+ self.assertIn('front_ios_boot_message', wanted) # the scan finds the declarations at all
+- shell = (REPO / 'dm/ios/Shell/ShellMain.m').read_text()
+- missing = [n for n in dict.fromkeys(wanted) if not re.search(r'^[A-Za-z_][\w \t\*]*?\b' + n + r'\([^)]*\)[ \t]*\{', shell, re.M)]
+- self.assertEqual(missing, [], 'ShellMain.m does not define what front_ios.m takes from main.m')
++ glue = (REPO / 'dm/ios/framework/ShellGlue.m').read_text()
++ wanted_all = [*dict.fromkeys(wanted), 'dm_glue_start_game', 'dm_glue_present_game', 'dm_glue_focus_event']
++ missing = [n for n in wanted_all if not re.search(r'^[A-Za-z_][\w \t\*]*?\b' + n + r'\([^)]*\)[ \t]*\{', glue, re.M)]
++ self.assertEqual(missing, [], 'ShellGlue.m does not define what front_ios.m and ShellMain.m take')
++ self.assertIn('dm_glue_version =', glue)
+
+
+ @unittest.skipUnless(HAS_TOOLS and font_python(), 'needs macOS, XcodeGen, an iPhoneOS SDK and a python with fontTools')
+diff --git a/dm/ios/tools/build_ipa.sh b/dm/ios/tools/build_ipa.sh
+index 97d22d1..3f81541 100755
+--- a/dm/ios/tools/build_ipa.sh
++++ b/dm/ios/tools/build_ipa.sh
+@@ -209,9 +209,10 @@ if [ "$FRAMEWORK" = 1 ]; then
+ mkdir -p "$O" && ROMFS_ID=$(python3 -I "$DM/tools/romfs_image.py" --identity "$ROMFS" "$GAME" "$DM_APP_VERSION" "${PKG:-}") || die "identity of $ROMFS"
+ fi
+ NRO_TABLE=$PATCHED/nro.tsv; [ -f "$NRO_TABLE" ] || NRO_TABLE= # the NRO modules gen_embed.py packs: nro_count in the manifest
++ FW_LOADER=FR; [ -z "$FRAMEWORK_ONLY" ] || FW_LOADER=FH
+ python3 tools/gen_manifest.py Gen/framework/game.manifest.json --game "$GAME" --name "$DM_DISPLAY_NAME" \
+ --display-version "$DM_APP_VERSION" --package-version "${PKG:-}" --modules "$MODS" ${NRO_TABLE:+--nro-table "$NRO_TABLE"} \
+- --chain "b-$V" --romfs-marker "$MARKER" --romfs-identity "$ROMFS_ID" --framework-name "$FW_NAME" > /dev/null || die "game manifest (gen_manifest.py)"
++ --chain "b-$V" --romfs-marker "$MARKER" --romfs-identity "$ROMFS_ID" --framework-name "$FW_NAME" --loader "$FW_LOADER" > /dev/null || die "game manifest (gen_manifest.py)"
+ printf 'OTHER_LDFLAGS = $(inherited) %s\n' "$F" > Gen/framework.xcconfig || die "framework link flags"
+ t "framework: Gen/framework (modules $MODS, profile.tsv, game.manifest.json)"
+ fi
+@@ -252,9 +253,9 @@ fi
+ # game's per-game resources into it, so one folder is one game: the shader libraries (msl/<MSLDIR>, the shell's DM_MSL_DIR), the pipeline
+ # archive (pso/, DM_PSO_BUNDLE) and the icon the shell's library shows. The game files and add-on content stay out (data, Documents/games/<id>/)
+ if [ -n "$FRAMEWORK_ONLY" ]; then
+- t "xcodebuild (Release, unsigned, the game framework $FW_NAME only)"
++ t "xcodebuild (Release, unsigned, the game framework $FW_NAME with its own host)"
+ mkdir -p "$O" "$FRAMEWORK_ONLY" || die "mkdir $FRAMEWORK_ONLY"
+- xcodebuild -project DmIOS.xcodeproj -target DmGame -configuration Release -sdk iphoneos \
++ xcodebuild -project DmIOS.xcodeproj -target DmShellGame -configuration Release -sdk iphoneos \
+ CODE_SIGNING_ALLOWED=NO CODE_SIGNING_REQUIRED=NO CODE_SIGN_IDENTITY= PRODUCT_NAME="$FW_NAME" PRODUCT_BUNDLE_IDENTIFIER="$DM_BUNDLE_ID.game" \
+ DM_XCODE_OUTPUT_ROOT="$DD" SYMROOT="$DD/Build/Products" OBJROOT="$DD/Build/Intermediates.noindex" build > "$O/build-framework.log" 2>&1 \
+ || { grep -E 'error:' "$O/build-framework.log" | head -20; die "xcodebuild, log $O/build-framework.log"; }
+diff --git a/dm/ios/tools/build_shell.sh b/dm/ios/tools/build_shell.sh
+index d3cc308..8c9c2df 100755
+--- a/dm/ios/tools/build_shell.sh
++++ b/dm/ios/tools/build_shell.sh
+@@ -29,18 +29,19 @@ MODE=${1:-}; case "$MODE" in --prepare-xcode|--build) ;; *) die "usage: $0 --pre
+ [ -n "${DM_SHELL_FRAMEWORKS:-}" ] || die "DM_SHELL_FRAMEWORKS is not set: the games' framework folders, one per line"
+ mkdir -p "$SHELL_DIR" || die "mkdir $SHELL_DIR"; S=$(cd "$SHELL_DIR" && pwd)
+ [ "$S" != "$IOS_SOURCE" ] || die "the shell project must be outside dm/ios"
+-export DM_SHELL_PACKAGE=${DM_SHELL_PACKAGE:-$REPO/frontend-ios}
++[ -n "${DM_SHELL_PACKAGE:-}" ] || { [ -f "$REPO/frontend-ios/Package.swift" ] && DM_SHELL_PACKAGE=$REPO/frontend-ios || DM_SHELL_PACKAGE=$(cd "$REPO/.." && pwd)/frontend-ios; }
++export DM_SHELL_PACKAGE
+ [ -f "$DM_SHELL_PACKAGE/Package.swift" ] || die "no Swift package at $DM_SHELL_PACKAGE (DM_SHELL_PACKAGE)"
+ export LC_ALL=C DM_BUNDLE_ID=${DM_BUNDLE_ID:-org.nxnative.shell} DM_TEAM_ID=${DM_TEAM_ID:-0000000000} DM_SHELL_NAME=${DM_SHELL_NAME:-NX2Apple} DM_APP_VERSION=${DM_APP_VERSION:-1.0}
+ export DM_FORK_PATCHES=$(paste -sd, "$DM/fork_patches.txt" 2>/dev/null || true)
+ DD=${DM_XCODE_DERIVED_DATA:-$S/dd}; mkdir -p "$DD" && DD=$(cd "$DD" && pwd)
+ V=$(sed -n 's/^#define DMSH_CHAIN "\(.*\)"/\1/p' "$DM/gfx/nvn/dmsh_chain.h"); [ -n "$V" ] || die "no DMSH_CHAIN in dm/gfx/nvn/dmsh_chain.h"
+
+-# Every framework: a manifest of this chain, its executable, a title ID of its own. The first one's profile is the host's
++# Every framework: a manifest with its own host (loader FH), its executable, a title ID of its own
+ FWLIST=$S/frameworks.txt
+-python3 -I - "$V" "$FWLIST" <<'PY' || die "the frameworks in DM_SHELL_FRAMEWORKS (above)"
++python3 -I - "$FWLIST" <<'PY' || die "the frameworks in DM_SHELL_FRAMEWORKS (above)"
+ import json, os, sys
+-chain, out = 'b-' + sys.argv[1], sys.argv[2]
++out = sys.argv[1]
+ paths = [p.strip() for p in os.environ['DM_SHELL_FRAMEWORKS'].splitlines() if p.strip()]
+ if not paths: sys.exit('[RED] no framework named')
+ seen, rows = {}, []
+@@ -51,21 +52,20 @@ for p in paths:
+ name, exe, tid = m.get('framework'), m.get('framework_executable'), m.get('title_id', '')
+ if os.path.basename(p) != name: sys.exit(f'[RED] {p}: the manifest names {name}')
+ if not os.path.isfile(os.path.join(p, exe or '-')): sys.exit(f'[RED] {p}: no executable {exe} (build_ipa.sh DM_FRAMEWORK_ONLY builds it)')
+- if m.get('chain') != chain: sys.exit(f'[RED] {p}: built for shader chain {m.get("chain")}, this checkout is {chain}: build the game again')
++ if m.get('loader') != 'FH': sys.exit(f'[RED] {p}: built without a host in the framework (loader {m.get("loader")!r}). Rebuild this game for the shared app.')
+ if tid in seen: sys.exit(f'[RED] {p}: title ID {tid} is already in the shell ({seen[tid]})')
+ seen[tid] = p; rows.append((tid, p, m.get('name', '')))
+ with open(out, 'w', encoding='utf-8') as f:
+ for tid, p, name in rows: f.write(f'{tid}\t{p}\t{name}\n')
+ PY
+ export GAME=$(head -1 "$FWLIST" | cut -f1)
+-t "shell: $DM_SHELL_NAME ($DM_BUNDLE_ID), compiled defaults of $GAME, games: $(cut -f3 "$FWLIST" | paste -sd, -)"
++t "shell: $DM_SHELL_NAME ($DM_BUNDLE_ID), games: $(cut -f3 "$FWLIST" | paste -sd, -)"
+
+-t "generate Gen/ (host sources, shared files, the project)"
++t "generate Gen/ (shared files, the project)"
+ for item in Sources Shell tools; do ln -sfn "$IOS_SOURCE/$item" "$S/$item" || die "link $item"; done
+ cd "$S" || die "cd $S"
+ rm -rf Gen && mkdir -p Gen/dm/font || die "mkdir Gen"
+-python3 "$IOS_SOURCE/tools/gen_build.py" "$DM/host" Gen > Gen/dm.xcconfig || die "gen_build"
+-echo 'OTHER_LDFLAGS = $(inherited) $(DM_FRAMEWORKS)' >> Gen/dm.xcconfig
++: > Gen/dm.xcconfig || die "dm.xcconfig"
+ cp "${STD_FONT:-/System/Library/Fonts/Supplemental/Arial Unicode.ttf}" Gen/dm/font/standard.ttf || die "copy standard font (STD_FONT=a TTF)"
+ "${FONT_PY:-python3}" "$DM/tools/make_ext_font.py" Gen/dm/font/nintendo_ext.ttf > /dev/null || die "make_ext_font.py (pip install fonttools, or FONT_PY=python with fontTools)"
+ mkdir -p Gen/Assets.xcassets && printf '{"info":{"author":"xcode","version":1}}\n' > Gen/Assets.xcassets/Contents.json || die "asset catalog"
+diff --git a/dm/ios/tools/gen_manifest.py b/dm/ios/tools/gen_manifest.py
+index e1d302f..058b02d 100644
+--- a/dm/ios/tools/gen_manifest.py
++++ b/dm/ios/tools/gen_manifest.py
+@@ -63,7 +63,7 @@ def manifest(args):
+ 'modules': modules,
+ 'nro_count': nro_count(args.nro_table),
+ 'chain': args.chain,
+- 'loader': 'FR', # a pure module container: the shell is the host (design §1.1 FR)
++ 'loader': args.loader,
+ 'framework': args.framework_name + '.framework',
+ 'framework_executable': args.framework_name,
+ 'image_marker': IMAGE_MARKER,
+@@ -95,6 +95,8 @@ def main(argv=None):
+ ap.add_argument('--framework-name', default=FRAMEWORK_EXECUTABLE,
+ help='the framework\'s product name: DmGame in the one-game app (M1), DmGame<title ID> in the shell, where several '
+ 'games\' frameworks sit side by side in Frameworks/')
++ ap.add_argument('--loader', default='FR', choices=('FR', 'FH'),
++ help='FR: a module container whose host is the app (M1); FH: the framework carries its own host (the shell, #451)')
+ ap.add_argument('--built-by', help='who built it, for a log line (optional; a device or tool name)')
+ args = ap.parse_args(argv)
+ data = manifest(args)
diff --git a/patches/series b/patches/series
index 982c7032..8c7f9f60 100644
--- a/patches/series
+++ b/patches/series
@@ -42,3 +42,5 @@
0072-nsp-script-the-first-dotnet-with-an-sdk-10-goes.patch
0073-nsp-script-hand-the-extraction-and-the-shader-sp.patch
0074-mac-split-a-joy-con-pair-into-two-sideways-contr.patch
+0075-host-read-embedded-sections-from-the-image-that.patch
+0076-ios-shell-link-the-host-into-each-game-s-framewo.patch