From a6489800853f52823e612532e962fbf1a93354c5 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:43 -0500 Subject: [PATCH 01/36] Moved the Linux targets into the host, for the runner --- Sources/{LinuxPackager => LinuxHost}/LinuxTarget.swift | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename Sources/{LinuxPackager => LinuxHost}/LinuxTarget.swift (100%) diff --git a/Sources/LinuxPackager/LinuxTarget.swift b/Sources/LinuxHost/LinuxTarget.swift similarity index 100% rename from Sources/LinuxPackager/LinuxTarget.swift rename to Sources/LinuxHost/LinuxTarget.swift From 856fe74fc56da9cae99dda4fd4911b61dba0dc75 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:43 -0500 Subject: [PATCH 02/36] Re-exported the host's targets and install locations from the packager --- Sources/LinuxPackager/Exports.swift | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 Sources/LinuxPackager/Exports.swift diff --git a/Sources/LinuxPackager/Exports.swift b/Sources/LinuxPackager/Exports.swift new file mode 100644 index 0000000..9d59c34 --- /dev/null +++ b/Sources/LinuxPackager/Exports.swift @@ -0,0 +1,2 @@ +// LinuxTarget and InstalledApps are the runner's and the packager's. +@_exported import LinuxHost From f3cdf205f8e17f4719f55a093130c46a11392fff Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:43 -0500 Subject: [PATCH 03/36] Loaded an app's libapp.so after checking it against its signature --- Sources/LinuxHost/AppLibrary.swift | 122 +++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 Sources/LinuxHost/AppLibrary.swift diff --git a/Sources/LinuxHost/AppLibrary.swift b/Sources/LinuxHost/AppLibrary.swift new file mode 100644 index 0000000..804f58c --- /dev/null +++ b/Sources/LinuxHost/AppLibrary.swift @@ -0,0 +1,122 @@ +import CRuntime +import Crypto +import Foundation +import RuntimeHost +import RuntimeNative + +/// An app's Linux slice, loaded: `lib//libapp.so` from its bundle +/// (AppRuntime's `DynamicRuntime.md` §7.5, §7.6), as the runner loads it +/// (`Plan.md` §4). +/// +/// The library names no other library. What it leaves undefined, the +/// runner's process supplies: `rt.h`, which `linux-app-host` exports; a few +/// libc functions; and GLES 2.0, which `preload` puts in the global scope +/// first for an app that draws. It binds every symbol as it loads, so one +/// the process lacks fails the load, by name. +/// +/// Before it's loaded, its contents are checked against the bundle's +/// `_CodeSignature/CodeResources`, and the bytes checked are the ones +/// loaded: the file is opened once, hashed, and loaded through its +/// descriptor. +public struct AppLibrary { + + /// The library's path in the bundle. + public let path: String + + public let entryPoints: AppEntryPoints + + /// Loads the slice for `target` from the bundle at `bundle`. + /// + /// `preload` are libraries to load into the global scope first, by + /// soname, for the symbols the app's library leaves undefined. + public static func load( + bundle: String, + target: LinuxTarget, + preload: [String] = [] + ) throws(AppLibraryError) -> AppLibrary { + let relative = target.sharedLibrary + let path = bundle + "/" + relative + let expected = try signedDigest(bundle: bundle, file: relative) + + let descriptor = open(path, O_RDONLY | O_CLOEXEC) + guard descriptor >= 0 else { + throw AppLibraryError("the app has no \(target.rawValue) slice: \(relative): \(String(cString: strerror(errno)))") + } + defer { close(descriptor) } + guard let contents = read(descriptor) else { + throw AppLibraryError("can't read \(relative): \(String(cString: strerror(errno)))") + } + guard Data(SHA256.hash(data: contents)) == expected else { + throw AppLibraryError("\(relative) doesn't match the bundle's CodeResources") + } + + for name in preload { + guard dlopen(name, RTLD_NOW | RTLD_GLOBAL) != nil else { + throw AppLibraryError("the app needs \(name): \(lastError())") + } + } + + // The descriptor's file is the one hashed, whatever happens to the + // path meanwhile; the path when /proc isn't mounted. + let byDescriptor = "/proc/self/fd/\(descriptor)" + let loadPath = FileManager.default.fileExists(atPath: byDescriptor) ? byDescriptor : path + guard let handle = dlopen(loadPath, RTLD_NOW | RTLD_LOCAL) else { + throw AppLibraryError("can't load \(relative): \(lastError())") + } + // Never closed: the app runs as long as the process does. + func symbol(_ name: String) throws(AppLibraryError) -> UnsafeMutableRawPointer { + guard let address = dlsym(handle, name) else { + throw AppLibraryError("\(relative) doesn't export \(name)") + } + return address + } + typealias Main = @convention(c) () -> rt_status + let main = unsafeBitCast(try symbol("rt_main"), to: Main.self) + let dispatch = unsafeBitCast(try symbol("rt_dispatch"), to: NativeGuest.EntryPoints.Dispatch.self) + let finalize = unsafeBitCast(try symbol("rt_finalize"), to: NativeGuest.EntryPoints.Finalize.self) + return AppLibrary(path: path, entryPoints: AppEntryPoints(main: { main() }, dispatch: dispatch, finalize: finalize)) + } + + /// The SHA-256 that `_CodeSignature/CodeResources` lists for `file`. + public static func signedDigest(bundle: String, file: String) throws(AppLibraryError) -> Data { + let manifest = bundle + "/_CodeSignature/CodeResources" + guard let data = FileManager.default.contents(atPath: manifest) else { + throw AppLibraryError("the app isn't signed: it has no _CodeSignature/CodeResources") + } + guard let plist = (try? PropertyListSerialization.propertyList(from: data, format: nil)) as? [String: Any], + let files = plist["files"] as? [String: Data] else { + throw AppLibraryError("_CodeSignature/CodeResources is malformed") + } + guard let digest = files[file] else { + throw AppLibraryError("_CodeSignature/CodeResources doesn't list \(file)") + } + return digest + } + + private static func read(_ descriptor: Int32) -> Data? { + let file = FileHandle(fileDescriptor: descriptor, closeOnDealloc: false) + return (try? file.readToEnd()).map { $0 ?? Data() } + } + + private static func lastError() -> String { + dlerror().map { String(cString: $0) } ?? "unknown error" + } +} + +/// Why an app's library can't be loaded. +public struct AppLibraryError: Error, CustomStringConvertible { + + public var description: String + + init(_ description: String) { + self.description = description + } +} + +public extension LinuxTarget { + + /// The slice's library, as a path in the bundle. + var sharedLibrary: String { + "lib/\(rawValue)/libapp.so" + } +} From be7c979b2b99d412fbda78bcc45b69d810d6cda2 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:43 -0500 Subject: [PATCH 04/36] Found installed apps by their identifier --- Sources/LinuxHost/InstalledApps.swift | 66 +++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 Sources/LinuxHost/InstalledApps.swift diff --git a/Sources/LinuxHost/InstalledApps.swift b/Sources/LinuxHost/InstalledApps.swift new file mode 100644 index 0000000..f1ac99b --- /dev/null +++ b/Sources/LinuxHost/InstalledApps.swift @@ -0,0 +1,66 @@ +import Foundation + +/// Where `linux-app install` puts an app, and how the runner finds it by +/// its identifier (`Plan.md` §4, `Packager.md` §4): +/// `/lib/linux-app/.app`, the app's bundle thinned to +/// what this machine runs. +public enum InstalledApps { + + /// The apps' directory under a prefix. + public static let directory = "lib/linux-app" + + /// The installed bundle of `identifier` under `prefix`. + public static func bundle(identifier: String, prefix: String) -> String { + prefix + "/" + directory + "/" + identifier + ".app" + } + + /// The prefixes searched, in order: `LINUXAPPRUNTIME_PREFIXES` (a + /// colon-separated list) if it's set; otherwise the user's + /// (`~/.local`), the runner's own (`/bin/linux-app-host`), then + /// `/usr/local` and `/usr`. + public static func prefixes( + environment: [String: String] = ProcessInfo.processInfo.environment, + runner: String? = runnerPath() + ) -> [String] { + if let list = environment["LINUXAPPRUNTIME_PREFIXES"], !list.isEmpty { + return list.split(separator: ":").map(String.init) + } + var prefixes: [String] = [] + if let home = environment["HOME"], home.hasPrefix("/") { + prefixes.append(home + "/.local") + } + if let runner { + let bin = (runner as NSString).deletingLastPathComponent + if (bin as NSString).lastPathComponent == "bin" { + prefixes.append((bin as NSString).deletingLastPathComponent) + } + } + for prefix in ["/usr/local", "/usr"] where !prefixes.contains(prefix) { + prefixes.append(prefix) + } + return prefixes + } + + /// The first installed bundle of `identifier` in `prefixes`. + public static func find(identifier: String, prefixes: [String] = prefixes()) -> String? { + guard isIdentifier(identifier) else { return nil } + return prefixes.lazy + .map { bundle(identifier: identifier, prefix: $0) } + .first { FileManager.default.fileExists(atPath: $0 + "/Info.plist") } + } + + /// A bundle identifier, which names a directory: `org.example.App`. + public static func isIdentifier(_ value: String) -> Bool { + let parts = value.split(separator: ".", omittingEmptySubsequences: false) + return parts.count >= 2 && parts.allSatisfy { part in + !part.isEmpty && part.allSatisfy { $0.isASCII && ($0.isLetter || $0.isNumber || $0 == "-" || $0 == "_") } + } + } + + /// This process's executable, with links resolved. + public static func runnerPath() -> String? { + let path = (try? FileManager.default.destinationOfSymbolicLink(atPath: "/proc/self/exe")) + ?? CommandLine.arguments.first.map { URL(fileURLWithPath: $0).resolvingSymlinksInPath().path } + return path.flatMap { $0.hasPrefix("/") ? $0 : nil } + } +} From 45bd2f034342335712867bab2df91e4dd6fbfad1 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:43 -0500 Subject: [PATCH 05/36] Defined arc4random_buf for musl too --- Sources/CLinuxHost/arc4random.c | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/Sources/CLinuxHost/arc4random.c b/Sources/CLinuxHost/arc4random.c index 7a8e4f8..f6e4ee8 100644 --- a/Sources/CLinuxHost/arc4random.c +++ b/Sources/CLinuxHost/arc4random.c @@ -1,10 +1,14 @@ -// What app slices need from libc that older glibc lacks. Ubuntu 22.04's -// glibc 2.35, which PortMaster ports build against, has no arc4random_buf -// (2.36 added it); Embedded Swift's hashing calls it for its seed. +// arc4random_buf, which an app's libapp.so leaves undefined (Embedded +// Swift's hashing calls it for its seed), where libc lacks it: musl, and +// glibc before 2.36 (Ubuntu 22.04's 2.35, which PortMaster ports build +// against). The runner exports it (exports.list), and its executable is +// searched first, so this is the definition the app binds to rather than +// one some other library in the process happens to have (on Alpine, +// Mesa pulls in libbsd's). #include -#if defined(__GLIBC__) && !__GLIBC_PREREQ(2, 36) +#if !defined(__GLIBC__) || !__GLIBC_PREREQ(2, 36) #include #include From 7d637982a370db93e1a0533e3990d60a369fadb6 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:43 -0500 Subject: [PATCH 06/36] Declared naming the process after the app --- Sources/CLinuxHost/include/CLinuxHost.h | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/Sources/CLinuxHost/include/CLinuxHost.h b/Sources/CLinuxHost/include/CLinuxHost.h index 42f762a..c33cc82 100644 --- a/Sources/CLinuxHost/include/CLinuxHost.h +++ b/Sources/CLinuxHost/include/CLinuxHost.h @@ -1,2 +1,8 @@ -// libc functions app slices need that older glibc lacks (arc4random.c). +// What the runner's process supplies that libc may not, and what Swift +// can't call itself. #include + +/// Names the process for `ps` and `top` (`PR_SET_NAME`), which keep 15 +/// bytes of it: every app runs in the same runner, and is shown by its own +/// name. prctl is variadic, so Swift can't call it. +void clinuxhost_set_process_name(const char *name); From 59bba3dbc01187e2b3b573a89eaef5a2c03f61e3 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:43 -0500 Subject: [PATCH 07/36] Named the process after the app --- Sources/CLinuxHost/process.c | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 Sources/CLinuxHost/process.c diff --git a/Sources/CLinuxHost/process.c b/Sources/CLinuxHost/process.c new file mode 100644 index 0000000..71978d1 --- /dev/null +++ b/Sources/CLinuxHost/process.c @@ -0,0 +1,6 @@ +#include "CLinuxHost.h" +#include + +void clinuxhost_set_process_name(const char *name) { + prctl(PR_SET_NAME, (unsigned long)name, 0, 0, 0); +} From e5bc56cda9f96f4f49fd241af84c39089db01b8c Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:43 -0500 Subject: [PATCH 08/36] Listed what the runner exports for apps' libraries --- Sources/LinuxAppHost/exports.list | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 Sources/LinuxAppHost/exports.list diff --git a/Sources/LinuxAppHost/exports.list b/Sources/LinuxAppHost/exports.list new file mode 100644 index 0000000..049721b --- /dev/null +++ b/Sources/LinuxAppHost/exports.list @@ -0,0 +1,8 @@ +/* What linux-app-host exports for the app's libapp.so to bind to + * (Plan.md §4): rt.h's functions, which RuntimeNative defines, and + * arc4random_buf where CLinuxHost defines it. The linker keeps them, + * though nothing in the runner calls them. */ +{ + rt_*; + arc4random_buf; +}; From 2ef81e99a96c632088c53f69db7a74840b2057a6 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:43 -0500 Subject: [PATCH 09/36] Made linux-app-host the runner --- Sources/LinuxAppHost/main.swift | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/Sources/LinuxAppHost/main.swift b/Sources/LinuxAppHost/main.swift index cf23375..3989f9d 100644 --- a/Sources/LinuxAppHost/main.swift +++ b/Sources/LinuxAppHost/main.swift @@ -1,9 +1,4 @@ import LinuxHostApp -// The app's library, linked in when the package was built with -// LINUXAPPRUNTIME_APP_LIBRARY, defines these. -#if APP_LINKED -HostApp.main(AppEntryPoints(main: rt_main, dispatch: rt_dispatch, finalize: rt_finalize)) -#else -HostApp.main(nil) -#endif +// The runner: it loads the app's libapp.so from its bundle. +HostApp.main() From cd51fd026db73b2cded601d43044b557fb9e0ece Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:43 -0500 Subject: [PATCH 10/36] Named GLES's library for the runner to preload --- Sources/LinuxGraphics/LinuxGraphics.swift | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Sources/LinuxGraphics/LinuxGraphics.swift b/Sources/LinuxGraphics/LinuxGraphics.swift index 632ffd6..81e32b3 100644 --- a/Sources/LinuxGraphics/LinuxGraphics.swift +++ b/Sources/LinuxGraphics/LinuxGraphics.swift @@ -23,6 +23,10 @@ public enum LinuxGraphics: HostModule { [.graphics: isAvailable ? GrantedPermission() : UnavailablePermission()] } + /// GLES 2.0's library, by soname: an app that draws binds its `gl*` + /// calls to it. + public static let gles = "libGLESv2.so.2" + /// Whether `libEGL` and `libGLESv2` load. public static var isAvailable: Bool { GLLibrary.shared != nil From 205a63ff4af71dd6a6ca70d739374fa7a8a090c2 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:43 -0500 Subject: [PATCH 11/36] Said the runner loads GLES for an app that draws --- Sources/LinuxGraphics/GLLibrary.swift | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Sources/LinuxGraphics/GLLibrary.swift b/Sources/LinuxGraphics/GLLibrary.swift index 7a93111..a179577 100644 --- a/Sources/LinuxGraphics/GLLibrary.swift +++ b/Sources/LinuxGraphics/GLLibrary.swift @@ -7,9 +7,10 @@ import Darwin /// EGL, and the few GLES 2.0 functions the host calls itself, looked up at /// run time (`Plan.md` §7). /// -/// The host links no GL: an app that draws has `libGLESv2` linked in by the -/// packager, for its own `gl*` calls, and the host opens the same libraries -/// by name. Without them, `Surface` is unavailable and the rest of the host +/// The host links no GL. For an app that draws, the runner loads +/// `libGLESv2` into the global scope before the app's library, which binds +/// its own `gl*` calls to it, and the host opens the same libraries by +/// name. Without them, `Surface` is unavailable and the rest of the host /// works as before. struct GLLibrary { @@ -58,7 +59,7 @@ struct GLLibrary { private init?() { guard let egl = Self.open(["libEGL.so.1", "libEGL.so"]), - let gles = Self.open(["libGLESv2.so.2", "libGLESv2.so"]) else { + let gles = Self.open([LinuxGraphics.gles, "libGLESv2.so"]) else { return nil } func load(_ library: UnsafeMutableRawPointer, _ name: String, as type: T.Type = T.self) -> T? { From 6b7c95eb81e99552238f41bee016d86a7d764ca2 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:44 -0500 Subject: [PATCH 12/36] Loaded the app's library at launch, by bundle or identifier --- Sources/LinuxHostApp/HostApp.swift | 94 +++++++++++++++++++++++------- 1 file changed, 73 insertions(+), 21 deletions(-) diff --git a/Sources/LinuxHostApp/HostApp.swift b/Sources/LinuxHostApp/HostApp.swift index dd434de..16696aa 100644 --- a/Sources/LinuxHostApp/HostApp.swift +++ b/Sources/LinuxHostApp/HostApp.swift @@ -2,6 +2,7 @@ @_exported import LinuxHost import CLinuxHost import CacaoSDL +import DynamicGraphics import Foundation import LinuxBluetooth import LinuxCoreModel @@ -10,18 +11,20 @@ import LinuxWebKit import LinuxUI import RuntimeFormatting -/// The app's `main` (`Plan.md` §4): finds the app's bundle, checks and -/// prepares the app, calls `rt_main`, and runs Cacao's main loop with a -/// window showing the guest's renderer. +/// The runner (`Plan.md` §4): finds an app's bundle, checks the app +/// against this host, loads its `libapp.so`, calls `rt_main`, and runs +/// Cacao's main loop with a window showing the guest's renderer. No app is +/// linked in: every app runs in this one program. /// /// ``` -/// linux-app-host [--bundle App.app] [--open URL] +/// linux-app-host [--bundle] App.app | IDENTIFIER [[--open] URL] /// ``` /// -/// - `--bundle`: the universal bundle whose `Info.plist` describes the app -/// linked in; by default `App.app` next to the executable, or -/// `LINUXAPPRUNTIME_BUNDLE`. -/// - `--open`: a URL for the app to open once it started. +/// - The app: a bundle's path, or an installed app's identifier +/// (`InstalledApps`); by default `LINUXAPPRUNTIME_BUNDLE`, or `App.app` +/// next to the executable, as a PortMaster port has it. +/// - `--open`: a URL for the app to open once it started, as a desktop +/// entry's `%u` passes it. /// /// Cacao's `CACAO_SCREENSHOT=path.png` saves the first frame and quits. public enum HostApp { @@ -38,20 +41,35 @@ public enum HostApp { /// The window's title: the app's name. nonisolated(unsafe) static var title = "" - public static func main(_ entry: AppEntryPoints?) -> Never { + public static func main() -> Never { let arguments = Arguments(CommandLine.arguments) - guard let entry else { - fail("this host was built without an app; build it with LINUXAPPRUNTIME_APP_LIBRARY set to an app's libapp.a") - } - guard let bundle = arguments.bundle ?? defaultBundle() else { - fail("no app bundle: pass --bundle App.app") + let bundle: String + switch arguments.app { + case .bundle(let path)?: + bundle = path + case .identifier(let identifier)?: + guard let found = InstalledApps.find(identifier: identifier) else { + fail("\(identifier) isn't installed (searched \(InstalledApps.prefixes().map { $0 + "/" + InstalledApps.directory }.joined(separator: ", ")))") + } + bundle = found + case nil: + guard let found = defaultBundle() else { + fail("no app: pass a bundle's path or an installed app's identifier") + } + bundle = found } let info: AppInfo + let executable: String? do { - info = try AppInfo(contentsOf: bundle + "/Info.plist") + let data = try Data(contentsOf: URL(fileURLWithPath: bundle + "/Info.plist")) + info = try AppInfo(propertyList: data) + let dictionary = try? PropertyListSerialization.propertyList(from: data, format: nil) as? [String: Any] + executable = dictionary?["CFBundleExecutable"] as? String } catch { fail("\(bundle): \(error)") } + // Shown by `ps` and `top` as the app, not as the runner. + clinuxhost_set_process_name(executable ?? info.name) // Cacao's loop drains the main queue every turn; the host's own // loop runs its jobs and timers there. @@ -60,13 +78,26 @@ public enum HostApp { MainLoop.shared.runsOnMainQueue = true } + // The app's ABI and contracts, checked at every launch: this + // runner may have changed since the app was installed. let host = AppHost(info: info, modules: modules, bundlePath: bundle) do { try host.prepare() } catch { fail(error.description) } - let status = host.start(entry) + guard let target = LinuxTarget.native else { + fail("this machine isn't one of the Linux targets: \(LinuxTarget.allCases.map(\.rawValue).joined(separator: ", "))") + } + let library: AppLibrary + do { + library = try AppLibrary.load(bundle: bundle, target: target, preload: preload(for: info)) + } catch { + fail(error.description) + } + HostLog.debug("loaded \(library.path)") + + let status = host.start(library.entryPoints) guard status == .ok else { fail("the app didn't start: \(status)") } @@ -87,12 +118,19 @@ public enum HostApp { exit(0) } + /// The libraries an app's `libapp.so` binds to that the runner doesn't + /// link: GLES 2.0 for an app that draws (`Surface`), which the library + /// doesn't name itself. + static func preload(for info: AppInfo) -> [String] { + info.contractNames.contains(SurfaceProxy.descriptor.name) ? [LinuxGraphics.gles] : [] + } + static func fail(_ message: String) -> Never { HostLog.error(message) exit(1) } - /// `App.app` next to the executable, or `LINUXAPPRUNTIME_BUNDLE`. + /// `LINUXAPPRUNTIME_BUNDLE`, or `App.app` next to the executable. static func defaultBundle() -> String? { if let path = ProcessInfo.processInfo.environment["LINUXAPPRUNTIME_BUNDLE"] { return path @@ -103,16 +141,30 @@ public enum HostApp { } struct Arguments { - var bundle: String? + + enum App: Equatable { + case bundle(String) + case identifier(String) + } + + var app: App? var open: String? init(_ arguments: [String]) { var iterator = arguments.dropFirst().makeIterator() while let argument = iterator.next() { switch argument { - case "--bundle": bundle = iterator.next() - case "--open": open = iterator.next() - default: HostLog.warning("ignoring \(argument)") + case "--bundle": + app = iterator.next().map(App.bundle) + case "--open": + open = iterator.next() + case _ where app == nil && !argument.hasPrefix("-"): + // A path names a bundle; otherwise it's an identifier. + app = argument.contains("/") || argument.hasSuffix(".app") ? .bundle(argument) : .identifier(argument) + case _ where open == nil && !argument.hasPrefix("-"): + open = argument + default: + HostLog.warning("ignoring \(argument)") } } } From 4e6d5e90b78db14cbd137ecff890982ee5092ffe Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:44 -0500 Subject: [PATCH 13/36] Stopped building a host for each app --- Sources/LinuxPackager/HostPackage.swift | 209 ------------------------ 1 file changed, 209 deletions(-) delete mode 100644 Sources/LinuxPackager/HostPackage.swift diff --git a/Sources/LinuxPackager/HostPackage.swift b/Sources/LinuxPackager/HostPackage.swift deleted file mode 100644 index 2bb960c..0000000 --- a/Sources/LinuxPackager/HostPackage.swift +++ /dev/null @@ -1,209 +0,0 @@ -import Crypto -import Foundation - -/// The SwiftPM package that builds an app's host (`Packager.md` §3): an -/// executable named after the app, linking `LinuxHostApp` and the app's -/// `libapp.a`. Generated in the work directory and reused between builds. -public struct HostPackage { - - /// The package's directory. - public var directory: URL - - /// This repository's package, which the generated one depends on. - public var hostPackage: URL - - public var executable: String - - /// The executable product. Not the app's name, which may be a product of - /// a package in the graph already (AppRuntime's `ExampleUI` is); the - /// packager names the copy it installs. - public static let product = "LinuxAppMain" - - /// The app's `libapp.a`. - public var library: URL - - /// Whether the app calls GL (it declares `graphics`): its `gl*` calls - /// are `libGLESv2`'s, which the host then links. - public var linksGL: Bool - - public init(directory: URL, hostPackage: URL, executable: String, library: URL, linksGL: Bool = false) { - self.directory = directory - self.hostPackage = hostPackage - self.executable = executable - self.library = library - self.linksGL = linksGL - } - - /// Where this package's source is: `--host-package`, then - /// `LINUXAPPRUNTIME_PATH`, then the tree `linux-app` was built from. - public static func locate(_ explicit: String? = nil) throws(PackagerError) -> URL { - let candidates = [explicit, ProcessInfo.processInfo.environment["LINUXAPPRUNTIME_PATH"]].compactMap { $0 } - .map { URL(fileURLWithPath: $0) } - + [URL(fileURLWithPath: #filePath).deletingLastPathComponent().deletingLastPathComponent().deletingLastPathComponent()] - for candidate in candidates { - let manifest = candidate.appendingPathComponent("Package.swift") - if let text = try? String(contentsOf: manifest, encoding: .utf8), text.contains("name: \"LinuxAppRuntime\"") { - return candidate.standardizedFileURL - } - } - throw PackagerError("can't find LinuxAppRuntime's source; pass --host-package or set LINUXAPPRUNTIME_PATH") - } - - /// Copies the app's library into the package as `lib/libapp-.a`. - /// SwiftPM doesn't relink when a library in the linker flags changes, - /// but a new name changes the manifest, which it does notice. - public static func stage(_ library: URL, in directory: URL) throws(PackagerError) -> URL { - guard let data = FileManager.default.contents(atPath: library.path) else { - throw PackagerError("can't read \(library.path)") - } - let hash = SHA256.hash(data: data).prefix(8).map { String(format: "%02x", $0) }.joined() - let lib = directory.appendingPathComponent("lib") - let staged = lib.appendingPathComponent("libapp-\(hash).a") - do { - try FileManager.default.createDirectory(at: lib, withIntermediateDirectories: true) - for old in try FileManager.default.contentsOfDirectory(atPath: lib.path) where old != staged.lastPathComponent { - try FileManager.default.removeItem(at: lib.appendingPathComponent(old)) - } - if !FileManager.default.fileExists(atPath: staged.path) { - try data.write(to: staged) - } - } catch { - throw PackagerError("can't copy \(library.path) into \(lib.path): \(error)") - } - return staged - } - - var manifest: String { - """ - // swift-tools-version:6.4 - // Generated by linux-app: the host for \(executable), linked with its library. - import PackageDescription - - let package = Package( - name: \(literal(executable + "Host")), - products: [ - .executable(name: "\(Self.product)", targets: ["AppMain"]), - ], - dependencies: [ - .package(name: "LinuxAppRuntime", path: \(literal(hostPackage.path))), - ], - targets: [ - .executableTarget( - name: "AppMain", - dependencies: [.product(name: "LinuxHostApp", package: "LinuxAppRuntime")], - swiftSettings: [.swiftLanguageMode(.v5)], - linkerSettings: [.unsafeFlags([\(([library.path] + (linksGL ? ["-lGLESv2"] : [])).map(literal).joined(separator: ", "))])] - ), - ] - ) - - """ - } - - static let main = """ - // Generated by linux-app. The app's library defines these. - import LinuxHostApp - - HostApp.main(AppEntryPoints(main: rt_main, dispatch: rt_dispatch, finalize: rt_finalize)) - - """ - - /// Writes the package, leaving files that haven't changed alone so - /// builds stay incremental. - public func write() throws(PackagerError) { - let sources = directory.appendingPathComponent("Sources/AppMain") - try write(manifest, to: directory.appendingPathComponent("Package.swift")) - try write(Self.main, to: sources.appendingPathComponent("main.swift")) - let version = hostPackage.appendingPathComponent(".swift-version") - if let pinned = try? String(contentsOf: version, encoding: .utf8) { - try write(pinned, to: directory.appendingPathComponent(".swift-version")) - } - } - - private func write(_ text: String, to url: URL) throws(PackagerError) { - if (try? String(contentsOf: url, encoding: .utf8)) == text { - return - } - do { - try FileManager.default.createDirectory(at: url.deletingLastPathComponent(), withIntermediateDirectories: true) - try text.write(to: url, atomically: true, encoding: .utf8) - } catch { - throw PackagerError("can't write \(url.path): \(error)") - } - } - - /// Builds the host; the executable's path. `extraArguments` go to - /// `swift build`, such as a Swift SDK for another architecture. With - /// `staticSwift`, the Swift - /// runtime, Foundation and Dispatch are linked in, so the app runs where - /// Swift isn't installed. - public func build(configuration: String, staticSwift: Bool = true, extraArguments: [String] = [], - runner: CommandRunning) throws(PackagerError) -> URL { - try write() - var arguments = ["swift", "build", "--package-path", directory.path, "--scratch-path", - directory.appendingPathComponent(".build").path, "-c", configuration, "--product", Self.product] - if staticSwift { - arguments.append("--static-swift-stdlib") - } - arguments += extraArguments - // The host package links an app itself when this is set. - let environment = ["LINUXAPPRUNTIME_APP_LIBRARY": ""] - try runner.run(arguments, directory: directory, environment: environment) - let bin = try runner.run(arguments + ["--show-bin-path"], directory: directory, environment: environment) - .split(separator: "\n").last.map(String.init) ?? "" - return URL(fileURLWithPath: bin.trimmingCharacters(in: .whitespaces)).appendingPathComponent(Self.product) - } - - /// The AppRuntime checkout SwiftPM resolved for the build, if it cloned - /// one. - public var resolvedAppRuntime: URL? { - let checkout = directory.appendingPathComponent(".build/checkouts/AppRuntime") - return FileManager.default.fileExists(atPath: checkout.appendingPathComponent("Scripts/wasm2c-shim.py").path) ? checkout : nil - } -} - -/// A Swift string literal for `value`. -func literal(_ value: String) -> String { - var escaped = "" - for scalar in value.unicodeScalars { - switch scalar { - case "\\": escaped += "\\\\" - case "\"": escaped += "\\\"" - case "\n": escaped += "\\n" - case "\r": escaped += "\\r" - case "\t": escaped += "\\t" - default: - if scalar.value < 0x20 { - escaped += "\\u{\(String(scalar.value, radix: 16))}" - } else { - escaped.unicodeScalars.append(scalar) - } - } - } - return "\"\(escaped)\"" -} - -/// The wasm2c engine (`Packager.md` §2): AppRuntime's shim turns -/// `App.wasm` into a sealed `libapp.a`. -public struct Wasm2c { - - /// AppRuntime's checkout, for `Scripts/wasm2c-shim.py`. - public var appRuntime: URL - - public init(appRuntime: URL) { - self.appRuntime = appRuntime - } - - /// AppRuntime from `--appruntime`, then `APPRUNTIME_PATH`. - public static func locate(_ explicit: String?) -> URL? { - [explicit, ProcessInfo.processInfo.environment["APPRUNTIME_PATH"]].compactMap { $0 } - .map { URL(fileURLWithPath: $0) } - .first { FileManager.default.fileExists(atPath: $0.appendingPathComponent("Scripts/wasm2c-shim.py").path) } - } - - public func build(wasm: URL, output: URL, runner: CommandRunning) throws(PackagerError) -> URL { - let script = appRuntime.appendingPathComponent("Scripts/wasm2c-shim.py").path - try runner.run(["python3", script, "build", "--wasm", wasm.path, "--output", output.path], directory: nil, environment: [:]) - return output.appendingPathComponent("libapp.a") - } -} From 183c573ea81fe08ebd5e1eff4c3d8d3ca1e9e0f7 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:44 -0500 Subject: [PATCH 14/36] Located the runner, and built it for ports --- Sources/LinuxPackager/Runner.swift | 69 ++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 Sources/LinuxPackager/Runner.swift diff --git a/Sources/LinuxPackager/Runner.swift b/Sources/LinuxPackager/Runner.swift new file mode 100644 index 0000000..38cf380 --- /dev/null +++ b/Sources/LinuxPackager/Runner.swift @@ -0,0 +1,69 @@ +import Foundation + +/// `linux-app-host`, the runner every installed app runs in (`Plan.md` §4, +/// `Packager.md` §3). Installing an app doesn't build anything: the runner +/// is installed once, and updated on its own. +public enum Runner { + + /// The runner's program name. + public static let name = "linux-app-host" + + /// The installed runner: `explicit`, then `LINUXAPPRUNTIME_RUNNER`, then + /// the one next to `linux-app`, then the first on `PATH`. + public static func locate( + _ explicit: String? = nil, + environment: [String: String] = ProcessInfo.processInfo.environment, + tool: String? = InstalledApps.runnerPath() + ) throws(PackagerError) -> URL { + var candidates = [explicit, environment["LINUXAPPRUNTIME_RUNNER"]].compactMap { $0 } + if let tool { + candidates.append((tool as NSString).deletingLastPathComponent + "/" + name) + } + candidates += (environment["PATH"] ?? "").split(separator: ":").map { "\($0)/\(name)" } + for candidate in candidates where FileManager.default.isExecutableFile(atPath: candidate) { + return URL(fileURLWithPath: candidate).standardizedFileURL + } + throw PackagerError("can't find \(name); install it, or pass --runner or set LINUXAPPRUNTIME_RUNNER") + } + + /// This package's source, for building a runner a PortMaster port + /// carries: `--host-package`, then `LINUXAPPRUNTIME_PATH`, then the tree + /// `linux-app` was built from. + public static func source(_ explicit: String? = nil) throws(PackagerError) -> URL { + let candidates = [explicit, ProcessInfo.processInfo.environment["LINUXAPPRUNTIME_PATH"]].compactMap { $0 } + .map { URL(fileURLWithPath: $0) } + + [URL(fileURLWithPath: #filePath).deletingLastPathComponent().deletingLastPathComponent().deletingLastPathComponent()] + for candidate in candidates { + let manifest = candidate.appendingPathComponent("Package.swift") + if let text = try? String(contentsOf: manifest, encoding: .utf8), text.contains("name: \"LinuxAppRuntime\"") { + return candidate.standardizedFileURL + } + } + throw PackagerError("can't find LinuxAppRuntime's source; pass --host-package or set LINUXAPPRUNTIME_PATH") + } + + /// Builds the runner from `source`; the executable's path. Any app runs + /// in it, so it's built once per target. `extraArguments` go to `swift + /// build`, such as a Swift SDK for another architecture. With + /// `staticSwift`, the Swift runtime, Foundation and Dispatch are linked + /// in, so it runs where Swift isn't installed. + public static func build( + source: URL, + scratch: URL, + configuration: String = "release", + staticSwift: Bool = true, + extraArguments: [String] = [], + runner: CommandRunning + ) throws(PackagerError) -> URL { + var arguments = ["swift", "build", "--package-path", source.path, "--scratch-path", scratch.path, + "-c", configuration, "--product", name] + if staticSwift { + arguments.append("--static-swift-stdlib") + } + arguments += extraArguments + try runner.run(arguments, directory: nil, environment: [:]) + let bin = try runner.run(arguments + ["--show-bin-path"], directory: nil, environment: [:]) + .split(separator: "\n").last.map(String.init) ?? "" + return URL(fileURLWithPath: bin.trimmingCharacters(in: .whitespaces)).appendingPathComponent(name) + } +} From 633b2318fc53c0fe7b2bcd8e0b4a4250348d79df Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:44 -0500 Subject: [PATCH 15/36] Took a slice's libapp.so --- Sources/LinuxPackager/UniversalBundle.swift | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/Sources/LinuxPackager/UniversalBundle.swift b/Sources/LinuxPackager/UniversalBundle.swift index 4c3d5b9..a1a8c8e 100644 --- a/Sources/LinuxPackager/UniversalBundle.swift +++ b/Sources/LinuxPackager/UniversalBundle.swift @@ -3,8 +3,9 @@ import Foundation import LinuxHost /// A universal bundle from AppRuntime's `guest.py bundle`: `Info.plist`, -/// `lib//libapp.a`, `wasm32/App.wasm`, and optionally `resources/`, -/// `icon.png` and `_CodeSignature/CodeResources` (`Packager.md` §1). +/// `lib//libapp.so` and `libapp.a`, `wasm32/App.wasm`, +/// `_CodeSignature/CodeResources`, and optionally `resources/` and +/// `icon.png` (`Packager.md` §1). public struct UniversalBundle { public let url: URL @@ -53,9 +54,10 @@ public struct UniversalBundle { ?? executable } - /// The target's sealed slice, if the bundle has one. + /// The target's slice, the `libapp.so` the runner loads, if the bundle + /// has one. public func slice(_ target: LinuxTarget) -> URL? { - existing("lib/\(target.rawValue)/libapp.a") + existing(target.sharedLibrary) } public var wasm: URL? { From 2fd8f90f903a2a8dc5f8b233606cfe92bae38cfe Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:44 -0500 Subject: [PATCH 16/36] Validated libapp.so and required a signature --- Sources/LinuxPackager/Validator.swift | 112 ++++++++------------------ 1 file changed, 34 insertions(+), 78 deletions(-) diff --git a/Sources/LinuxPackager/Validator.swift b/Sources/LinuxPackager/Validator.swift index 2c7ecc3..3aad9fa 100644 --- a/Sources/LinuxPackager/Validator.swift +++ b/Sources/LinuxPackager/Validator.swift @@ -29,45 +29,30 @@ public enum HostContracts { public static let capabilities: Set = [.bluetooth, .graphics, .network] } -/// How the guest's code gets into the app (`Packager.md` §2). -public enum Engine: String, CaseIterable, Sendable { - /// The bundle's sealed `libapp.a` for the target. - case slice - /// `App.wasm` translated to C by AppRuntime's wasm2c shim. - case wasm2c - - /// A slice if the bundle has one, else wasm2c. - public static func preferred(for bundle: UniversalBundle, target: LinuxTarget) -> Engine { - bundle.slice(target) != nil ? .slice : .wasm2c - } -} - -/// The checks of `Packager.md` §1. +/// The checks of `Packager.md` §1, which install makes before it copies an +/// app. The runner makes the ABI and contract checks again at each launch. public struct Validator { public var bundle: UniversalBundle public var target: LinuxTarget - public var engine: Engine - /// Missing contracts warn instead of failing; the guest sees them as /// absent. public var allowMissingContracts = false public var provided: [String: ContractDescriptor] = HostContracts.provided - public init(bundle: UniversalBundle, target: LinuxTarget, engine: Engine) { + public init(bundle: UniversalBundle, target: LinuxTarget) { self.bundle = bundle self.target = target - self.engine = engine } public func validate() -> [Diagnostic] { var diagnostics: [Diagnostic] = [] let info = bundle.info - if !Self.isIdentifier(info.identifier) { + if !InstalledApps.isIdentifier(info.identifier) { diagnostics.append(.error("CFBundleIdentifier \"\(info.identifier)\" isn't a reverse-DNS identifier")) } if !Self.isFileName(bundle.executable) { @@ -88,22 +73,18 @@ public struct Validator { diagnostics.append(.warning("\(contract.name) is version \(descriptor.version) on Linux; the app was built against \(contract.version)")) } } + if !FileManager.default.fileExists(atPath: bundle.url.appendingPathComponent("_CodeSignature/CodeResources").path) { + diagnostics.append(.error("the bundle isn't signed: it has no _CodeSignature/CodeResources, which the runner checks its library against")) + } for problem in bundle.codeResourceProblems() { diagnostics.append(.error("the bundle doesn't match its CodeResources: \(problem)")) } - switch engine { - case .slice: - if let slice = bundle.slice(target) { - for problem in SliceInspector.problems(slice, target: target) { - diagnostics.append(.error("\(target.rawValue) slice: \(problem)")) - } - } else { - diagnostics.append(.error("the bundle has no \(target.rawValue) slice; use --engine wasm2c")) - } - case .wasm2c: - if bundle.wasm == nil { - diagnostics.append(.error("the bundle has no wasm32/App.wasm")) + if let slice = bundle.slice(target) { + for problem in SliceInspector.problems(slice, target: target) { + diagnostics.append(.error("\(target.rawValue) slice: \(problem)")) } + } else { + diagnostics.append(.error("the bundle has no \(target.rawValue) slice (\(target.sharedLibrary))")) } for capability in info.capabilities.subtracting(HostContracts.capabilities).sorted(by: { $0.rawValue < $1.rawValue }) { diagnostics.append(.warning("the app declares \(capability.rawValue), which the Linux host doesn't support yet")) @@ -111,66 +92,41 @@ public struct Validator { return diagnostics } - /// `org.example.App`: two or more dot-separated parts of letters, - /// digits, `-` and `_`. - static func isIdentifier(_ value: String) -> Bool { - let parts = value.split(separator: ".", omittingEmptySubsequences: false) - return parts.count >= 2 && parts.allSatisfy { part in - !part.isEmpty && part.allSatisfy { $0.isASCII && ($0.isLetter || $0.isNumber || $0 == "-" || $0 == "_") } - } - } - static func isFileName(_ value: String) -> Bool { !value.isEmpty && value != "." && value != ".." && !value.contains("/") && !value.contains("\0") && !value.hasPrefix("-") } } -/// Reads a slice's archive: every ELF object in it must be for the target. +/// Reads a slice's `libapp.so`: a shared library for the target. +/// `guest.py` checked the rest when it built it: what it leaves undefined, +/// what it exports, and that it names no other library. public enum SliceInspector { - public static func problems(_ archive: URL, target: LinuxTarget) -> [String] { - guard let data = FileManager.default.contents(atPath: archive.path) else { - return ["can't read \(archive.path)"] + public static func problems(_ library: URL, target: LinuxTarget) -> [String] { + guard let handle = FileHandle(forReadingAtPath: library.path) else { + return ["can't read \(library.lastPathComponent)"] } - let machines: [UInt16] - do { - machines = try elfMachines(Array(data)) - } catch { - return [error.message] + defer { try? handle.close() } + let header = Array((try? handle.read(upToCount: 20)) ?? Data()) + guard header.count == 20, header.starts(with: [0x7F, 0x45, 0x4C, 0x46]) else { + return ["\(library.lastPathComponent) isn't an ELF file"] } - if machines.isEmpty { - return ["the archive has no ELF objects"] + var problems: [String] = [] + let elfClass = header[4], endian = header[5] + let expectedClass: UInt8 = target == .armv7 ? 1 : 2 + if elfClass != expectedClass || endian != 1 { + problems.append("it's \(elfClass == 1 ? "32" : "64")-bit\(endian == 1 ? "" : " big-endian"), not as \(target.machine) is") } - let wrong = Set(machines.filter { $0 != target.elfMachine }) - return wrong.isEmpty ? [] : ["objects are for ELF machine \(wrong.sorted()), not \(target.elfMachine) (\(target.machine))"] - } - - /// `e_machine` of each ELF member of a `!` archive. - static func elfMachines(_ bytes: [UInt8]) throws(PackagerError) -> [UInt16] { - let magic = Array("!\n".utf8) - guard bytes.starts(with: magic) else { - throw PackagerError("not an ar archive") + let type = UInt16(header[16]) | UInt16(header[17]) << 8 + if type != 3 { + problems.append("it isn't a shared library (ELF type \(type))") } - var machines: [UInt16] = [] - var offset = magic.count - while offset + 60 <= bytes.count { - let header = bytes[offset..= 20, body.starts(with: [0x7F, 0x45, 0x4C, 0x46]) { - let start = body.startIndex - machines.append(UInt16(body[start + 18]) | UInt16(body[start + 19]) << 8) - } - offset += 60 + size + (size % 2) + let machine = UInt16(header[18]) | UInt16(header[19]) << 8 + if machine != target.elfMachine { + problems.append("it's for ELF machine \(machine), not \(target.elfMachine) (\(target.machine))") } - return machines + return problems } } From 963bd66c7bc7bd2fcfd770999297166fabaf9b77 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:44 -0500 Subject: [PATCH 17/36] Passed arguments to the desktop entry's program --- Sources/LinuxPackager/DesktopEntry.swift | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/Sources/LinuxPackager/DesktopEntry.swift b/Sources/LinuxPackager/DesktopEntry.swift index 575471d..01cd774 100644 --- a/Sources/LinuxPackager/DesktopEntry.swift +++ b/Sources/LinuxPackager/DesktopEntry.swift @@ -8,15 +8,20 @@ public struct DesktopEntry: Equatable { /// The program: a name on `PATH`, or an absolute path. public var exec: String + /// What the program is given before the URL to open: the runner, the + /// app's identifier. + public var arguments: [String] + public var version: String /// `Name[locale]`, by POSIX locale (`pt_BR`). public var localizedNames: [String: String] = [:] - public init(identifier: String, name: String, exec: String, version: String) { + public init(identifier: String, name: String, exec: String, arguments: [String] = [], version: String) { self.identifier = identifier self.name = name self.exec = exec + self.arguments = arguments self.version = version } @@ -28,7 +33,7 @@ public struct DesktopEntry: Equatable { ] lines += localizedNames.sorted { $0.key < $1.key }.map { "Name[\($0.key)]=\(Self.escape($0.value))" } lines += [ - "Exec=\(Self.quote(exec)) %u", + "Exec=\(([exec] + arguments).map(Self.quote).joined(separator: " ")) %u", "Icon=\(Self.escape(identifier))", "Terminal=false", "Categories=Utility;", From b749e5050dd8f155194e49a4e30c1ce321de1c05 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:44 -0500 Subject: [PATCH 18/36] Installed apps by thinning their bundles, with nothing built --- Sources/LinuxPackager/Packager.swift | 202 +++++++++++---------------- 1 file changed, 82 insertions(+), 120 deletions(-) diff --git a/Sources/LinuxPackager/Packager.swift b/Sources/LinuxPackager/Packager.swift index 0010438..70a558b 100644 --- a/Sources/LinuxPackager/Packager.swift +++ b/Sources/LinuxPackager/Packager.swift @@ -1,43 +1,30 @@ import Foundation -/// `linux-app package`, `install` and `run` (`Packager.md` §2 – §4). +/// `linux-app package` and `install` (`Packager.md` §2 – §4): checks an app +/// against this host, thins its bundle to what the target runs, and writes +/// it where the runner finds it. Nothing is compiled or linked: the device +/// needs the runner, and no toolchain. public struct Packager { public struct Options { public var target: LinuxTarget - public var engine: Engine - /// `release` or `debug`. - public var configuration = "release" public var allowMissingContracts = false - /// The install tree; `/out` if `nil`. + /// The install tree; `.build/linux-app//` if `nil`. public var output: URL? /// Also write `--.tar.gz`. public var archive = false - /// Link the Swift runtime in (`--static-swift-stdlib`). - public var staticSwift = true - /// More `swift build` arguments: `--swift-sdk`, `--destination`. - public var buildArguments: [String] = [] - public var hostPackage: URL - /// AppRuntime, for the wasm2c engine. - public var appRuntime: URL? - /// `.build/linux-app` in the current directory by default. - public var workRoot: URL - - public init(target: LinuxTarget, engine: Engine, hostPackage: URL, - workRoot: URL = URL(fileURLWithPath: ".build/linux-app")) { + + public init(target: LinuxTarget) { self.target = target - self.engine = engine - self.hostPackage = hostPackage - self.workRoot = workRoot } } - /// What `package` made. + /// What `package` or `install` wrote. public struct Result { - /// The install tree. + /// The install tree, or the prefix installed into. public var root: URL - /// `bin/` in it. - public var executable: URL + /// The thinned bundle in it: `lib/linux-app/.app`. + public var bundle: URL public var archive: URL? public var diagnostics: [Diagnostic] } @@ -54,28 +41,20 @@ public struct Packager { self.runner = runner } - /// The app's work directory: its generated host package and build. - public var work: URL { - options.workRoot.appendingPathComponent(bundle.info.identifier).appendingPathComponent(options.target.rawValue) - } - public func validate() -> [Diagnostic] { - var validator = Validator(bundle: bundle, target: options.target, engine: options.engine) + var validator = Validator(bundle: bundle, target: options.target) validator.allowMissingContracts = options.allowMissingContracts return validator.validate() } - /// Validates, builds the host with the app, and writes the install tree. + /// Validates, and writes the install tree, for a distribution's package + /// or an archive: its desktop entry runs the runner from `PATH`. public func package() throws(PackagerError) -> Result { - let diagnostics = validate() - let errors = diagnostics.filter { $0.severity == .error } - guard errors.isEmpty else { - throw PackagerError(errors.map(\.description).joined(separator: "\n")) - } - let library = try library() - let binary = try buildHost(library: library) - let root = options.output ?? work.appendingPathComponent("out") - try assemble(binary: binary, into: root, exec: bundle.executable) + let diagnostics = try checked() + let root = options.output + ?? URL(fileURLWithPath: ".build/linux-app").appendingPathComponent(bundle.info.identifier) + .appendingPathComponent(options.target.rawValue) + let installed = try assemble(into: root, runner: Runner.name) var archive: URL? if options.archive { let name = "\(bundle.info.identifier)-\(bundle.info.version.isEmpty ? "0" : bundle.info.version)-\(options.target.rawValue).tar.gz" @@ -83,112 +62,95 @@ public struct Packager { try runner.run(["tar", "-czf", url.path, "-C", root.path, "."], directory: nil, environment: [:]) archive = url } - return Result(root: root, executable: root.appendingPathComponent("bin/\(bundle.executable)"), - archive: archive, diagnostics: diagnostics) + return Result(root: root, bundle: installed, archive: archive, diagnostics: diagnostics) } - /// Builds the host linked with `library`; the executable's path. - func buildHost(library: URL) throws(PackagerError) -> URL { - let directory = work.appendingPathComponent("host") - let host = HostPackage(directory: directory, hostPackage: options.hostPackage, - executable: bundle.executable, library: try HostPackage.stage(library, in: directory), - linksGL: bundle.info.capabilities.contains(.graphics)) - return try host.build(configuration: options.configuration, staticSwift: options.staticSwift, - extraArguments: options.buildArguments, runner: runner) + /// Validates, and installs into `prefix` (`~/.local` by default), with + /// the desktop entry running `runner` by its absolute path. + public func install(prefix: URL, runner program: URL) throws(PackagerError) -> Result { + let diagnostics = try checked() + let installed = try assemble(into: prefix, runner: program.path) + let applications = prefix.appendingPathComponent("share/applications") + _ = try? runner.run(["update-desktop-database", applications.path], directory: nil, environment: [:]) + return Result(root: prefix, bundle: installed, archive: nil, diagnostics: diagnostics) } - /// The app's library for the engine. - func library() throws(PackagerError) -> URL { - switch options.engine { - case .slice: - guard let slice = bundle.slice(options.target) else { - throw PackagerError("the bundle has no \(options.target.rawValue) slice") - } - return slice - case .wasm2c: - guard let wasm = bundle.wasm else { - throw PackagerError("the bundle has no wasm32/App.wasm") - } - var appRuntime = options.appRuntime - if appRuntime == nil { - // The checkout SwiftPM resolves for the host build. - let host = HostPackage(directory: work.appendingPathComponent("host"), hostPackage: options.hostPackage, - executable: bundle.executable, library: wasm) - try host.write() - try runner.run(["swift", "package", "--package-path", host.directory.path, "--scratch-path", - host.directory.appendingPathComponent(".build").path, "resolve"], directory: nil, environment: [:]) - appRuntime = host.resolvedAppRuntime - } - guard let appRuntime else { - throw PackagerError("wasm2c needs AppRuntime's checkout; pass --appruntime or set APPRUNTIME_PATH") - } - return try Wasm2c(appRuntime: appRuntime).build(wasm: wasm, output: work.appendingPathComponent("wasm2c"), runner: runner) + private func checked() throws(PackagerError) -> [Diagnostic] { + let diagnostics = validate() + let errors = diagnostics.filter { $0.severity == .error } + guard errors.isEmpty else { + throw PackagerError(errors.map(\.description).joined(separator: "\n")) } + return diagnostics } // MARK: The tree - /// Writes the install tree of `Packager.md` §4 into `root`, replacing an - /// earlier one. `exec` is the desktop entry's program. - func assemble(binary: URL, into root: URL, exec: String) throws(PackagerError) { + /// What a thinned bundle keeps: everything the runner reads, and the + /// signature, which still holds for every file kept. + static let kept = ["Info.plist", "resources", "icon.png", "_CodeSignature"] + + /// Writes the app into `root` (`Packager.md` §4), replacing an earlier + /// copy; the thinned bundle. `runner` is the desktop entry's program. + /// + /// ``` + /// lib/linux-app/.app/ Info.plist, resources/, icon.png, + /// _CodeSignature/, lib//libapp.so + /// share/applications/.desktop + /// share/icons/hicolor/256x256/apps/.png + /// ``` + func assemble(into root: URL, runner: String) throws(PackagerError) -> URL { let identifier = bundle.info.identifier let files = FileManager.default - let lib = root.appendingPathComponent("lib/\(identifier)") + let apps = root.appendingPathComponent(InstalledApps.directory) + let app = apps.appendingPathComponent("\(identifier).app") + let staged = apps.appendingPathComponent(".\(identifier).app.new") do { - for path in ["bin/\(bundle.executable)", "lib/\(identifier)", "share/applications/\(identifier).desktop", - "share/icons/hicolor/256x256/apps/\(identifier).png"] { - let url = root.appendingPathComponent(path) - if files.fileExists(atPath: url.path) || (try? files.destinationOfSymbolicLink(atPath: url.path)) != nil { - try files.removeItem(at: url) - } - } - try files.createDirectory(at: lib, withIntermediateDirectories: true) - let program = lib.appendingPathComponent(bundle.executable) - try files.copyItem(at: binary, to: program) - try files.setAttributes([.posixPermissions: 0o755], ofItemAtPath: program.path) - - // The bundle without its code, which is in the program now. - let app = lib.appendingPathComponent("App.app") - try files.createDirectory(at: app, withIntermediateDirectories: true) - for name in try files.contentsOfDirectory(atPath: bundle.url.path) - where !["lib", "wasm32", "_CodeSignature"].contains(name) { - try files.copyItem(at: bundle.url.appendingPathComponent(name), to: app.appendingPathComponent(name)) - } - - let bin = root.appendingPathComponent("bin") - try files.createDirectory(at: bin, withIntermediateDirectories: true) - try files.createSymbolicLink(atPath: bin.appendingPathComponent(bundle.executable).path, - withDestinationPath: "../lib/\(identifier)/\(bundle.executable)") + // The new copy is complete before it replaces the old one. + try? files.removeItem(at: staged) + try files.createDirectory(at: staged, withIntermediateDirectories: true) + try thin(into: staged) + try? files.removeItem(at: app) + try files.moveItem(at: staged, to: app) let applications = root.appendingPathComponent("share/applications") try files.createDirectory(at: applications, withIntermediateDirectories: true) - var entry = DesktopEntry(identifier: identifier, name: bundle.displayName, exec: exec, version: bundle.info.version) + var entry = DesktopEntry(identifier: identifier, name: bundle.displayName, exec: runner, + arguments: [identifier], version: bundle.info.version) entry.localizedNames = bundle.localizedDisplayNames try entry.text.write(to: applications.appendingPathComponent("\(identifier).desktop"), atomically: true, encoding: .utf8) - if let icon = bundle.icon { - let icons = root.appendingPathComponent("share/icons/hicolor/256x256/apps") + let icons = root.appendingPathComponent("share/icons/hicolor/256x256/apps") + let icon = icons.appendingPathComponent("\(identifier).png") + try? files.removeItem(at: icon) + if let source = bundle.icon { try files.createDirectory(at: icons, withIntermediateDirectories: true) - try files.copyItem(at: icon, to: icons.appendingPathComponent("\(identifier).png")) + try files.copyItem(at: source, to: icon) } } catch let error as PackagerError { throw error } catch { + try? files.removeItem(at: staged) throw PackagerError("can't write the app into \(root.path): \(error)") } + return app } - /// Packages into `prefix` (`~/.local` by default), with the desktop - /// entry running the program by its absolute path. - public func install(prefix: URL) throws(PackagerError) -> Result { - var staged = self - staged.options.output = nil - let result = try staged.package() - let binary = result.root.appendingPathComponent("lib/\(bundle.info.identifier)/\(bundle.executable)") - let exec = prefix.appendingPathComponent("bin/\(bundle.executable)").path - try assemble(binary: binary, into: prefix, exec: exec) - let applications = prefix.appendingPathComponent("share/applications") - _ = try? runner.run(["update-desktop-database", applications.path], directory: nil, environment: [:]) - return Result(root: prefix, executable: URL(fileURLWithPath: exec), archive: nil, diagnostics: result.diagnostics) + /// Copies what the target runs into `directory`: the kept files, and + /// the target's `libapp.so`. + func thin(into directory: URL) throws { + let files = FileManager.default + for name in Self.kept { + let source = bundle.url.appendingPathComponent(name) + if files.fileExists(atPath: source.path) { + try files.copyItem(at: source, to: directory.appendingPathComponent(name)) + } + } + guard let slice = bundle.slice(options.target) else { + throw PackagerError("the bundle has no \(options.target.rawValue) slice") + } + let library = directory.appendingPathComponent(options.target.sharedLibrary) + try files.createDirectory(at: library.deletingLastPathComponent(), withIntermediateDirectories: true) + try files.copyItem(at: slice, to: library) } } From 02e7f67560849ec0a181e4817933d997bb8f9db9 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:44 -0500 Subject: [PATCH 19/36] Made ports carry the runner and libapp.so --- Sources/LinuxPackager/PortMaster.swift | 53 +++++++++++++++++++------- 1 file changed, 39 insertions(+), 14 deletions(-) diff --git a/Sources/LinuxPackager/PortMaster.swift b/Sources/LinuxPackager/PortMaster.swift index 66895ec..1ba5b7f 100644 --- a/Sources/LinuxPackager/PortMaster.swift +++ b/Sources/LinuxPackager/PortMaster.swift @@ -1,11 +1,23 @@ import Foundation /// `linux-app portmaster`: a PortMaster port of an app (`PortMaster.md`). +/// +/// A handheld has no runner installed, so the port carries one, named +/// after the app, beside the app's bundle thinned to its `libapp.so` for +/// each architecture. The runner is the same for every app; it's built +/// here because a port's runs on an older glibc than a distribution's. public struct PortMasterPort { public struct Options { /// Where the port's directory and zip go. public var output: URL + /// This package's source, which the runner is built from. + public var source: URL = URL(fileURLWithPath: ".") + /// The runner's build directory. + public var scratch: URL = URL(fileURLWithPath: ".build/linux-app/runner") + /// More `swift build` arguments: a Swift SDK's destination for + /// another architecture. + public var buildArguments: [String] = [] /// The libraries the port bundles: SDL3, SDL3_ttf, and whatever the /// build environment says (`LINUXAPPRUNTIME_PORT_LIBS`). public var libraries: URL? @@ -28,7 +40,7 @@ public struct PortMasterPort { public var diagnostics: [Diagnostic] } - /// Builds the host: a `Packager` for `linux-arm64` or `linux-armv7`. + /// Checks the app: a `Packager` for `linux-arm64` or `linux-armv7`. public var packager: Packager public var options: Options @@ -74,15 +86,15 @@ public struct PortMasterPort { guard errors.isEmpty else { throw PackagerError(errors.map(\.description).joined(separator: "\n")) } - var packager = self.packager - packager.options.configuration = "release" - packager.options.staticSwift = true - let binary = try packager.buildHost(library: try packager.library()) + let target = packager.options.target + let binary = try Runner.build(source: options.source, + scratch: options.scratch.appendingPathComponent(target.rawValue), + extraArguments: options.buildArguments, runner: packager.runner) let result = try assemble(binary: binary, architecture: architecture) return Result(directory: result.directory, zip: result.zip, minimumGLIBC: result.glibc, diagnostics: diagnostics) } - /// Writes the port around a built host, adding to a port that has the + /// Writes the port around a built runner, adding to a port that has the /// other architecture. func assemble(binary: URL, architecture: String) throws(PackagerError) -> (directory: URL, zip: URL, glibc: String?) { let files = FileManager.default @@ -91,7 +103,8 @@ public struct PortMasterPort { do { try files.createDirectory(at: game, withIntermediateDirectories: true) - // The program and its libraries, for this architecture. + // The runner, named after the app so that's what the device + // shows running, and its libraries, for this architecture. let program = game.appendingPathComponent("\(bundle.executable).\(architecture)") try replace(program, with: binary) try files.setAttributes([.posixPermissions: 0o755], ofItemAtPath: program.path) @@ -113,15 +126,27 @@ public struct PortMasterPort { } } - // What both architectures share. + // The bundle, thinned: what both architectures share, and each + // one's libapp.so, keeping the other architecture's. let app = game.appendingPathComponent("App.app") - if files.fileExists(atPath: app.path) { - try files.removeItem(at: app) - } try files.createDirectory(at: app, withIntermediateDirectories: true) - for name in try files.contentsOfDirectory(atPath: bundle.url.path) where !["lib", "wasm32", "_CodeSignature"].contains(name) { - try files.copyItem(at: bundle.url.appendingPathComponent(name), to: app.appendingPathComponent(name)) + for name in Packager.kept { + let destination = app.appendingPathComponent(name) + if files.fileExists(atPath: destination.path) { + try files.removeItem(at: destination) + } + let source = bundle.url.appendingPathComponent(name) + if files.fileExists(atPath: source.path) { + try files.copyItem(at: source, to: destination) + } + } + let target = packager.options.target + guard let slice = bundle.slice(target) else { + throw PackagerError("the bundle has no \(target.rawValue) slice") } + let library = app.appendingPathComponent(target.sharedLibrary) + try files.createDirectory(at: library.deletingLastPathComponent(), withIntermediateDirectories: true) + try replace(library, with: slice) if let fonts = options.fonts, files.fileExists(atPath: fonts.path) { let destination = game.appendingPathComponent("fonts") if files.fileExists(atPath: destination.path) { @@ -385,7 +410,7 @@ public struct PortMasterPort { try files.removeItem(at: directory) } try files.createDirectory(at: directory, withIntermediateDirectories: true) - let host = packager.options.hostPackage.appendingPathComponent("LICENSE") + let host = options.source.appendingPathComponent("LICENSE") if files.fileExists(atPath: host.path) { try files.copyItem(at: host, to: directory.appendingPathComponent("LinuxAppRuntime.txt")) } From 1e3401afe247df3e36869d52a7938e326bb89500 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:44 -0500 Subject: [PATCH 20/36] Made linux-app install for the runner --- Sources/LinuxAppTool/LinuxApp.swift | 113 +++++++++++++--------------- 1 file changed, 51 insertions(+), 62 deletions(-) diff --git a/Sources/LinuxAppTool/LinuxApp.swift b/Sources/LinuxAppTool/LinuxApp.swift index cb56dc0..34c9f07 100644 --- a/Sources/LinuxAppTool/LinuxApp.swift +++ b/Sources/LinuxAppTool/LinuxApp.swift @@ -20,64 +20,33 @@ struct BundleOptions: ParsableArguments { @Argument(help: "The universal bundle, from guest.py bundle.") var bundle: String - @Option(help: "linux-arm64 or linux-x86_64; this machine's by default.") + @Option(help: "linux-arm64, linux-x86_64 or linux-armv7; this machine's by default.") var target: String? - @Option(help: "slice or wasm2c; a slice if the bundle has one.") - var engine: String? - @Flag(help: "Warn about contracts this host lacks instead of failing; the app sees them as absent.") var allowMissingContracts = false - @Option(help: "LinuxAppRuntime's source; LINUXAPPRUNTIME_PATH, or where linux-app was built from.") - var hostPackage: String? - - @Option(help: "AppRuntime's checkout, for wasm2c; APPRUNTIME_PATH, or the one SwiftPM resolves.") - var appruntime: String? - - @Option(help: "The work directory for generated host packages and builds.") - var work = ".build/linux-app" - - @Flag(name: .shortAndLong, help: "Show the commands the packager runs.") + @Flag(name: .shortAndLong, help: "Show the commands the packager runs.") var verbose = false - func load() throws -> (UniversalBundle, LinuxTarget, Engine) { + func load() throws -> (UniversalBundle, LinuxTarget) { let bundle = try UniversalBundle(url: URL(fileURLWithPath: self.bundle)) - let target: LinuxTarget if let name = self.target { guard let named = LinuxTarget(rawValue: name) else { throw ValidationError("unknown target \(name); one of \(LinuxTarget.allCases.map(\.rawValue).joined(separator: ", "))") } - target = named - } else { - guard let native = LinuxTarget.native else { - throw ValidationError("this machine isn't a Linux target; pass --target") - } - target = native + return (bundle, named) } - let engine: Engine - if let name = self.engine { - guard let named = Engine(rawValue: name) else { - throw ValidationError("unknown engine \(name); slice or wasm2c") - } - engine = named - } else { - engine = .preferred(for: bundle, target: target) + guard let native = LinuxTarget.native else { + throw ValidationError("this machine isn't a Linux target; pass --target") } - return (bundle, target, engine) + return (bundle, native) } - func packager(configuration: String = "release", buildArguments: [String] = []) throws -> Packager { - let (bundle, target, engine) = try load() - if let native = LinuxTarget.native, native != target, buildArguments.isEmpty { - throw ValidationError("building for \(target.rawValue) on \(native.rawValue) isn't supported yet") - } - var options = Packager.Options(target: target, engine: engine, hostPackage: try HostPackage.locate(hostPackage)) - options.configuration = configuration + func packager() throws -> Packager { + let (bundle, target) = try load() + var options = Packager.Options(target: target) options.allowMissingContracts = allowMissingContracts - options.appRuntime = Wasm2c.locate(appruntime) - options.buildArguments = buildArguments - options.workRoot = URL(fileURLWithPath: work) return Packager(bundle: bundle, options: options, runner: CommandRunner(verbose: verbose)) } } @@ -97,35 +66,33 @@ extension LinuxApp { @OptionGroup var options: BundleOptions func run() throws { - let (bundle, target, engine) = try options.load() - var validator = Validator(bundle: bundle, target: target, engine: engine) + let (bundle, target) = try options.load() + var validator = Validator(bundle: bundle, target: target) validator.allowMissingContracts = options.allowMissingContracts let diagnostics = validator.validate() report(diagnostics) if diagnostics.contains(where: { $0.severity == .error }) { throw ExitCode.failure } - print("ok: \(bundle.info.identifier) for \(target.rawValue) with \(engine.rawValue)") + print("ok: \(bundle.info.identifier) for \(target.rawValue)") } } struct Package: ParsableCommand { - static let configuration = CommandConfiguration(abstract: "Build the app and write its install tree.") + static let configuration = CommandConfiguration( + abstract: "Write the app's install tree: its bundle thinned to one target, and its desktop entry.") @OptionGroup var options: BundleOptions - @Option(help: "The install tree's directory; .build/linux-app///out by default.") + @Option(help: "The install tree's directory; .build/linux-app// by default.") var output: String? - @Option(help: "release or debug.") - var configuration = "release" - @Flag(help: "Also write --.tar.gz next to the tree.") var archive = false func run() throws { - var packager = try options.packager(configuration: configuration) + var packager = try options.packager() packager.options.output = output.map { URL(fileURLWithPath: $0) } packager.options.archive = archive let result = try packager.package() @@ -139,39 +106,52 @@ extension LinuxApp { struct Install: ParsableCommand { - static let configuration = CommandConfiguration(abstract: "Package the app and install it for the user.") + static let configuration = CommandConfiguration( + abstract: "Install the app for the user, to run in the installed runner. Nothing is built.") @OptionGroup var options: BundleOptions @Option(help: "Where to install; ~/.local by default.") var prefix: String? + @Option(help: "The runner the desktop entry starts; LINUXAPPRUNTIME_RUNNER, the one next to linux-app, or linux-app-host on PATH.") + var runner: String? + func run() throws { let packager = try options.packager() + let program = try Runner.locate(runner) let prefix = prefix.map { URL(fileURLWithPath: $0) } ?? FileManager.default.homeDirectoryForCurrentUser.appendingPathComponent(".local") - let result = try packager.install(prefix: prefix) + let result = try packager.install(prefix: prefix, runner: program) report(result.diagnostics) - print(result.executable.path) + print(result.bundle.path) } } struct Run: ParsableCommand { - static let configuration = CommandConfiguration(abstract: "Package a debug build and run it.") + static let configuration = CommandConfiguration(abstract: "Check the app and run it in the runner, as it is.") @OptionGroup var options: BundleOptions - @Argument(parsing: .postTerminator, help: "Arguments for the app's host, after --.") + @Option(help: "The runner; as for install.") + var runner: String? + + @Argument(parsing: .postTerminator, help: "More arguments for the runner, after --: a URL to open.") var arguments: [String] = [] func run() throws { - let packager = try options.packager(configuration: "debug") - let result = try packager.package() - report(result.diagnostics) + let (bundle, target) = try options.load() + var validator = Validator(bundle: bundle, target: target) + validator.allowMissingContracts = options.allowMissingContracts + let diagnostics = validator.validate() + report(diagnostics) + if diagnostics.contains(where: { $0.severity == .error }) { + throw ExitCode.failure + } let process = Process() - process.executableURL = result.executable - process.arguments = arguments + process.executableURL = try Runner.locate(runner) + process.arguments = ["--bundle", bundle.url.path] + arguments try process.run() process.waitUntilExit() throw ExitCode(process.terminationStatus) @@ -210,12 +190,21 @@ extension LinuxApp { @Option(help: "A screenshot; the app's icon by default.") var screenshot: String? + @Option(help: "LinuxAppRuntime's source, which the port's runner is built from; LINUXAPPRUNTIME_PATH, or where linux-app was built from.") + var hostPackage: String? + + @Option(help: "The runner's build directory.") + var work = ".build/linux-app/runner" + func run() throws { let environment = ProcessInfo.processInfo.environment let destination = destination ?? environment["LINUXAPPRUNTIME_SWIFT_DESTINATION"] - // SwiftPM's default build system ignores destination files. - let packager = try options.packager(buildArguments: destination.map { ["--build-system", "native", "--destination", $0] } ?? []) + let packager = try options.packager() var portOptions = PortMasterPort.Options(output: URL(fileURLWithPath: output)) + portOptions.source = try Runner.source(hostPackage) + portOptions.scratch = URL(fileURLWithPath: work) + // SwiftPM's default build system ignores destination files. + portOptions.buildArguments = destination.map { ["--build-system", "native", "--destination", $0] } ?? [] portOptions.libraries = (libraries ?? environment["LINUXAPPRUNTIME_PORT_LIBS"]).map { URL(fileURLWithPath: $0) } portOptions.fonts = URL(fileURLWithPath: fonts) portOptions.porters = porter From 32ef2dcec21b49fce142346fff619d809ccb2060 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:44 -0500 Subject: [PATCH 21/36] Exported rt.h from the runner and linked no app --- Package.swift | 37 +++++++++++++++++-------------------- 1 file changed, 17 insertions(+), 20 deletions(-) diff --git a/Package.swift b/Package.swift index 88ea614..4d164ad 100644 --- a/Package.swift +++ b/Package.swift @@ -4,18 +4,15 @@ import PackageDescription /// The Linux host for AppRuntime apps (`Documentation/Plan.md`). /// -/// AppRuntime comes without its `GuestExports` trait: the app's library, a -/// sealed slice, defines `rt_dispatch` and `rt_finalize`, and the host's own +/// `linux-app-host` is the runner: it loads an app's `libapp.so`, which +/// defines `rt_main`, `rt_dispatch` and `rt_finalize`, and links no app. +/// AppRuntime comes without its `GuestExports` trait, so the host's own /// `DynamicRuntime` binds to the runtime directly. /// /// The environment: /// /// - `APPRUNTIME_PATH`: a local AppRuntime checkout instead of GitHub; /// `CACAO_PATH` likewise for PureSwift/Cacao. -/// - `LINUXAPPRUNTIME_APP_LIBRARY`: an app's `libapp.a` (a `linux-arm64` or -/// `linux-x86_64` slice from `guest.py slice`), which `linux-app-host` -/// links, with `libGLESv2` if the app calls GL. Without it, -/// `linux-app-host` builds without an app and says so when run. let environment = ProcessInfo.processInfo.environment let appRuntime: Package.Dependency = { @@ -46,10 +43,6 @@ let swiftUI: [Target.Dependency] = [ let swiftUI: [Target.Dependency] = [] #endif -let appLibrary = environment["LINUXAPPRUNTIME_APP_LIBRARY"].flatMap { path in - FileManager.default.fileExists(atPath: path) ? path : nil -} - func runtime(_ product: String) -> Target.Dependency { .product(name: product, package: "AppRuntime") } @@ -101,7 +94,7 @@ let package = Package( .target( name: "LinuxHost", dependencies: [runtime("CRuntime"), runtime("RuntimeCore"), runtime("RuntimeNative"), runtime("DynamicRuntime"), runtime("RuntimeABI"), - runtime("RuntimeHost"), runtime("DynamicFiles")], + runtime("RuntimeHost"), runtime("DynamicFiles"), .product(name: "Crypto", package: "swift-crypto")], swiftSettings: host ), @@ -163,23 +156,26 @@ let package = Package( // MARK: - App - // libc functions app slices need that older glibc lacks. + // What the runner's process supplies that libc may not + // (arc4random_buf), and prctl, which Swift can't call. .target(name: "CLinuxHost"), .target( name: "LinuxHostApp", dependencies: ["LinuxHost", "LinuxUI", "LinuxBluetooth", "LinuxGraphics", "LinuxWebKit", "LinuxCoreModel", "CLinuxHost", runtime("CRuntime"), runtime("RuntimeFormatting"), - .product(name: "CacaoSDL", package: "Cacao")], + runtime("DynamicGraphics"), .product(name: "CacaoSDL", package: "Cacao")], swiftSettings: host ), .executableTarget( name: "LinuxAppHost", dependencies: ["LinuxHostApp"], - swiftSettings: host + (appLibrary != nil ? [.define("APP_LINKED")] : []), - // The app's own `gl*` calls are libGLESv2's; it's needed only if - // it makes them. - linkerSettings: appLibrary.map { - [.unsafeFlags([$0, "-Xlinker", "--push-state", "-Xlinker", "--as-needed", "-lGLESv2", "-Xlinker", "--pop-state"])] - } ?? [] + exclude: ["exports.list"], + swiftSettings: host, + // The runner exports rt.h's functions for the app's libapp.so, + // and the linker keeps them though nothing here calls them. + linkerSettings: [ + .unsafeFlags(["-Xlinker", "--dynamic-list=\(Context.packageDirectory)/Sources/LinuxAppHost/exports.list"], + .when(platforms: [.linux])), + ] ), // MARK: - Packager @@ -199,7 +195,8 @@ let package = Package( // MARK: - Tests - .testTarget(name: "LinuxHostTests", dependencies: ["LinuxHost", runtime("DynamicFiles")], swiftSettings: host), + .testTarget(name: "LinuxHostTests", dependencies: ["LinuxHost", runtime("DynamicFiles"), .product(name: "Crypto", package: "swift-crypto")], + swiftSettings: host), .testTarget( name: "LinuxUITests", dependencies: ["LinuxUI", runtime("DynamicUI"), runtime("DynamicRuntime"), .product(name: "Cacao", package: "Cacao")] + swiftUI, From 678a2fb6b71cc7327dc68478a3375c283057aba7 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:44 -0500 Subject: [PATCH 22/36] Tested loading and refusing apps' libraries --- Tests/LinuxHostTests/AppLibraryTests.swift | 146 +++++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 Tests/LinuxHostTests/AppLibraryTests.swift diff --git a/Tests/LinuxHostTests/AppLibraryTests.swift b/Tests/LinuxHostTests/AppLibraryTests.swift new file mode 100644 index 0000000..6d21f07 --- /dev/null +++ b/Tests/LinuxHostTests/AppLibraryTests.swift @@ -0,0 +1,146 @@ +import Crypto +import Foundation +import RuntimeHost +import Testing +@testable import LinuxHost + +/// The runner's loader: libraries compiled here with the toolchain's clang, +/// as a slice's `libapp.so` would be, in signed bundles. +@Suite struct AppLibraryTests { + + static var compiler: String? { + ["/usr/bin/clang", "/usr/local/bin/clang"].first { FileManager.default.isExecutableFile(atPath: $0) } + } + + static var canLoad: Bool { + #if os(Linux) + compiler != nil && LinuxTarget.native != nil + #else + false + #endif + } + + /// A bundle whose library is `source`, compiled for this machine, and + /// signed unless `signed` is false. + func bundle(_ source: String, signed: Bool = true, flags: [String] = []) throws -> (path: String, target: LinuxTarget) { + let target = try #require(LinuxTarget.native) + let bundle = FileManager.default.temporaryDirectory.appendingPathComponent("app-\(UUID().uuidString)/App.app") + let lib = bundle.appendingPathComponent("lib/\(target.rawValue)") + try FileManager.default.createDirectory(at: lib, withIntermediateDirectories: true) + let c = bundle.deletingLastPathComponent().appendingPathComponent("app.c") + try source.write(to: c, atomically: true, encoding: .utf8) + let process = Process() + process.executableURL = URL(fileURLWithPath: try #require(Self.compiler)) + process.arguments = ["-shared", "-fPIC", "-nostdlib", "-Wl,-z,now", "-o", lib.appendingPathComponent("libapp.so").path, c.path] + flags + try process.run() + process.waitUntilExit() + try #require(process.terminationStatus == 0) + if signed { + try sign(bundle) + } + return (bundle.path, target) + } + + func sign(_ bundle: URL) throws { + var files: [String: Data] = [:] + let enumerator = try #require(FileManager.default.enumerator(atPath: bundle.path)) + for case let path as String in enumerator where !path.hasPrefix("_CodeSignature") { + var isDirectory: ObjCBool = false + FileManager.default.fileExists(atPath: bundle.appendingPathComponent(path).path, isDirectory: &isDirectory) + if !isDirectory.boolValue { + files[path] = Data(SHA256.hash(data: try Data(contentsOf: bundle.appendingPathComponent(path)))) + } + } + let signature = bundle.appendingPathComponent("_CodeSignature") + try FileManager.default.createDirectory(at: signature, withIntermediateDirectories: true) + try PropertyListSerialization.data(fromPropertyList: ["files": files], format: .xml, options: 0) + .write(to: signature.appendingPathComponent("CodeResources")) + } + + /// The three guest exports, and `rt_main` answering `status`. + func app(status: Int32 = 0, body: String = "") -> String { + """ + #include + \(body) + int32_t rt_main(void) { return \(status); } + int32_t rt_dispatch(uint32_t context, uint32_t index, uint32_t self, const uint64_t *args, uint32_t nargs, + uint64_t *ret, uint32_t nret) { return 0; } + void rt_finalize(uint32_t context) { } + """ + } + + @Test(.enabled(if: AppLibraryTests.canLoad)) func loadsTheSliceAndFindsItsExports() throws { + let (bundle, target) = try bundle(app(status: 7)) + let library = try AppLibrary.load(bundle: bundle, target: target) + #expect(library.path == bundle + "/lib/\(target.rawValue)/libapp.so") + #expect(library.entryPoints.main().rawValue == 7) + } + + @Test(.enabled(if: AppLibraryTests.canLoad)) func refusesALibraryItsSignatureDoesNotList() throws { + let unsigned = try bundle(app(), signed: false) + #expect(loadError(unsigned) == "the app isn't signed: it has no _CodeSignature/CodeResources") + + // Changed after it was signed. + let (path, target) = try bundle(app()) + try Data("not the library".utf8).write(to: URL(fileURLWithPath: path + "/" + target.sharedLibrary)) + #expect(loadError((path, target)) == "\(target.sharedLibrary) doesn't match the bundle's CodeResources") + + // Signed without it. + let other = try bundle(app()) + let manifest = URL(fileURLWithPath: other.path + "/_CodeSignature/CodeResources") + try PropertyListSerialization.data(fromPropertyList: ["files": [String: Data]()], format: .xml, options: 0).write(to: manifest) + #expect(loadError(other) == "_CodeSignature/CodeResources doesn't list \(other.target.sharedLibrary)") + } + + /// The library binds every symbol as it loads, so one the process + /// lacks fails the launch, by name. + @Test(.enabled(if: AppLibraryTests.canLoad)) func namesWhatTheProcessLacks() throws { + let missing = try bundle(app(body: """ + extern int32_t rt_not_in_this_runner(void); + int32_t rt_uses(void) { return rt_not_in_this_runner(); } + """)) + let error = try #require(loadError(missing)) + #expect(error.hasPrefix("can't load \(missing.target.sharedLibrary):")) + #expect(error.contains("rt_not_in_this_runner")) + } + + @Test(.enabled(if: AppLibraryTests.canLoad)) func preloadsWhatTheAppDraws() throws { + let (bundle, target) = try bundle(app()) + #expect(throws: AppLibraryError.self) { + try AppLibrary.load(bundle: bundle, target: target, preload: ["libnot-installed.so.9"]) + } + // The C library is always there to preload. + #expect(throws: Never.self) { + try AppLibrary.load(bundle: bundle, target: target, preload: ["libc.so.6"]) + } + } + + @Test(.enabled(if: AppLibraryTests.canLoad)) func aMissingSlice() throws { + let (bundle, target) = try bundle(app()) + let other = LinuxTarget.allCases.first { $0 != target }! + let error = try #require(loadError((bundle, other))) + #expect(error.contains("_CodeSignature/CodeResources doesn't list \(other.sharedLibrary)")) + } + + func loadError(_ bundle: (path: String, target: LinuxTarget)) -> String? { + do { + _ = try AppLibrary.load(bundle: bundle.path, target: bundle.target) + return nil + } catch { + return error.description + } + } + + // MARK: Finding installed apps + + @Test func prefixes() { + #expect(InstalledApps.prefixes(environment: ["HOME": "/home/ada"], runner: "/opt/rt/bin/linux-app-host") + == ["/home/ada/.local", "/opt/rt", "/usr/local", "/usr"]) + #expect(InstalledApps.prefixes(environment: ["HOME": "/home/ada"], runner: "/usr/bin/linux-app-host") + == ["/home/ada/.local", "/usr", "/usr/local"]) + #expect(InstalledApps.prefixes(environment: ["LINUXAPPRUNTIME_PREFIXES": "/a:/b", "HOME": "/home/ada"], runner: nil) == ["/a", "/b"]) + #expect(InstalledApps.bundle(identifier: "org.example.App", prefix: "/usr") == "/usr/lib/linux-app/org.example.App.app") + #expect(InstalledApps.isIdentifier("org.example.App")) + #expect(!InstalledApps.isIdentifier("nodots") && !InstalledApps.isIdentifier("../x.y") && !InstalledApps.isIdentifier("a..b")) + } +} From 3c4fea99f4d5997b57c951b6d3a52d26bee27b0f Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:44 -0500 Subject: [PATCH 23/36] Gave the test bundles libapp.so slices --- Tests/LinuxPackagerTests/Fixtures.swift | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/Tests/LinuxPackagerTests/Fixtures.swift b/Tests/LinuxPackagerTests/Fixtures.swift index b1d56d1..b390186 100644 --- a/Tests/LinuxPackagerTests/Fixtures.swift +++ b/Tests/LinuxPackagerTests/Fixtures.swift @@ -14,6 +14,7 @@ struct Fixture { contracts: [(name: String, version: Int, kind: String)] = [("org.pureswift.ui.Renderer", 1, "contract")], capabilities: [String] = [], machine: UInt16 = LinuxTarget.arm64.elfMachine, + elfType: UInt16 = 3, targets: [LinuxTarget] = [.arm64, .x86_64], wasm: Bool = true, signed: Bool = true @@ -37,7 +38,10 @@ struct Fixture { let directory = url.appendingPathComponent("lib/\(target.rawValue)") try files.createDirectory(at: directory, withIntermediateDirectories: true) let elfMachine = target == .arm64 ? machine : target.elfMachine - try Data(Self.archive([("/", [0, 0, 0, 0]), ("app.o/", Self.elf(machine: elfMachine))])) + // What a runner loads, and the archive bundles still carry. + try Data(Self.elf(machine: elfMachine, type: target == .arm64 ? elfType : 3, is64: target != .armv7)) + .write(to: directory.appendingPathComponent("libapp.so")) + try Data(Self.archive([("/", [0, 0, 0, 0]), ("app.o/", Self.elf(machine: elfMachine, type: 1))])) .write(to: directory.appendingPathComponent("libapp.a")) } if wasm { @@ -70,12 +74,15 @@ struct Fixture { get throws { try UniversalBundle(url: url) } } - /// A minimal ELF header with `e_machine`. - static func elf(machine: UInt16) -> [UInt8] { + /// A minimal ELF header: `e_machine`, `e_type` (3 a shared library, 1 + /// an object) and its class. + static func elf(machine: UInt16, type: UInt16 = 3, is64: Bool = true) -> [UInt8] { var header = [UInt8](repeating: 0, count: 64) header[0...3] = [0x7F, 0x45, 0x4C, 0x46] - header[4] = 2 + header[4] = is64 ? 2 : 1 header[5] = 1 + header[16] = UInt8(type & 0xFF) + header[17] = UInt8(type >> 8) header[18] = UInt8(machine & 0xFF) header[19] = UInt8(machine >> 8) return header From 06e07a8d858dce8418e808e54588561bf555b644 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:44 -0500 Subject: [PATCH 24/36] Tested thinning, installing for the runner and validating libapp.so --- Tests/LinuxPackagerTests/PackagerTests.swift | 114 ++++++++++--------- 1 file changed, 63 insertions(+), 51 deletions(-) diff --git a/Tests/LinuxPackagerTests/PackagerTests.swift b/Tests/LinuxPackagerTests/PackagerTests.swift index 96147c0..129d31e 100644 --- a/Tests/LinuxPackagerTests/PackagerTests.swift +++ b/Tests/LinuxPackagerTests/PackagerTests.swift @@ -5,9 +5,8 @@ import Testing @Suite struct ValidatorTests { - func diagnostics(_ fixture: Fixture, target: LinuxTarget = .arm64, engine: Engine = .slice, - allowMissing: Bool = false) throws -> [Diagnostic] { - var validator = Validator(bundle: try fixture.bundle, target: target, engine: engine) + func diagnostics(_ fixture: Fixture, target: LinuxTarget = .arm64, allowMissing: Bool = false) throws -> [Diagnostic] { + var validator = Validator(bundle: try fixture.bundle, target: target) validator.allowMissingContracts = allowMissing return validator.validate() } @@ -26,7 +25,7 @@ import Testing @Test func aGoodBundlePasses() throws { #expect(try diagnostics(Fixture()).isEmpty) - #expect(try diagnostics(Fixture(), engine: .wasm2c).isEmpty) + #expect(try diagnostics(Fixture(), target: .x86_64).isEmpty) } @Test func contractsThisHostLacks() throws { @@ -75,16 +74,21 @@ import Testing "resources/extra.txt was added", ]) #expect(try diagnostics(fixture).filter { $0.severity == .error }.count == 3) - #expect(try Fixture(signed: false).bundle.codeResourceProblems().isEmpty, "unsigned bundles aren't checked") + // The runner checks the library against the signature, so there + // must be one. + #expect(try diagnostics(Fixture(signed: false)).map(\.message) + == ["the bundle isn't signed: it has no _CodeSignature/CodeResources, which the runner checks its library against"]) } @Test func slicesMustBeForTheTarget() throws { let wrong = try diagnostics(Fixture(machine: LinuxTarget.x86_64.elfMachine)) - #expect(wrong.map(\.message) == ["linux-arm64 slice: objects are for ELF machine [62], not 183 (aarch64)"]) - let missing = try Fixture(targets: []) - #expect(try diagnostics(missing).map(\.message) == ["the bundle has no linux-arm64 slice; use --engine wasm2c"]) - #expect(Engine.preferred(for: try missing.bundle, target: .arm64) == .wasm2c) - #expect(try diagnostics(Fixture(targets: [], wasm: false), engine: .wasm2c).map(\.message) == ["the bundle has no wasm32/App.wasm"]) + #expect(wrong.map(\.message) == ["linux-arm64 slice: it's for ELF machine 62, not 183 (aarch64)"]) + let object = try diagnostics(Fixture(elfType: 1)) + #expect(object.map(\.message) == ["linux-arm64 slice: it isn't a shared library (ELF type 1)"]) + let bits = try diagnostics(Fixture(), target: .armv7) + #expect(bits.map(\.message) == ["the bundle has no linux-armv7 slice (lib/linux-armv7/libapp.so)"]) + #expect(try diagnostics(Fixture(targets: [.armv7]), target: .armv7).isEmpty) + #expect(try diagnostics(Fixture(targets: [])).map(\.message) == ["the bundle has no linux-arm64 slice (lib/linux-arm64/libapp.so)"]) } @Test func capabilitiesWithoutSupportWarn() throws { @@ -92,14 +96,6 @@ import Testing #expect(messages == [.warning("the app declares location, which the Linux host doesn't support yet")]) } - @Test func archivesAreParsed() throws { - let archive = Fixture.archive([("/", [0, 0, 0, 0]), ("a.o/", Fixture.elf(machine: 62) + [1]), ("b.o/", Fixture.elf(machine: 183))]) - #expect(try SliceInspector.elfMachines(archive) == [62, 183], "odd members are padded") - #expect(throws: PackagerError.self) { - try SliceInspector.elfMachines(Array("not an archive".utf8)) - } - } - @Test func theHostAndThePackagerAgreeOnModules() { var host: [String] = [] for module in HostApp.modules { @@ -115,68 +111,86 @@ import Testing @Suite struct PackagerTests { - func packager(_ fixture: Fixture, runner: FakeRunner) throws -> Packager { - var options = Packager.Options(target: .arm64, engine: .slice, hostPackage: URL(fileURLWithPath: "/src"), - workRoot: FileManager.default.temporaryDirectory.appendingPathComponent("work-\(UUID().uuidString)")) - options.configuration = "debug" + func packager(_ fixture: Fixture, runner: FakeRunner = FakeRunner(), output: URL? = nil) throws -> Packager { + var options = Packager.Options(target: .arm64) + options.output = output ?? FileManager.default.temporaryDirectory.appendingPathComponent("tree-\(UUID().uuidString)") return Packager(bundle: try fixture.bundle, options: options, runner: runner) } - @Test func writesTheInstallTree() throws { + @Test func thinsTheBundleAndBuildsNothing() throws { let fixture = try Fixture() let runner = FakeRunner() let result = try packager(fixture, runner: runner).package() let root = result.root let files = FileManager.default - #expect(try files.destinationOfSymbolicLink(atPath: root.appendingPathComponent("bin/Demo").path) == "../lib/org.example.Demo/Demo") - let program = root.appendingPathComponent("lib/org.example.Demo/Demo").path - #expect((try files.attributesOfItem(atPath: program)[.posixPermissions] as? Int) == 0o755) - let app = root.appendingPathComponent("lib/org.example.Demo/App.app") - #expect(try files.contentsOfDirectory(atPath: app.path).sorted() == ["Info.plist", "icon.png", "resources"]) + let app = root.appendingPathComponent("lib/linux-app/org.example.Demo.app") + #expect(result.bundle.path == app.path) + #expect(try files.contentsOfDirectory(atPath: app.path).sorted() + == ["Info.plist", "_CodeSignature", "icon.png", "lib", "resources"]) + #expect(try files.contentsOfDirectory(atPath: app.appendingPathComponent("lib").path) == ["linux-arm64"]) + #expect(try files.contentsOfDirectory(atPath: app.appendingPathComponent("lib/linux-arm64").path) == ["libapp.so"]) #expect(files.fileExists(atPath: root.appendingPathComponent("share/icons/hicolor/256x256/apps/org.example.Demo.png").path)) + #expect(!files.fileExists(atPath: root.appendingPathComponent("bin").path), "no program of its own") let entry = try String(contentsOf: root.appendingPathComponent("share/applications/org.example.Demo.desktop"), encoding: .utf8) - #expect(entry.contains("Exec=Demo %u\n")) + #expect(entry.contains("Exec=linux-app-host org.example.Demo %u\n")) #expect(entry.contains("Name=Demo App\n")) + #expect(runner.commands.isEmpty, "nothing compiled or linked") - // The build: a generated package for the app's library. - let build = try #require(runner.commands.first) - #expect(build.starts(with: ["swift", "build", "--package-path"])) - #expect(build.contains("--static-swift-stdlib"), "Swift is linked in") - #expect(build[build.firstIndex(of: "--product")! + 1] == HostPackage.product) - let manifest = try String(contentsOf: URL(fileURLWithPath: build[3]).appendingPathComponent("Package.swift"), encoding: .utf8) - #expect(manifest.contains(#".package(name: "LinuxAppRuntime", path: "/src")"#)) - #expect(manifest.contains("/lib/libapp-"), "a copy named for its contents, so a new library relinks") + // The thinned bundle still matches its signature, for what it kept. + let thinned = try UniversalBundle(url: app) + #expect(thinned.codeResourceProblems().allSatisfy { $0.hasSuffix("is missing") }) + let digest = try AppLibrary.signedDigest(bundle: app.path, file: "lib/linux-arm64/libapp.so") + #expect(digest.count == 32) - // Packaging again replaces the tree. - _ = try packager(fixture, runner: runner).package() + // Packaging again replaces it. + _ = try packager(fixture, output: root).package() + #expect(!files.fileExists(atPath: app.deletingLastPathComponent().appendingPathComponent(".org.example.Demo.app.new").path)) } - @Test func installsWithAnAbsolutePath() throws { + @Test func installsForTheRunner() throws { let fixture = try Fixture() let prefix = FileManager.default.temporaryDirectory.appendingPathComponent("prefix with space-\(UUID().uuidString)") - let result = try packager(fixture, runner: FakeRunner()).install(prefix: prefix) - #expect(result.executable.path == prefix.appendingPathComponent("bin/Demo").path) + let runner = URL(fileURLWithPath: "/opt/linux app/bin/linux-app-host") + let result = try packager(fixture).install(prefix: prefix, runner: runner) + #expect(result.bundle.path == InstalledApps.bundle(identifier: "org.example.Demo", prefix: prefix.path)) let entry = try String(contentsOf: prefix.appendingPathComponent("share/applications/org.example.Demo.desktop"), encoding: .utf8) - #expect(entry.contains("Exec=\"\(prefix.path)/bin/Demo\" %u")) + #expect(entry.contains("Exec=\"/opt/linux app/bin/linux-app-host\" org.example.Demo %u")) + // The runner finds it by its identifier. + #expect(InstalledApps.find(identifier: "org.example.Demo", prefixes: ["/nonexistent", prefix.path]) == result.bundle.path) + #expect(InstalledApps.find(identifier: "org.example.Other", prefixes: [prefix.path]) == nil) + #expect(InstalledApps.find(identifier: "../etc", prefixes: [prefix.path]) == nil) } @Test func refusesInvalidBundles() throws { let fixture = try Fixture(contracts: [("org.example.Missing", 1, "contract")]) - let runner = FakeRunner() + let output = FileManager.default.temporaryDirectory.appendingPathComponent("refused-\(UUID().uuidString)") #expect(throws: PackagerError.self) { - try packager(fixture, runner: runner).package() + try packager(fixture, output: output).package() } - #expect(runner.commands.isEmpty) + #expect(!FileManager.default.fileExists(atPath: output.path)) } @Test func archives() throws { - var packager = try packager(Fixture(), runner: FakeRunner()) + var packager = try packager(Fixture()) packager.options.archive = true let result = try packager.package() #expect(result.archive?.lastPathComponent == "org.example.Demo-1.2-linux-arm64.tar.gz") } + @Test func findsTheRunner() throws { + let directory = FileManager.default.temporaryDirectory.appendingPathComponent("runner-\(UUID().uuidString)") + try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true) + let program = directory.appendingPathComponent("linux-app-host") + try Data("#!/bin/sh\n".utf8).write(to: program) + try FileManager.default.setAttributes([.posixPermissions: 0o755], ofItemAtPath: program.path) + #expect(try Runner.locate(nil, environment: ["PATH": "/nonexistent:\(directory.path)"], tool: nil) == program) + #expect(try Runner.locate(nil, environment: [:], tool: directory.appendingPathComponent("linux-app").path) == program) + #expect(throws: PackagerError.self) { + try Runner.locate(nil, environment: ["PATH": "/nonexistent"], tool: nil) + } + } + @Test func desktopEntriesNameTheAppInEachLanguage() throws { let fixture = try Fixture(signed: false) let plist = fixture.url.appendingPathComponent("Info.plist") @@ -194,6 +208,8 @@ import Testing var entry = DesktopEntry(identifier: "a.b", name: "Demo", exec: "demo", version: "1") entry.localizedNames = bundle.localizedDisplayNames #expect(entry.text.contains("Name=Demo\nName[pt_BR]=Demonstração\nName[zh_CN]=演示\nExec=demo %u\n")) + let runner = DesktopEntry(identifier: "a.b", name: "Demo", exec: "/usr/bin/linux-app-host", arguments: ["a.b"], version: "1") + #expect(runner.text.contains("Exec=/usr/bin/linux-app-host a.b %u\n")) } @Test func desktopEntriesEscape() { @@ -203,10 +219,6 @@ import Testing #expect(DesktopEntry.quote("/a/$HOME") == "\"/a/\\\\$HOME\"", "escaped inside quotes, then as a string") } - @Test func swiftLiterals() { - #expect(literal("a\"b\\c\n") == #""a\"b\\c\n""#) - } - @Test func targets() { #expect(LinuxTarget.target(machine: "aarch64") == .arm64) #expect(LinuxTarget.target(machine: "x86_64") == .x86_64) From d4aaa3264893d94cd30dbe8a2655e493bbaa5a89 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:44 -0500 Subject: [PATCH 25/36] Tested that a port carries each architecture's libapp.so --- Tests/LinuxPackagerTests/PortMasterTests.swift | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/Tests/LinuxPackagerTests/PortMasterTests.swift b/Tests/LinuxPackagerTests/PortMasterTests.swift index 9919170..d59e5f1 100644 --- a/Tests/LinuxPackagerTests/PortMasterTests.swift +++ b/Tests/LinuxPackagerTests/PortMasterTests.swift @@ -4,9 +4,8 @@ import Testing @Suite struct PortMasterTests { - func port(_ fixture: Fixture, output: URL, libraries: URL? = nil) throws -> PortMasterPort { - var options = Packager.Options(target: .arm64, engine: .slice, hostPackage: URL(fileURLWithPath: "/src")) - options.workRoot = output.appendingPathComponent("work") + func port(_ fixture: Fixture, output: URL, libraries: URL? = nil, target: LinuxTarget = .arm64) throws -> PortMasterPort { + let options = Packager.Options(target: target) var portOptions = PortMasterPort.Options(output: output) portOptions.libraries = libraries portOptions.fonts = nil @@ -38,17 +37,20 @@ import Testing let binary = try temporary("bin").appendingPathComponent("host") try Data("#!/bin/sh\n".utf8).write(to: binary) - let port = try port(Fixture(), output: output, libraries: libraries) - _ = try port.assemble(binary: binary, architecture: "aarch64") - let result = try port.assemble(binary: binary, architecture: "armhf") + let fixture = try Fixture(targets: [.arm64, .armv7]) + _ = try port(fixture, output: output, libraries: libraries, target: .arm64).assemble(binary: binary, architecture: "aarch64") + let result = try port(fixture, output: output, libraries: libraries, target: .armv7).assemble(binary: binary, architecture: "armhf") let files = FileManager.default let game = result.directory.appendingPathComponent("demo") for path in ["Demo.aarch64", "Demo.armhf", "libs.aarch64/libSDL3.so.0", "libs.armhf/libSDL3.so.0", - "App.app/Info.plist", "demo.gptk", "licenses/SDL3.txt"] { + "App.app/Info.plist", "App.app/_CodeSignature/CodeResources", "demo.gptk", "licenses/SDL3.txt"] { #expect(files.fileExists(atPath: game.appendingPathComponent(path).path), "\(path)") } - #expect(!files.fileExists(atPath: game.appendingPathComponent("App.app/lib").path)) + // Each architecture's library, and no archive or wasm. + #expect(try files.contentsOfDirectory(atPath: game.appendingPathComponent("App.app/lib").path).sorted() == ["linux-arm64", "linux-armv7"]) + #expect(try files.contentsOfDirectory(atPath: game.appendingPathComponent("App.app/lib/linux-armv7").path) == ["libapp.so"]) + #expect(!files.fileExists(atPath: game.appendingPathComponent("App.app/wasm32").path)) #expect((try files.attributesOfItem(atPath: game.appendingPathComponent("Demo.armhf").path)[.posixPermissions] as? Int) == 0o755) let json = try #require(try JSONSerialization.jsonObject(with: Data(contentsOf: result.directory.appendingPathComponent("port.json"))) as? [String: Any]) From 45c8c122abb5ab5ce0189c7296a10816b36067e4 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:44 -0500 Subject: [PATCH 26/36] Ran bundles in the runner --- Scripts/run-app.sh | 22 +++++++++------------- 1 file changed, 9 insertions(+), 13 deletions(-) diff --git a/Scripts/run-app.sh b/Scripts/run-app.sh index 47db391..2b14913 100755 --- a/Scripts/run-app.sh +++ b/Scripts/run-app.sh @@ -1,21 +1,17 @@ #!/bin/sh -# Builds linux-app-host linked with a universal bundle's Linux slice and runs -# it in the development image, headless (SDL's offscreen driver), saving its -# first frame to SCREENSHOT (inside this checkout) and quitting; with +# Runs a universal bundle in the runner, linux-app-host, in the development +# image, headless (SDL's offscreen driver), saving its first frame to +# SCREENSHOT (inside this checkout) and quitting; with # CACAO_SCREENSHOT_DELAY=seconds, the first after that, as for a GL surface, -# whose frames come after the window's first. The bundle -# must be inside this checkout, such as .build/guest/.app from -# AppRuntime's `guest.py bundle --target linux-arm64 --output .build/guest`. +# whose frames come after the window's first. The runner loads the bundle's +# libapp.so for this machine. The bundle must be inside this checkout, such +# as .build/guest/.app from AppRuntime's +# `guest.py bundle --target linux-arm64 --output .build/guest`. # # Scripts/run-app.sh .build/guest/org.pureswift.ExampleUI.app .build/shots/ExampleUI.png set -e bundle=${1:?usage: Scripts/run-app.sh BUNDLE SCREENSHOT [linux-app-host arguments]} screenshot=${2:?usage: Scripts/run-app.sh BUNDLE SCREENSHOT [linux-app-host arguments]} shift 2 -case "$(uname -m)" in - arm64 | aarch64) target=linux-arm64 ;; - *) target=linux-x86_64 ;; -esac -library="/src/$bundle/lib/$target/libapp.a" -LINUXAPPRUNTIME_APP_LIBRARY=$library exec "$(dirname "$0")/docker.sh" \ - "swift build --scratch-path .build/linux --product linux-app-host && CACAO_SCREENSHOT=/src/$screenshot .build/linux/debug/linux-app-host --bundle /src/$bundle $*" +exec "$(dirname "$0")/docker.sh" \ + "swift build --scratch-path .build/linux-trixie --product linux-app-host && CACAO_SCREENSHOT=/src/$screenshot .build/linux-trixie/debug/linux-app-host --bundle /src/$bundle $*" From b138f1faba361ced6512dc5c6b999288dc022a5c Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:44 -0500 Subject: [PATCH 27/36] Stopped passing an app library to builds --- Scripts/docker.sh | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/Scripts/docker.sh b/Scripts/docker.sh index 719a0dd..8d79f85 100755 --- a/Scripts/docker.sh +++ b/Scripts/docker.sh @@ -7,8 +7,7 @@ # Scripts/docker.sh swift test --scratch-path .build/linux # APPRUNTIME_PATH=~/Developer/AppRuntime Scripts/docker.sh swift build --scratch-path .build/linux # -# LINUXAPPRUNTIME_APP_LIBRARY, a path inside the container, and -# CACAO_SCREENSHOT_DELAY are passed through. WebKit's web processes run +# CACAO_SCREENSHOT_DELAY is passed through. WebKit's web processes run # without their bubblewrap sandbox, which can't make namespaces in a # container. set -e @@ -30,6 +29,6 @@ fi exec docker run --rm \ -v "$root:/src" -w /src \ -v linuxappruntime-swiftpm:/root/.cache \ - -e LINUXAPPRUNTIME_APP_LIBRARY -e CACAO_SCREENSHOT_DELAY \ + -e CACAO_SCREENSHOT_DELAY \ -e WEBKIT_DISABLE_SANDBOX_THIS_IS_DANGEROUS=1 \ "$@" "$image" bash -c "$command" From 84d833f1719592afbcc8f0951b02c9e5b0884158 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:44 -0500 Subject: [PATCH 28/36] Said WABT is for AppRuntime's wasm2c shim --- Dockerfile | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Dockerfile b/Dockerfile index ef03e69..f1ff239 100644 --- a/Dockerfile +++ b/Dockerfile @@ -2,8 +2,7 @@ # Debian 13, SDL3, Cairo, FreeType, fontconfig and Wayland for Cacao, a font, # Mesa's EGL and GLES 2.0 for GL surfaces (llvmpipe without a GPU), WPE WebKit # and its FreeDesktop.org backend for web views, which the host loads at run -# time, Python for AppRuntime's scripts, and WABT for the packager's wasm2c -# engine. +# time, Python for AppRuntime's scripts, and WABT for its wasm2c shim. # # Debian rather than Ubuntu: Ubuntu 26.04 doesn't package WPE WebKit. SDL is # built from source: Debian's is 3.2, and PureSwift/SDL needs 3.4. From ad0aacf9f86125362b82bfc439784f999796219d Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:44 -0500 Subject: [PATCH 29/36] Documented the runner --- Documentation/Plan.md | 105 ++++++++++++++++++++++++++++++------------ 1 file changed, 76 insertions(+), 29 deletions(-) diff --git a/Documentation/Plan.md b/Documentation/Plan.md index 96ea49e..f85d89b 100644 --- a/Documentation/Plan.md +++ b/Documentation/Plan.md @@ -10,6 +10,11 @@ design, [Packager.md](Packager.md), and so do PortMaster ports, - **PortMaster ports** don't build on Cacao yet: they need Cairo built for their glibc, and Cacao options for fullscreen, scale and a drawn pointer ([PortMaster.md](PortMaster.md) §7). +- **One runner for every app.** `linux-app-host` loads an app's + `libapp.so` (AppRuntime's §7.5, §7.6) instead of being built per app + with its `libapp.a` linked in, so installing an app copies files and + needs no toolchain, and the runner and the OS update on their own while + the app's ABI stays put (§4). - **Bluetooth** is tested against a fake bus that plays BlueZ's objects and signals; it hasn't run against `bluetoothd` and a device. - **AppRuntime's `guest.py bundle`** needed one fix to run on Linux: it @@ -19,12 +24,13 @@ design, [Packager.md](Packager.md), and so do PortMaster ports, The Linux host for [AppRuntime](https://github.com/PureSwift/AppRuntime) apps, the counterpart of DarwinAppRuntime. An AppRuntime app is guest code -only: a universal bundle with `App.wasm` and native `libapp.a` slices -(`linux-arm64`, `linux-x86_64`, `linux-armv7`). This repository turns one -into a Linux program: +only: a universal bundle with `App.wasm` and a native slice for each Linux +target (`linux-arm64`, `linux-x86_64`, `linux-armv7`), a `libapp.so`. This +repository runs one on Linux: -- the **host runtime**: `main`, the event loop, the runtime core behind - `rt.h`, and the contract implementations over Linux services; +- the **runner**, `linux-app-host`: `main`, the event loop, the runtime core + behind `rt.h`, and the contract implementations over Linux services, into + which it loads an app's `libapp.so`; - the **SwiftUI player**: DarwinAppRuntime's renderer of the SwiftUI frontend's render IR, on Cacao's SwiftUI for Linux; - **Bluetooth** over BlueZ's D-Bus API; @@ -44,14 +50,14 @@ AppRuntime's contracts. | In | Later | |---|---| | arm64 and x86_64 Linux with glibc (Debian 13, Ubuntu 24.04+) | armv7, musl | -| Native slices linked into the host | wasm2c (AppRuntime's shim, as on Darwin); WasmKit for development | +| Native slices, loaded by the runner | `App.wasm`, in an engine in the runner; wasm2c for a target a bundle lacks, before it's installed | | Wayland and X11 through SDL3; a headless driver for tests | Multiple windows | | `Renderer`, `BluetoothCentral` and friends, GL surfaces, web views, files, settings, model stores, date and number formatting, the built-ins | Location (GeoClue), Device (UPower, sysfs), Networking (libcurl), Motion (iio-sensor-proxy), NFC (neard) | ## 2. Process model ``` -┌────────────────────── app (one executable) ──────────────────────┐ +┌──────────────────── linux-app-host (the runner) ─────────────────┐ │ LinuxHostApp main │ │ ├── runtime core: RuntimeCore + RuntimeNative (rt_* symbols) │ │ ├── MainLoop: timers, jobs from other threads │ @@ -60,7 +66,7 @@ AppRuntime's contracts. │ ├── LinuxWebKit: WPE WebKit pages, frames in shared memory │ │ ├── LinuxUI: DarwinUI, render IR → SwiftUI views → events │ │ │ └── Cacao: SwiftUI, Silica/Cairo, SDL3 windows and input │ -│ └── libapp.a: the app's sealed linux-arm64 / linux-x86_64 slice│ +│ └── libapp.so: the app's slice, loaded from its bundle │ └──────────────────────────────────────────────────────────────────┘ ``` @@ -112,22 +118,56 @@ every host written in Swift; this host registers them as they are: ## 4. Startup -1. Read the app's keys (`RTABIVersion`, `RTContracts`, `RTCapabilities`, - `CFBundleIdentifier`, version and build) from the universal bundle's - `Info.plist`: the path from `--bundle`, or `App.app` next to the - executable. -2. Check the ABI and contract versions (§7.6); refuse a newer ABI or a - contract this host lacks. -3. `NativeRuntime.shared.bindDirectly()`; set capabilities; set the clock. -4. Register the built-ins (`Permissions`, `Bundle`, `Application`) and each - module the app uses (`LinuxUI` for `Renderer`, `LinuxBluetooth`, - `LinuxGraphics`, `LinuxWebKit`). -5. Call `rt_main`. When the guest calls `Renderer.make`, the player adds +`linux-app-host` is the one program every app runs in. No app is linked +into it: it loads the app's `libapp.so`, which names no other library and +leaves undefined only `rt.h`, a few libc functions and, for an app that +draws, GLES 2.0 (AppRuntime's §7.5). + +``` +linux-app-host [--bundle] App.app | IDENTIFIER [[--open] URL] +``` + +1. Find the app: a bundle's path, or an installed app's identifier, looked + up as `/lib/linux-app/.app` in `~/.local`, the + runner's own prefix, `/usr/local` and `/usr` (`LINUXAPPRUNTIME_PREFIXES` + replaces the list). Without one, `LINUXAPPRUNTIME_BUNDLE`, or `App.app` + next to the executable, as a PortMaster port has it. +2. Name the process after the app (`PR_SET_NAME`, `CFBundleExecutable`), + so `ps` and `top` show it and not the runner. +3. Read the app's keys from its `Info.plist` and check the ABI and contract + versions (§7.6), at every launch: the runner may have changed since the + app was installed. A newer ABI or a contract this host lacks refuses it. +4. `NativeRuntime.shared.bindDirectly()`; set capabilities; set the clock. + Register the built-ins (`Permissions`, `Bundle`, `Application`) and each + module the app uses. +5. Load the library (`AppLibrary`): + - check `lib//libapp.so` against the bundle's + `_CodeSignature/CodeResources`, and load the bytes checked: the file is + opened once, hashed, and loaded through its descriptor + (`/proc/self/fd`); + - for an app whose contracts include `Surface`, load + `libGLESv2.so.2` into the global scope first; + - `dlopen` it. It binds every symbol as it loads, so one the runner + lacks refuses the app, by name; + - look up `rt_main`, `rt_dispatch` and `rt_finalize`. +6. Call `rt_main`. When the guest calls `Renderer.make`, the player adds its scene; the first tree is there before `rt_main` returns. -6. Run Cacao's loop until the window closes, the window showing the first +7. Run Cacao's loop until the window closes, the window showing the first scene (or, for an app with no renderer, the `MainLoop` until it's interrupted). +What the runner's process supplies to the library: + +- **`rt.h`.** RuntimeNative defines its functions in Swift (`@c`). + `linux-app-host` is linked with a dynamic list + (`Sources/LinuxAppHost/exports.list`) that exports `rt_*`, which keeps + them though nothing in the runner calls them. +- **libc's part.** The library binds to the C library the runner runs on, + glibc or musl. Where it lacks `arc4random_buf` (musl, glibc before 2.36), + `CLinuxHost` defines it and the runner exports it; its executable is + searched first, so that's the definition the app binds to. +- **GLES 2.0**, loaded as above. + ## 5. The SwiftUI player The player is DarwinAppRuntime's: `DarwinUI`, its renderer of the render IR @@ -367,6 +407,11 @@ SQLite one, CoreModel-SQLite, with SQLite compiled in, so a device needs no contract end to end in a container, answering on the main loop. - `LinuxHost`'s settings: the file's path from the environment, and settings read again at the next launch. +- `LinuxHost`'s loader: libraries compiled by the test with the + toolchain's clang, in signed bundles: loaded, and their exports called; + refused unsigned, changed after signing, or not listed; a symbol the + process lacks named in the refusal; a library to preload that isn't + there. Where installed apps are found. - `LinuxCoreModel`: where stores are; about 500 requests answered as CoreModel's in-memory store answers them; every value there and back; batches applied whole or not at all; a store kept between launches, @@ -377,10 +422,13 @@ SQLite one, CoreModel-SQLite, with SQLite compiled in, so a device needs no resources, a refused connection, remote loads without `network`, frames and their pixels, a click, typing, and a resize. Every WebKit call is made on one thread, which WebKit takes for its main thread. -- End to end: AppRuntime's `ExampleUI` built as a `linux-arm64` slice, - linked into `linux-app-host` and run headless with SDL's `offscreen` - driver, its first frame saved with `CACAO_SCREENSHOT`. `ExampleModel` - the same way, launched twice on one container, with to-dos written into +- End to end: AppRuntime's `ExampleUI`, `ExampleGL` and `ExampleModel` + bundles, their `linux-arm64` `libapp.so` loaded by `linux-app-host` and + run headless with SDL's `offscreen` driver, each first frame saved with + `CACAO_SCREENSHOT`; `ExampleGL` with GLES loaded first. `ExampleModel` + installed with `linux-app install` and launched by its identifier, + shown by `ps` as `ExampleModel`, and refused once its library is + changed; and launched twice on one container, with to-dos written into its SQLite database between the launches: the second shows them. - Real BlueZ needs hardware: manual runs on a Raspberry Pi or a laptop with `bluetoothd`. @@ -389,11 +437,10 @@ SQLite one, CoreModel-SQLite, with SQLite compiled in, so a device needs no 1. **Host runtime and player**: `LinuxHost`, `LinuxUI`, `LinuxBluetooth`, `LinuxHostApp`; `ExampleUI` runs in Docker. -2. **Packager**: `linux-app` builds the host for a target triple, links the - bundle's slice (or wasm2c output), and writes an installable directory: - the executable, `Info.plist`, resources, a `.desktop` file and icon; - later Flatpak and AppImage, whose manifests carry the capabilities - (`--system-talk-name=org.bluez` for `bluetooth`). +2. **Packager**: `linux-app` checks an app and installs it: its bundle + thinned to the target's `libapp.so`, a `.desktop` file and icon, for + the runner; later Flatpak and AppImage, whose manifests carry the + capabilities (`--system-talk-name=org.bluez` for `bluetooth`). 3. **More contracts**: Location (GeoClue2), Device (UPower, sysfs), Networking (libcurl or AsyncHTTPClient), Motion (iio-sensor-proxy), NFC (neard). Formatting is done: AppRuntime's `RuntimeFormatting` From f8733bfd54ceca77dca3aee3a5fa21a405d6b582 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:44 -0500 Subject: [PATCH 30/36] Documented installing for the runner --- Documentation/Packager.md | 126 +++++++++++++++++++------------------- 1 file changed, 62 insertions(+), 64 deletions(-) diff --git a/Documentation/Packager.md b/Documentation/Packager.md index b4a9049..f13ae14 100644 --- a/Documentation/Packager.md +++ b/Documentation/Packager.md @@ -1,26 +1,31 @@ # Packager — Design -**Status:** implemented, except Flatpak, AppImage and cross-building (§5). -`ExampleUI` packages from its bundle with either engine, and the packaged -app runs. - -`linux-app` turns a universal bundle into a Linux app: phase 2 of the -[plan](Plan.md). It never compiles guest Swift. The bundle already has the -guest's code, as a sealed `libapp.a` per target and `App.wasm`, and its -`Info.plist` has the portable keys AppRuntime's manifest stage wrote -(DarwinAppRuntime's `ManifestPackager.md` §1). +**Status:** implemented, except Flatpak and AppImage (§5). `ExampleUI`, +`ExampleGL` and `ExampleModel` install from their bundles and run in the +runner. + +`linux-app` installs a universal bundle's app for the runner, +`linux-app-host` ([Plan.md](Plan.md) §4): phase 2 of the plan. It never +compiles or links anything. The bundle has the guest's code, as a +`libapp.so` per Linux target, which `guest.py` linked when it built the +bundle (AppRuntime's `DynamicRuntime.md` §7.5), and its `Info.plist` has +the portable keys AppRuntime's manifest stage wrote (DarwinAppRuntime's +`ManifestPackager.md` §1). So a device needs the runner, and no compiler, +linker or SwiftPM; the runner and the OS update on their own, and the app's +ABI is what stays put. ```sh linux-app validate App.app [--target linux-arm64] -linux-app package App.app [--target …] [--engine slice|wasm2c] [--output DIR] [--archive] -linux-app install App.app [--prefix ~/.local] -linux-app run App.app [-- host arguments] +linux-app package App.app [--target …] [--output DIR] [--archive] +linux-app install App.app [--prefix ~/.local] [--runner PATH] +linux-app run App.app [--runner PATH] [-- URL] ``` ## 1. Validation `validate`, and every other command first, checks the bundle against this -host: +host. The runner checks the ABI, the contracts and the library's signature +again at every launch, since it may have changed since. | Check | Failure | |---|---| @@ -28,80 +33,73 @@ host: | `RTABIVersion` ≤ the host's | error | | Each `RTContracts` entry is implemented here, as the same kind | error; `--allow-missing-contracts` makes it a warning, and the guest sees the contract as absent | | … at the same version or later | warning: methods added later resolve as absent | -| `_CodeSignature/CodeResources` matches every file's SHA-256 | error: a corrupt or tampered bundle | -| The engine's input: `lib//libapp.a` for `slice`, `wasm32/App.wasm` for `wasm2c` | error | -| The slice is an archive of ELF objects for the target's machine | error | +| The bundle has `_CodeSignature/CodeResources`, and it matches every file's SHA-256 | error: the runner loads no library its bundle doesn't vouch for | +| `lib//libapp.so` is there, and is a shared library for the target's machine and word size | error | | A declared capability this host has no contract for (location, motion, NFC, …) | warning | -## 2. Targets and engines +`guest.py` has checked the rest of the library when it built it: that it +names no other library, binds as it loads, exports the three guest exports +only, and leaves undefined only what a runner supplies. -The target is the build machine's (`linux-arm64` on aarch64, `linux-x86_64` -on x86_64); cross-building waits on Swift SDKs for Linux targets. +## 2. Targets -- **`slice`** (the default when the bundle has one) links the bundle's - `lib//libapp.a`. -- **`wasm2c`** (the default otherwise) runs AppRuntime's - `Scripts/wasm2c-shim.py build` on `App.wasm`, which needs WABT (`apt - install wabt`) and clang, and links its `libapp.a` the same way. - Ubuntu's `wabt` 1.0.36 leaves out two files its runtime source includes - (`wasm-rt-impl-tableops.inc`, `wasm-rt-mem-impl-helper.inc`); the - `Dockerfile` adds them from the same release. The - AppRuntime checkout comes from `--appruntime`, `APPRUNTIME_PATH`, or the - one SwiftPM resolved for the host build. +The target is this machine's (`linux-arm64` on aarch64, `linux-x86_64` on +x86_64, `linux-armv7` on armv7l), or `--target`'s. A bundle carries a +`libapp.so` for each target it was built for. -## 3. Building the host +There's no wasm2c engine: it needs a C compiler, which a device doesn't +have. A bundle without a slice for a target needs one made where there's +a toolchain, by AppRuntime's wasm2c shim, before it's installed; the shim +makes only a `libapp.a` so far. Running `App.wasm` itself is for an engine +in the runner. -As on Darwin, the host is built per app from a generated SwiftPM package in -the work directory (`.build/linux-app//`, reused -between builds): +## 3. The runner -``` -Package.swift an executable product, LinuxAppMain, depending on this - package's LinuxHostApp, linking the app's libapp.a; the - tree names its copy CFBundleExecutable -Sources//main.swift - HostApp.main(AppEntryPoints(main: rt_main, …)) -``` +Apps don't get a program of their own: every app runs in `linux-app-host`, +installed once (Plan.md §4). `install` and `run` find it from `--runner`, +`LINUXAPPRUNTIME_RUNNER`, beside `linux-app`, or on `PATH`. -`swift build -c release` (or `--configuration debug`) builds it. The app's library is copied in as `lib/libapp-.a`: SwiftPM -doesn't relink when a library named in linker flags changes, but a new name -changes the manifest. This -package is found from `--host-package`, `LINUXAPPRUNTIME_PATH`, or the -source tree `linux-app` was built from. +A PortMaster port is the exception: a handheld has no runner installed, so +the port carries one, built by `linux-app portmaster` for the handheld's +glibc ([PortMaster.md](PortMaster.md)). It's the same program for every +app. ## 4. The app -`package` writes an install tree under `--output` (default -`.build/linux-app///out`): +`install` writes the app into `--prefix` (`~/.local` by default): ``` -bin/ → ../lib// -lib// the host, linked with the app -lib//App.app/Info.plist the bundle, without lib/ and wasm32/ -lib//App.app/resources/… +lib/linux-app/.app/Info.plist the bundle, thinned: +lib/linux-app/.app/resources/… +lib/linux-app/.app/icon.png +lib/linux-app/.app/_CodeSignature/CodeResources +lib/linux-app/.app/lib//libapp.so this target's only share/applications/.desktop -share/icons/hicolor/256x256/apps/.png from the bundle's icon.png +share/icons/hicolor/256x256/apps/.png from the bundle's icon.png ``` -The host finds `App.app` next to its executable, through the `bin/` -symlink. `--archive` also writes `--.tar.gz` -of the tree. +Thinning drops the other targets' libraries, `libapp.a` and `App.wasm`. +The signature is kept as it was: every file still in the bundle matches it, +and the runner checks the library against it. The new copy is written +beside the old one and replaces it whole. -The desktop entry names the app (`CFBundleName`), runs it (`Exec`, with +The desktop entry names the app (`CFBundleName`), runs it +(`Exec= %u`, the runner by its absolute path, with `%u` so URLs reach `Application.open`), and matches its windows: the host sets SDL's app metadata, so the window's Wayland app ID and X11 class are -the identifier, which `StartupWMClass` repeats. +the identifier, which `StartupWMClass` repeats. `install` refreshes the +desktop database when `update-desktop-database` is there. -`install` packages and copies the tree into `--prefix` (`~/.local` by -default), with `Exec` an absolute path, and refreshes the desktop database -when `update-desktop-database` is there. `run` packages a debug build into -the work directory and runs it. +`package` writes the same tree to `--output` (default +`.build/linux-app//`) for a distribution's package, +with the runner named by `Exec` from `PATH`, and `--archive` also writes +`--.tar.gz` of it. `run` checks the bundle and +runs it in the runner as it is. ## 5. Later - **Flatpak and AppImage.** A Flatpak manifest carries the capabilities as sandbox permissions (`bluetooth` → `--system-talk-name=org.bluez`, `network` → `--share=network`). -- **Localized names** in the desktop entry, from the bundle's - `.lproj` tables. -- **Cross-building** for another architecture with a Swift SDK. +- **A read-only image** per app (squashfs), as AppRuntime's launcher + mounts them (§7.8 there). From 3ee8a36cc5e94772de34ba19807b3b4958e132fa Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:44 -0500 Subject: [PATCH 31/36] Documented ports carrying the runner --- Documentation/PortMaster.md | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/Documentation/PortMaster.md b/Documentation/PortMaster.md index 12beaa7..25c7488 100644 --- a/Documentation/PortMaster.md +++ b/Documentation/PortMaster.md @@ -19,16 +19,23 @@ gameinfo.xml EmulationStation metadata README.md notes and controls screenshot.png the screenshot: --screenshot, or the app's icon / - .aarch64 the host, linked with the app, per architecture - .armhf + .aarch64 the runner, linux-app-host, per architecture, + .armhf named after the app libs.aarch64/ SDL3 and SDL3_ttf, built for old glibc libs.armhf/ - App.app/ Info.plist and resources + App.app/ the bundle, thinned: Info.plist, resources, + its signature, and lib/linux-arm64/libapp.so + and lib/linux-armv7/libapp.so fonts/ DejaVu, for devices without fontconfig .gptk gptokeyb's mapping licenses/ ``` +A handheld has no runner installed, so the port carries its own: the same +program for every app, which loads `App.app/lib//libapp.so` +(Plan.md §4). It's named after the app, so that's what the device shows +running and what gptokeyb watches. + `` is the executable's name in lowercase. Packaging one architecture into a directory that has the other adds to it: `port.json`'s `arch` lists both, and `min_glibc` is the newer of the two. The zip, `.zip`, also @@ -86,14 +93,15 @@ two images `Scripts/portmaster.sh` uses: Swift is linked statically. The armhf build goes through SwiftPM's native build system, since the default one ignores destination files. Ubuntu -22.04's glibc has no `arc4random_buf`, which app slices call, so the host -supplies it there (`CLinuxHost`). fontconfig is loaded at run time if it's there; +22.04's glibc has no `arc4random_buf`, which an app's library calls, so +the runner defines and exports it there (`CLinuxHost`). fontconfig is loaded at run time if it's there; otherwise the host uses `fonts/`. The images say what they bundle (`LINUXAPPRUNTIME_PORT_LIBS`) and how to build (`LINUXAPPRUNTIME_SWIFT_SDK` for the armv7 SDK); `linux-app portmaster` reads both. -The guest side is unchanged: the bundle's `linux-arm64` and `linux-armv7` -slices are libc-agnostic, so they link into either host. +The runner is what's built. The app isn't: its `linux-arm64` and +`linux-armv7` `libapp.so` name no libc, so the same files load in a +handheld's runner and a desktop's. ## 5. Testing From 7902f75e825bfb2cdf44b7249ec968c2ff27e39b Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:57:44 -0500 Subject: [PATCH 32/36] Described the runner and installing apps for it --- README.md | 63 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 39 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 4760fc9..225dcbf 100644 --- a/README.md +++ b/README.md @@ -2,27 +2,29 @@ The Linux host for [AppRuntime](https://github.com/PureSwift/AppRuntime) apps. An AppRuntime app is guest code only: a universal bundle with -`App.wasm` and native `libapp.a` slices. This repository turns one into a -Linux program: +`App.wasm` and a `libapp.so` for each Linux target. This repository runs +one on Linux: -- the **host runtime**: `main`, a main loop for timers and D-Bus, the - runtime core behind `rt.h`, and the built-in contracts; +- the **runner**, `linux-app-host`: one program every app runs in, which + loads the app's `libapp.so`; `main`, a main loop for timers and D-Bus, + the runtime core behind `rt.h`, and the built-in contracts; - the **SwiftUI player**: DarwinAppRuntime's renderer of the SwiftUI frontend's render IR, on [Cacao](https://github.com/PureSwift/Cacao), SwiftUI for Linux; - **Bluetooth** LE central over BlueZ's D-Bus API; - **GL surfaces**: OpenGL ES 2.0 in a SwiftUI view, over EGL; - **web views**: WPE WebKit pages in a SwiftUI view; -- the **packager**, `linux-app`, which turns a universal bundle into an - installable app. +- the **packager**, `linux-app`, which installs an app for the runner by + copying files: its bundle thinned to this machine's `libapp.so`. Nothing + is compiled or linked, so a device needs the runner and no toolchain. **Status:** AppRuntime's `ExampleUI`, built as a `linux-arm64` slice, runs in the player on Cacao, headless under SDL's offscreen driver, and the player passes DarwinUI's own tests there. PortMaster ports don't build on Cacao yet ([PortMaster.md](Documentation/PortMaster.md) §7). The Bluetooth contracts are tested against a fake BlueZ and haven't run against real -hardware. `linux-app` packages `ExampleUI` from its bundle, as a slice or -through wasm2c, and the packaged app runs. See the +hardware. The runner loads `ExampleUI`, `ExampleGL` and `ExampleModel` +from their bundles, and `linux-app` installs them for it. See the [plan](Documentation/Plan.md) and the [packager](Documentation/Packager.md). ![ExampleUI on Linux](Documentation/ExampleUI.png) @@ -58,7 +60,7 @@ added to its database between launches: | `LinuxWebKit` | `WebContent`: WPE WebKit pages, loaded at run time, drawn into shared memory and shown by the player's `WebView` view ([plan](Documentation/Plan.md) §8) | | `LinuxCoreModel` | `LinuxModelStore`: the app's CoreModel stores in SQLite, through AppRuntime's `HostModelStore` and CoreModel-SQLite ([plan](Documentation/Plan.md) §9) | | `LinuxHostApp`, `linux-app-host` | The app's `main`: the host, and Cacao's window and loop. It also registers AppRuntime's `RuntimeFormatting`, dates and numbers over Swift Foundation ([plan](Documentation/Plan.md) §3) | -| `LinuxPackager`, `linux-app` | The packager: validation, the host build, wasm2c, the install tree, PortMaster ports | +| `LinuxPackager`, `linux-app` | The packager: validation, thinning a bundle to one target, the install tree, PortMaster ports | ## Building @@ -106,28 +108,39 @@ python3 ~/Developer/AppRuntime/Scripts/guest.py bundle --product ExampleUI \ --target linux-arm64 --output .build/guest ``` -Then, on Linux: +Then, on Linux, build the runner once: + +```sh +swift build --product linux-app-host --product linux-app +.build/debug/linux-app-host .build/guest/org.pureswift.ExampleUI.app +``` + +and install apps for it: ```sh -swift build --product linux-app .build/debug/linux-app validate .build/guest/org.pureswift.ExampleUI.app -.build/debug/linux-app package .build/guest/org.pureswift.ExampleUI.app --archive -.build/debug/linux-app install .build/guest/org.pureswift.ExampleUI.app -.build/debug/linux-app run .build/guest/org.pureswift.ExampleUI.app +.build/debug/linux-app install .build/guest/org.pureswift.ExampleUI.app --runner .build/debug/linux-app-host +.build/debug/linux-app-host org.pureswift.ExampleUI ``` -`package` writes an install tree (`bin/`, `lib//`, a desktop entry and -icon) and, with `--archive`, a tarball of it; `install` puts it in -`~/.local`. `--engine wasm2c` builds from `App.wasm` instead of a slice, -which needs WABT (`apt install wabt`). The packaged program takes: +`install` copies the bundle, thinned to `Info.plist`, `resources/`, the +icon, its signature and this machine's `libapp.so`, to +`~/.local/lib/linux-app/.app`, and writes a desktop entry that starts +the runner with the app's identifier. `package` writes the same tree +elsewhere for a distribution's package, and `--archive` a tarball of it; +`run` checks a bundle and runs it as it is. The runner takes: | Argument | | |---|---| -| `--open URL` | A URL for the app to open | -| `--bundle App.app` | Another bundle's keys; `App.app` next to the program by default | +| `App.app` or `--bundle App.app` | A bundle | +| An identifier | An installed app, found in `~/.local`, the runner's prefix, `/usr/local` or `/usr` (`LINUXAPPRUNTIME_PREFIXES`) | +| `--open URL`, or a URL after the app | A URL for the app to open | + +It checks the app's ABI and contracts at every launch, and its `libapp.so` +against the bundle's `CodeResources` before loading it. -`Scripts/run-app.sh` links a bundle's slice into `linux-app-host` and runs it -in Docker, headless, saving its first frame: +`Scripts/run-app.sh` runs a bundle in the runner in Docker, headless, +saving its first frame: ```sh mkdir -p .build/shots @@ -137,8 +150,10 @@ Scripts/run-app.sh .build/guest/org.pureswift.ExampleUI.app .build/shots/Example ## PortMaster `linux-app portmaster` makes a [PortMaster](https://portmaster.games) port -for aarch64 and armhf handhelds: the host built for their older glibc, SDL3 -built for them, a launcher, gamepad controls and the catalogue's metadata +for aarch64 and armhf handhelds: the runner built for their older glibc +and named after the app, the bundle thinned to its `libapp.so` for each +architecture, SDL3 built for them, a launcher, gamepad controls and the +catalogue's metadata ([design](Documentation/PortMaster.md)). Ports don't build on Cacao yet: their images need Cairo built for old glibc, and Cacao needs the handheld options the earlier player had (§7 there). In Docker: From ba843a943c6b92866b00bd8e09b34a1f863edb88 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:59:56 -0500 Subject: [PATCH 33/36] Gave the test bundles only libapp.so, as Linux slices now are --- Tests/LinuxPackagerTests/Fixtures.swift | 21 +-------------------- 1 file changed, 1 insertion(+), 20 deletions(-) diff --git a/Tests/LinuxPackagerTests/Fixtures.swift b/Tests/LinuxPackagerTests/Fixtures.swift index b390186..e7b63eb 100644 --- a/Tests/LinuxPackagerTests/Fixtures.swift +++ b/Tests/LinuxPackagerTests/Fixtures.swift @@ -38,11 +38,9 @@ struct Fixture { let directory = url.appendingPathComponent("lib/\(target.rawValue)") try files.createDirectory(at: directory, withIntermediateDirectories: true) let elfMachine = target == .arm64 ? machine : target.elfMachine - // What a runner loads, and the archive bundles still carry. + // What a runner loads: a Linux slice is only its libapp.so. try Data(Self.elf(machine: elfMachine, type: target == .arm64 ? elfType : 3, is64: target != .armv7)) .write(to: directory.appendingPathComponent("libapp.so")) - try Data(Self.archive([("/", [0, 0, 0, 0]), ("app.o/", Self.elf(machine: elfMachine, type: 1))])) - .write(to: directory.appendingPathComponent("libapp.a")) } if wasm { try files.createDirectory(at: url.appendingPathComponent("wasm32"), withIntermediateDirectories: true) @@ -87,23 +85,6 @@ struct Fixture { header[19] = UInt8(machine >> 8) return header } - - /// An `ar` archive of the members. - static func archive(_ members: [(name: String, data: [UInt8])]) -> [UInt8] { - var bytes = Array("!\n".utf8) - for member in members { - func field(_ value: String, _ width: Int) -> [UInt8] { - Array(value.padding(toLength: width, withPad: " ", startingAt: 0).utf8) - } - bytes += field(member.name, 16) + field("0", 12) + field("0", 6) + field("0", 6) + field("644", 8) - + field(String(member.data.count), 10) + [0x60, 0x0A] - bytes += member.data - if member.data.count % 2 == 1 { - bytes.append(0x0A) - } - } - return bytes - } } /// Plays `swift build`: records commands and makes the binary it would. From b5869d51dd59c3efa994502219e40c05a7b7a31f Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:59:56 -0500 Subject: [PATCH 34/36] Said a Linux slice is only its libapp.so --- Sources/LinuxPackager/UniversalBundle.swift | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/LinuxPackager/UniversalBundle.swift b/Sources/LinuxPackager/UniversalBundle.swift index a1a8c8e..d7e0571 100644 --- a/Sources/LinuxPackager/UniversalBundle.swift +++ b/Sources/LinuxPackager/UniversalBundle.swift @@ -3,7 +3,7 @@ import Foundation import LinuxHost /// A universal bundle from AppRuntime's `guest.py bundle`: `Info.plist`, -/// `lib//libapp.so` and `libapp.a`, `wasm32/App.wasm`, +/// `lib//libapp.so` for each Linux target, `wasm32/App.wasm`, /// `_CodeSignature/CodeResources`, and optionally `resources/` and /// `icon.png` (`Packager.md` §1). public struct UniversalBundle { From 8ca4c1cf466119974f21520516f0ad56cad4194a Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 16:59:56 -0500 Subject: [PATCH 35/36] Stopped mentioning libapp.a among what thinning drops --- Documentation/Packager.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/Packager.md b/Documentation/Packager.md index f13ae14..b25e4ae 100644 --- a/Documentation/Packager.md +++ b/Documentation/Packager.md @@ -78,7 +78,7 @@ share/applications/.desktop share/icons/hicolor/256x256/apps/.png from the bundle's icon.png ``` -Thinning drops the other targets' libraries, `libapp.a` and `App.wasm`. +Thinning drops the other targets' libraries and `App.wasm`. The signature is kept as it was: every file still in the bundle matches it, and the runner checks the library against it. The new copy is written beside the old one and replaces it whole. From eed40374a85aa659fb07dbfcd9a79f6584a245be Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Thu, 19 Nov 2026 18:19:23 -0500 Subject: [PATCH 36/36] Said AppRuntime's wasm2c shim makes a slice's libapp.so --- Documentation/Packager.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/Documentation/Packager.md b/Documentation/Packager.md index b25e4ae..2af7f21 100644 --- a/Documentation/Packager.md +++ b/Documentation/Packager.md @@ -48,10 +48,12 @@ x86_64, `linux-armv7` on armv7l), or `--target`'s. A bundle carries a `libapp.so` for each target it was built for. There's no wasm2c engine: it needs a C compiler, which a device doesn't -have. A bundle without a slice for a target needs one made where there's -a toolchain, by AppRuntime's wasm2c shim, before it's installed; the shim -makes only a `libapp.a` so far. Running `App.wasm` itself is for an engine -in the runner. +have. A bundle without a slice for a target gets one where there's a +toolchain, before it's installed: AppRuntime's +`Scripts/wasm2c-shim.py slice --bundle App.app --target linux-arm64` makes +`lib/linux-arm64/libapp.so` from `wasm32/App.wasm` and re-signs the bundle, +and the runner loads it like a native slice. Running `App.wasm` itself is +for an engine in the runner. ## 3. The runner