From 617cee32ae5c6ea3325b6e47ff6b427f8d709c6a Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Mon, 16 Nov 2026 22:30:33 -0500 Subject: [PATCH 1/8] Shared the container's path rules with settings --- Sources/LinuxHost/LinuxFiles.swift | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Sources/LinuxHost/LinuxFiles.swift b/Sources/LinuxHost/LinuxFiles.swift index 8ea186e..ab029f2 100644 --- a/Sources/LinuxHost/LinuxFiles.swift +++ b/Sources/LinuxHost/LinuxFiles.swift @@ -6,7 +6,8 @@ import RuntimeHost /// The `Files` contract (AppRuntime's `Files.md`): `RuntimeHost`'s /// `HostFiles`, with the app's directories where Linux keeps them, and -/// answers on the main loop (`Plan.md` §9). +/// answers on the main loop (`Plan.md` §9). `LinuxDefaults` keeps the +/// app's settings beside them. /// /// | Directory | `LINUXAPPRUNTIME_CONTAINER` set | Otherwise (XDG) | /// |---|---|---| @@ -89,12 +90,12 @@ public enum LinuxFiles: HostModule { return directories } - private static func nonEmpty(_ value: String?) -> String? { + static func nonEmpty(_ value: String?) -> String? { value.flatMap { $0.isEmpty ? nil : $0 } } /// The XDG specification ignores relative paths in its variables. - private static func absolute(_ value: String?) -> String? { + static func absolute(_ value: String?) -> String? { nonEmpty(value).flatMap { $0.hasPrefix("/") ? $0 : nil } } From 89f3ab59c95192a27c15790e30d10e60b47412ab Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Mon, 16 Nov 2026 22:30:33 -0500 Subject: [PATCH 2/8] Kept the app's settings in its container --- Sources/LinuxHost/LinuxDefaults.swift | 54 +++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 Sources/LinuxHost/LinuxDefaults.swift diff --git a/Sources/LinuxHost/LinuxDefaults.swift b/Sources/LinuxHost/LinuxDefaults.swift new file mode 100644 index 0000000..f2c4078 --- /dev/null +++ b/Sources/LinuxHost/LinuxDefaults.swift @@ -0,0 +1,54 @@ +import DynamicRuntime +import Foundation +import RuntimeABI +import RuntimeHost + +/// The `Defaults` contract (AppRuntime's `Defaults.md`): `RuntimeHost`'s +/// `HostDefaults` over a `FileDefaultsStorage`, one file of the app's +/// settings (`Plan.md` §9). +/// +/// | `LINUXAPPRUNTIME_CONTAINER` set | Otherwise (XDG) | +/// |---|---| +/// | `/Defaults` | `$XDG_CONFIG_HOME//Defaults` | +/// +/// `` is the app's bundle identifier, and `XDG_CONFIG_HOME` defaults to +/// `~/.config`. +public enum LinuxDefaults: HostModule { + + public static var contracts: [ContractDescriptor] { + HostDefaultsModule.contracts + } + + /// Opens the app's settings, then registers `Defaults`. Without them, + /// reads find nothing and writes are refused. + public static func register(in registrar: some ContractRegistrar) { + do { + let path = try self.path(identifier: LinuxBundle.info.identifier, environment: LinuxFiles.environment) + HostDefaults.storage = try FileDefaultsStorage(path: path) + HostLog.debug("defaults: \(path)") + } catch { + HostLog.error("defaults: \(error)") + } + HostDefaultsModule.register(in: registrar) + } + + /// Where the settings of the app `identifier` are kept. + public static func path(identifier: String, environment: [String: String]) throws(LinuxFilesError) -> String { + guard LinuxFiles.isPathComponent(identifier) else { + throw LinuxFilesError("the bundle identifier \"\(identifier)\" can't name a directory") + } + if let container = LinuxFiles.nonEmpty(environment["LINUXAPPRUNTIME_CONTAINER"]) { + guard container.hasPrefix("/") else { + throw LinuxFilesError("LINUXAPPRUNTIME_CONTAINER must be an absolute path") + } + return container + "/Defaults" + } + if let config = LinuxFiles.absolute(environment["XDG_CONFIG_HOME"]) { + return config + "/" + identifier + "/Defaults" + } + guard let home = LinuxFiles.nonEmpty(environment["HOME"]) else { + throw LinuxFilesError("neither LINUXAPPRUNTIME_CONTAINER nor HOME is set") + } + return home + "/.config/" + identifier + "/Defaults" + } +} From d0c35ba28e7f8ec6b4657d4740ec0ad4c11d050a Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Mon, 16 Nov 2026 22:30:33 -0500 Subject: [PATCH 3/8] Tested where settings are kept and that they last --- Tests/LinuxHostTests/LinuxDefaultsTests.swift | 60 +++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 Tests/LinuxHostTests/LinuxDefaultsTests.swift diff --git a/Tests/LinuxHostTests/LinuxDefaultsTests.swift b/Tests/LinuxHostTests/LinuxDefaultsTests.swift new file mode 100644 index 0000000..535e407 --- /dev/null +++ b/Tests/LinuxHostTests/LinuxDefaultsTests.swift @@ -0,0 +1,60 @@ +import Foundation +import RuntimeHost +import Testing +@testable import LinuxHost + +/// `HostDefaults.storage` is one for the process: one test at a time. +@Suite(.serialized) struct LinuxDefaultsTests { + + @Test func paths() throws { + #expect(try LinuxDefaults.path(identifier: "org.example.App", environment: ["HOME": "/home/ada"]) + == "/home/ada/.config/org.example.App/Defaults") + #expect(try LinuxDefaults.path(identifier: "org.example.App", + environment: ["HOME": "/home/ada", "XDG_CONFIG_HOME": "/etc/ada"]) + == "/etc/ada/org.example.App/Defaults") + // A relative XDG_CONFIG_HOME is ignored, as the specification says. + #expect(try LinuxDefaults.path(identifier: "org.example.App", + environment: ["HOME": "/home/ada", "XDG_CONFIG_HOME": "config"]) + == "/home/ada/.config/org.example.App/Defaults") + #expect(try LinuxDefaults.path(identifier: "org.example.App", + environment: ["HOME": "/home/ada", "LINUXAPPRUNTIME_CONTAINER": "/roms/ports/app/conf"]) + == "/roms/ports/app/conf/Defaults") + } + + @Test func pathsThatCantBe() { + #expect(throws: LinuxFilesError.self) { + try LinuxDefaults.path(identifier: "../org.example.App", environment: ["HOME": "/home/ada"]) + } + #expect(throws: LinuxFilesError.self) { + try LinuxDefaults.path(identifier: "org.example.App", environment: ["LINUXAPPRUNTIME_CONTAINER": "conf"]) + } + #expect(throws: LinuxFilesError.self) { + try LinuxDefaults.path(identifier: "org.example.App", environment: [:]) + } + } + + /// Settings in a container's file outlast the launch that set them. + @Test func settingsAreThereAtTheNextLaunch() throws { + let container = FileManager.default.temporaryDirectory.appendingPathComponent("linux-defaults-\(UUID())") + defer { try? FileManager.default.removeItem(at: container) } + let path = try LinuxDefaults.path(identifier: "org.example.App", + environment: ["LINUXAPPRUNTIME_CONTAINER": container.path]) + defer { HostDefaults.storage = nil } + + HostDefaults.storage = try FileDefaultsStorage(path: path) + let defaults = HostDefaults.standard() + #expect(defaults.setString("Ada", key: "name")) + #expect(defaults.setData([1, 2, 3], key: "token")) + #expect(defaults.setString("", key: "empty")) + #expect(!defaults.setString("x", key: "")) + defaults.remove("token") + #expect(FileManager.default.fileExists(atPath: container.appendingPathComponent("Defaults").path)) + + // The next launch reads the file again. + HostDefaults.storage = try FileDefaultsStorage(path: path) + #expect(defaults.string("name") == "Ada") + #expect(defaults.string("empty") == "") + #expect(defaults.data("token") == nil) + #expect(defaults.keys() == ["empty", "name"]) + } +} From fa57fd21e1c62c46a0d4ef7cf8f1c16960192c4c Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Mon, 16 Nov 2026 22:30:33 -0500 Subject: [PATCH 4/8] Registered settings in the host --- Sources/LinuxHostApp/HostApp.swift | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Sources/LinuxHostApp/HostApp.swift b/Sources/LinuxHostApp/HostApp.swift index 4cb4372..68bf780 100644 --- a/Sources/LinuxHostApp/HostApp.swift +++ b/Sources/LinuxHostApp/HostApp.swift @@ -26,9 +26,9 @@ public enum HostApp { /// Every module this host has: the SwiftUI player (DarwinUI, on Cacao), /// Bluetooth, GL surfaces and web pages, which the player shows, and - /// the app's files. + /// the app's files and settings. public static let modules: [any HostModule.Type] = [ - DarwinUI.self, LinuxBluetooth.self, LinuxGraphics.self, LinuxWebKit.self, LinuxFiles.self, + DarwinUI.self, LinuxBluetooth.self, LinuxGraphics.self, LinuxWebKit.self, LinuxFiles.self, LinuxDefaults.self, ] /// The window's title: the app's name. From 8f2e892d420166e17e8aa67f1758be0104f40511 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Mon, 16 Nov 2026 22:30:33 -0500 Subject: [PATCH 5/8] Listed settings among the host's contracts --- Sources/LinuxPackager/Validator.swift | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Sources/LinuxPackager/Validator.swift b/Sources/LinuxPackager/Validator.swift index 89bcf11..19c74b8 100644 --- a/Sources/LinuxPackager/Validator.swift +++ b/Sources/LinuxPackager/Validator.swift @@ -12,9 +12,9 @@ public enum HostContracts { /// The modules `linux-app-host` registers (`HostApp.modules`): the /// player's contracts, without building the player, Bluetooth, - /// graphics, web views and files. + /// graphics, web views, files and settings. nonisolated(unsafe) public static let modules: [any HostModule.Type] = [ - PlayerContracts.self, LinuxBluetooth.self, LinuxGraphics.self, LinuxWebKit.self, LinuxFiles.self, + PlayerContracts.self, LinuxBluetooth.self, LinuxGraphics.self, LinuxWebKit.self, LinuxFiles.self, LinuxDefaults.self, ] public static var provided: [String: ContractDescriptor] { From ef517fe90d1f16e3fe9331a82a8ef7bbbc609dbc Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Mon, 16 Nov 2026 22:30:34 -0500 Subject: [PATCH 6/8] Documented settings --- Documentation/Plan.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/Documentation/Plan.md b/Documentation/Plan.md index b9d7727..d447861 100644 --- a/Documentation/Plan.md +++ b/Documentation/Plan.md @@ -46,7 +46,7 @@ AppRuntime's contracts. | 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 | | Wayland and X11 through SDL3; a headless driver for tests | Multiple windows | -| `Renderer`, Bluetooth `Central` and friends, GL surfaces, web views, files, the built-ins | Location (GeoClue), Device (UPower, sysfs), Networking (libcurl), Formatting (ICU), Motion (iio-sensor-proxy), NFC (neard) | +| `Renderer`, Bluetooth `Central` and friends, GL surfaces, web views, files, settings, the built-ins | Location (GeoClue), Device (UPower, sysfs), Networking (libcurl), Formatting (ICU), Motion (iio-sensor-proxy), NFC (neard) | ## 2. Process model @@ -87,7 +87,7 @@ timers for `schedule`. | Module | Contents | |---|---| -| `LinuxHost` | `AppHost` (built-ins, modules, `rt_main`), `MainLoop`, `MainLoopClock`, the `Bundle` built-in, and `LinuxFiles` (§9); over AppRuntime's `RuntimeHost`, which every host shares: `AppInfo` (the bundle's `Info.plist` keys), the compatibility checks, `HostModule`, the `Permissions` and `Application` built-ins, and `HostFiles` | +| `LinuxHost` | `AppHost` (built-ins, modules, `rt_main`), `MainLoop`, `MainLoopClock`, the `Bundle` built-in, and `LinuxFiles` and `LinuxDefaults` (§9); over AppRuntime's `RuntimeHost`, which every host shares: `AppInfo` (the bundle's `Info.plist` keys), the compatibility checks, `HostModule`, the `Permissions` and `Application` built-ins, `HostFiles` and `HostDefaults` | | `LinuxUI` | The SwiftUI player: DarwinAppRuntime's `DarwinUI`, copied by `Scripts/sync-darwinui.sh`, over Cacao's `SwiftUI` and `Combine` modules; `Host.swift` gives it the logger and bundle it takes from its host | | `LinuxBluetooth` | `Central`, `Peripheral`, `Service`, `Characteristic`, `Descriptor`, `Advertisement` over BlueZ | | `LinuxGraphics` | `Surface` over EGL and GLES 2.0, loaded at run time; the player's `GLSurface` view shows it (§7) | @@ -275,7 +275,7 @@ WebKit, and the player draws `WebView` nodes. It follows Perry's - Reading files beside a bundled page only: WebKit's file-URL rules apply. -## 9. Files +## 9. Files and settings `LinuxFiles` is the `Files` contract (AppRuntime's `Files.md`): AppRuntime's `HostFiles`, which does it all over POSIX calls, with the app's directories @@ -301,6 +301,16 @@ where Linux keeps them, and answers posted to the main loop from its queue. - **If the directories can't be decided**, for example with no `HOME`, the host logs why and every operation fails through its callback. +`LinuxDefaults` is the `Defaults` contract (`Defaults.md`): AppRuntime's +`HostDefaults` over a `FileDefaultsStorage`, one file with every setting in +it, rewritten atomically at each change. + +- **The file** is `/Defaults` in a container. Otherwise it's + `$XDG_CONFIG_HOME//Defaults`, which is `~/.config//Defaults` by + default: XDG's place for settings. +- **If it can't be opened**, the host logs why. Reads then find nothing, + and writes are refused. + ## 10. Testing - `LinuxUI`: DarwinUI's tests, on Cacao (§5). @@ -310,6 +320,8 @@ where Linux keeps them, and answers posted to the main loop from its queue. frames drawn and read back with Mesa's llvmpipe, and a lost context. - `LinuxHost`'s files: the directories from the environment, and the 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. - `LinuxWebKit`: on Linux, in WPE: loading HTML and the events' order, scripts' JSON, navigations asked about and refused, back, bundle resources, a refused connection, remote loads without `network`, frames From cb26ab7db0086f94f45d624de3ad74a03013a61d Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Mon, 16 Nov 2026 22:30:34 -0500 Subject: [PATCH 7/8] Said a port's settings go in its conf folder --- Documentation/PortMaster.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/PortMaster.md b/Documentation/PortMaster.md index d0fc465..969cf76 100644 --- a/Documentation/PortMaster.md +++ b/Documentation/PortMaster.md @@ -50,7 +50,7 @@ host's options for a handheld: | `LINUXAPPRUNTIME_SCALE` | Pixels per point: 1 below 700 pixels tall, 1.5 below 1000, 2 above, so a 640 × 480 screen is 640 × 480 points and a 720 × 720 one 480 × 480 | | `LINUXAPPRUNTIME_CURSOR=1` | Draw a pointer: there's no mouse, and KMSDRM has no system cursor | | `LINUXAPPRUNTIME_FONTS` | `fonts/`, used when fontconfig isn't there | -| `LINUXAPPRUNTIME_CONTAINER` | `conf/`: the app's files, where ports keep what's theirs | +| `LINUXAPPRUNTIME_CONTAINER` | `conf/`: the app's files and settings, where ports keep what's theirs | ## 3. Controls From 0e71b26e4f0cac2ef8553ce241a9ae66d6638ab0 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Mon, 16 Nov 2026 22:30:34 -0500 Subject: [PATCH 8/8] Described settings and their container --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e3a98d8..82c9c86 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ in its `documents`: | Module | | |---|---| -| `LinuxHost` | `AppHost` (built-ins, modules, `rt_main`), `MainLoop` and its clock, the `Bundle` built-in, and `LinuxFiles`, the app's files in XDG's directories or a container ([plan](Documentation/Plan.md) §9), over AppRuntime's shared `RuntimeHost` (`AppInfo`, compatibility checks, `HostModule`, `Permissions`, `Application`, `HostFiles`) | +| `LinuxHost` | `AppHost` (built-ins, modules, `rt_main`), `MainLoop` and its clock, the `Bundle` built-in, `LinuxFiles` and `LinuxDefaults`, the app's files and settings in XDG's directories or a container ([plan](Documentation/Plan.md) §9), over AppRuntime's shared `RuntimeHost` (`AppInfo`, compatibility checks, `HostModule`, `Permissions`, `Application`, `HostFiles`, `HostDefaults`) | | `LinuxUI` | The SwiftUI player: DarwinAppRuntime's `DarwinUI`, copied by `Scripts/sync-darwinui.sh`, over Cacao's `SwiftUI` | | `LinuxBluetooth` | `Central`, `Peripheral`, `Service`, `Characteristic`, `Descriptor` and `Advertisement` over BlueZ, through `wendylabsinc/dbus` | | `LinuxGraphics` | `Surface`: GLES 2.0 drawn in EGL pbuffers, loaded at run time, and read back into the player's `GLSurface` view ([plan](Documentation/Plan.md) §7) | @@ -149,7 +149,7 @@ The bundle needs `linux-arm64` and `linux-armv7` slices (`guest.py bundle | Variable | | |---|---| | `LINUXAPPRUNTIME_DEBUG` | `1` logs the host's debug messages | -| `LINUXAPPRUNTIME_CONTAINER` | An absolute path that holds the app's files (`Documents`, `Data`, `Caches`, `tmp`), in place of XDG's directories | +| `LINUXAPPRUNTIME_CONTAINER` | An absolute path that holds the app's files (`Documents`, `Data`, `Caches`, `tmp`) and settings (`Defaults`), in place of XDG's directories | | `CACAO_SCREENSHOT` | Saves the first frame to a PNG and quits | | `CACAO_SHOW_STATISTICS` | `1` shows Cacao's frame times | | `SDL_VIDEO_DRIVER` | `wayland`, `x11`, `kmsdrm`, or `offscreen` for no display |