From 123a1a61e1227e6b4bf350411612daecb4b11201 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Mon, 16 Nov 2026 17:46:27 -0500 Subject: [PATCH 01/10] Implemented Files with HostFiles, in XDG's directories or a container --- Sources/LinuxHost/LinuxFiles.swift | 115 +++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 Sources/LinuxHost/LinuxFiles.swift diff --git a/Sources/LinuxHost/LinuxFiles.swift b/Sources/LinuxHost/LinuxFiles.swift new file mode 100644 index 0000000..8ea186e --- /dev/null +++ b/Sources/LinuxHost/LinuxFiles.swift @@ -0,0 +1,115 @@ +import DynamicFiles +import DynamicRuntime +import Foundation +import RuntimeABI +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). +/// +/// | Directory | `LINUXAPPRUNTIME_CONTAINER` set | Otherwise (XDG) | +/// |---|---|---| +/// | `documents` | `/Documents` | `$XDG_DATA_HOME//Documents` | +/// | `data` | `/Data` | `$XDG_DATA_HOME//Data` | +/// | `caches` | `/Caches` | `$XDG_CACHE_HOME/` | +/// | `temporary` | `/tmp` | `$XDG_RUNTIME_DIR/`, or `/tmp/-` | +/// | `bundle` | the bundle's `resources/` | the same | +/// +/// `` is the app's bundle identifier. `XDG_DATA_HOME` defaults to +/// `~/.local/share` and `XDG_CACHE_HOME` to `~/.cache`. `temporary` is the +/// app's own, since it's emptied at every start. +public enum LinuxFiles: HostModule { + + public static var contracts: [ContractDescriptor] { + HostFilesModule.contracts + } + + /// Says where the app's files are, then registers `Files`. The + /// directories come from the app's identifier and `LinuxBundle`, which + /// `AppHost` sets up first. + public static func register(in registrar: some ContractRegistrar) { + let identifier = LinuxBundle.info.identifier + do { + let directories = try self.directories(identifier: identifier, resources: LinuxBundle.resources, environment: environment) + try HostFiles.configure(HostFiles.Configuration(directories: directories, deliver: deliver)) + HostLog.debug("files: \(directories.sorted { $0.key.rawValue < $1.key.rawValue }.map { "\($0.key): \($0.value)" }.joined(separator: ", "))") + } catch { + // Every operation then fails, and says so through its callback. + HostLog.error("files: \(error)") + } + HostFilesModule.register(in: registrar) + } + + /// The environment the directories come from; replaceable for tests. + nonisolated(unsafe) public static var environment = ProcessInfo.processInfo.environment + + /// Answers go to the main loop, from `HostFiles`' queue. + static let deliver: @Sendable (@escaping @Sendable () -> Void) -> Void = { answer in + MainLoop.shared.post(answer) + } + + /// Where each directory is for the app `identifier`. + public static func directories( + identifier: String, + resources: String?, + environment: [String: String], + userID: UInt32 = getuid() + ) throws(LinuxFilesError) -> [FileDirectory: String] { + guard isPathComponent(identifier) else { + throw LinuxFilesError("the bundle identifier \"\(identifier)\" can't name a directory") + } + var directories: [FileDirectory: String] = [:] + if let container = nonEmpty(environment["LINUXAPPRUNTIME_CONTAINER"]) { + guard container.hasPrefix("/") else { + throw LinuxFilesError("LINUXAPPRUNTIME_CONTAINER must be an absolute path") + } + directories[.documents] = container + "/Documents" + directories[.data] = container + "/Data" + directories[.caches] = container + "/Caches" + directories[.temporary] = container + "/tmp" + } else { + guard let home = nonEmpty(environment["HOME"]) else { + throw LinuxFilesError("neither LINUXAPPRUNTIME_CONTAINER nor HOME is set") + } + let data = absolute(environment["XDG_DATA_HOME"]) ?? home + "/.local/share" + let cache = absolute(environment["XDG_CACHE_HOME"]) ?? home + "/.cache" + directories[.documents] = data + "/" + identifier + "/Documents" + directories[.data] = data + "/" + identifier + "/Data" + directories[.caches] = cache + "/" + identifier + if let runtime = absolute(environment["XDG_RUNTIME_DIR"]) { + directories[.temporary] = runtime + "/" + identifier + } else { + directories[.temporary] = "/tmp/\(identifier)-\(userID)" + } + } + if let resources { + directories[.bundle] = resources + } + return directories + } + + private 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? { + nonEmpty(value).flatMap { $0.hasPrefix("/") ? $0 : nil } + } + + /// One path component: not empty, `.` or `..`, and no `/` or NUL. + static func isPathComponent(_ name: String) -> Bool { + !name.isEmpty && name != "." && name != ".." && !name.contains("/") && !name.contains("\0") + } +} + +/// Why the app's directories couldn't be decided. +public struct LinuxFilesError: Error, CustomStringConvertible { + + public var description: String + + init(_ description: String) { + self.description = description + } +} From 0f3a834cc8a122ee7bdae7f20e9d6822808ecd34 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Mon, 16 Nov 2026 17:46:27 -0500 Subject: [PATCH 02/10] Tested the app's directories and the Files contract on the main loop --- Tests/LinuxHostTests/LinuxFilesTests.swift | 122 +++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 Tests/LinuxHostTests/LinuxFilesTests.swift diff --git a/Tests/LinuxHostTests/LinuxFilesTests.swift b/Tests/LinuxHostTests/LinuxFilesTests.swift new file mode 100644 index 0000000..358a64b --- /dev/null +++ b/Tests/LinuxHostTests/LinuxFilesTests.swift @@ -0,0 +1,122 @@ +import DynamicFiles +import Foundation +import RuntimeHost +import Testing +@testable import LinuxHost + +/// Records the one answer an operation gets. +final class RecordingCallback: FileCallback { + + var answer: String? + + func didComplete() { answer = "complete" } + + func didRead(_ data: [UInt8]) { answer = "read \(String(decoding: data, as: UTF8.self))" } + + func didList(_ names: [String]) { answer = "list \(names.joined(separator: ","))" } + + func didGetAttributes(kind: Int32, size: Int64, modified: Int64) { + answer = "attributes \(kind) \(size) \(modified > 0)" + } + + func didFail(_ error: Int32) { answer = "fail \(error)" } +} + +/// `HostFiles` is configured once for the process: one test at a time. +@Suite(.serialized) struct LinuxFilesTests { + + @Test func xdgDirectories() throws { + let directories = try LinuxFiles.directories( + identifier: "org.example.App", resources: "/apps/App.app/resources", + environment: ["HOME": "/home/ada", "XDG_RUNTIME_DIR": "/run/user/1000"], userID: 1000) + #expect(directories == [ + .documents: "/home/ada/.local/share/org.example.App/Documents", + .data: "/home/ada/.local/share/org.example.App/Data", + .caches: "/home/ada/.cache/org.example.App", + .temporary: "/run/user/1000/org.example.App", + .bundle: "/apps/App.app/resources", + ]) + } + + @Test func xdgVariablesAndTheirDefaults() throws { + let directories = try LinuxFiles.directories( + identifier: "org.example.App", resources: nil, + environment: ["HOME": "/home/ada", "XDG_DATA_HOME": "/data/ada", "XDG_CACHE_HOME": "relative/is/ignored"], + userID: 1000) + #expect(directories[.documents] == "/data/ada/org.example.App/Documents") + #expect(directories[.caches] == "/home/ada/.cache/org.example.App") + // Without a runtime directory, the app's own under /tmp. + #expect(directories[.temporary] == "/tmp/org.example.App-1000") + // No bundle, no bundle directory: its files aren't found. + #expect(directories[.bundle] == nil) + } + + @Test func aContainer() throws { + let directories = try LinuxFiles.directories( + identifier: "org.example.App", resources: "/roms/ports/app/App.app/resources", + environment: ["HOME": "/home/ada", "LINUXAPPRUNTIME_CONTAINER": "/roms/ports/app/conf"]) + #expect(directories == [ + .documents: "/roms/ports/app/conf/Documents", + .data: "/roms/ports/app/conf/Data", + .caches: "/roms/ports/app/conf/Caches", + .temporary: "/roms/ports/app/conf/tmp", + .bundle: "/roms/ports/app/App.app/resources", + ]) + #expect(throws: LinuxFilesError.self) { + try LinuxFiles.directories(identifier: "org.example.App", resources: nil, + environment: ["LINUXAPPRUNTIME_CONTAINER": "conf"]) + } + } + + @Test func identifiersMustNameADirectory() { + for identifier in ["", ".", "..", "org/example", "a\0b"] { + #expect(throws: LinuxFilesError.self) { + try LinuxFiles.directories(identifier: identifier, resources: nil, environment: ["HOME": "/home/ada"]) + } + } + #expect(throws: LinuxFilesError.self) { + try LinuxFiles.directories(identifier: "org.example.App", resources: nil, environment: [:]) + } + } + + /// The contract end to end: `HostFiles` in a container, answering on + /// the main loop. + @Test func filesAnswerOnTheMainLoop() throws { + let root = FileManager.default.temporaryDirectory.appendingPathComponent("linux-files-\(UUID())") + let resources = root.appendingPathComponent("App.app/resources") + try FileManager.default.createDirectory(at: resources.appendingPathComponent("levels"), withIntermediateDirectories: true) + try Data("level one".utf8).write(to: resources.appendingPathComponent("levels/1.map")) + defer { try? FileManager.default.removeItem(at: root) } + let directories = try LinuxFiles.directories( + identifier: "org.example.App", resources: resources.path, + environment: ["LINUXAPPRUNTIME_CONTAINER": root.appendingPathComponent("conf").path]) + try HostFiles.configure(HostFiles.Configuration(directories: directories, deliver: LinuxFiles.deliver)) + let files = HostFiles.shared() + + func perform(_ operation: (RecordingCallback) -> Void) -> String? { + let callback = RecordingCallback() + operation(callback) + MainLoop.shared.run { callback.answer != nil } + return callback.answer + } + let documents = FileDirectory.documents.rawValue + // The writable directories are there from the start. + #expect(FileManager.default.fileExists(atPath: root.appendingPathComponent("conf/Documents").path)) + #expect(perform { files.read(FileDirectory.bundle.rawValue, path: "levels/1.map", offset: 0, length: -1, callback: $0) } + == "read level one") + #expect(perform { files.write(documents, path: "saves/slot1.sav", data: Array("saved".utf8), mode: 0, callback: $0) } + == "complete") + #expect(perform { files.write(documents, path: "saves/slot1.sav", data: Array(" more".utf8), mode: 1, callback: $0) } + == "complete") + #expect(perform { files.read(documents, path: "saves/slot1.sav", offset: 0, length: -1, callback: $0) } == "read saved more") + #expect(perform { files.list(documents, path: "", callback: $0) } == "list saves/") + #expect(perform { files.attributes(documents, path: "saves/slot1.sav", callback: $0) } == "attributes 0 10 true") + #expect(perform { files.copy(FileDirectory.bundle.rawValue, path: "levels", toDirectory: documents, toPath: "levels", callback: $0) } + == "complete") + #expect(perform { files.write(FileDirectory.bundle.rawValue, path: "x", data: [], mode: 0, callback: $0) } + == "fail \(FileError.readOnly.rawValue)") + #expect(perform { files.read(documents, path: "../escape", offset: 0, length: -1, callback: $0) } + == "fail \(FileError.invalidPath.rawValue)") + #expect(try String(contentsOf: root.appendingPathComponent("conf/Documents/levels/1.map"), encoding: .utf8) == "level one") + } +} From 82dbe89a3c97e477fac654ad7b01102d1977901f Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Mon, 16 Nov 2026 17:46:27 -0500 Subject: [PATCH 03/10] Depended on DynamicFiles for the host's files --- Package.swift | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Package.swift b/Package.swift index 6c88ced..0d23048 100644 --- a/Package.swift +++ b/Package.swift @@ -92,7 +92,8 @@ let package = Package( .target( name: "LinuxHost", - dependencies: [runtime("CRuntime"), runtime("RuntimeCore"), runtime("RuntimeNative"), runtime("DynamicRuntime"), runtime("RuntimeABI"), runtime("RuntimeHost")], + dependencies: [runtime("CRuntime"), runtime("RuntimeCore"), runtime("RuntimeNative"), runtime("DynamicRuntime"), runtime("RuntimeABI"), + runtime("RuntimeHost"), runtime("DynamicFiles")], swiftSettings: host ), @@ -175,7 +176,7 @@ let package = Package( // MARK: - Tests - .testTarget(name: "LinuxHostTests", dependencies: ["LinuxHost"], swiftSettings: host), + .testTarget(name: "LinuxHostTests", dependencies: ["LinuxHost", runtime("DynamicFiles")], swiftSettings: host), .testTarget( name: "LinuxUITests", dependencies: ["LinuxUI", runtime("DynamicUI"), runtime("DynamicRuntime"), .product(name: "Cacao", package: "Cacao")] + swiftUI, From 1c06273f49b037ba64c659606c0a2f73cb5eb725 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Mon, 16 Nov 2026 17:46:27 -0500 Subject: [PATCH 04/10] Registered the files module in the host app --- Sources/LinuxHostApp/HostApp.swift | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/Sources/LinuxHostApp/HostApp.swift b/Sources/LinuxHostApp/HostApp.swift index fbd15c6..4cb4372 100644 --- a/Sources/LinuxHostApp/HostApp.swift +++ b/Sources/LinuxHostApp/HostApp.swift @@ -25,8 +25,11 @@ import LinuxUI public enum HostApp { /// Every module this host has: the SwiftUI player (DarwinUI, on Cacao), - /// Bluetooth, and GL surfaces and web pages, which the player shows. - public static let modules: [any HostModule.Type] = [DarwinUI.self, LinuxBluetooth.self, LinuxGraphics.self, LinuxWebKit.self] + /// Bluetooth, GL surfaces and web pages, which the player shows, and + /// the app's files. + public static let modules: [any HostModule.Type] = [ + DarwinUI.self, LinuxBluetooth.self, LinuxGraphics.self, LinuxWebKit.self, LinuxFiles.self, + ] /// The window's title: the app's name. nonisolated(unsafe) static var title = "" From 3328d8af7446bd66538c9d5d6b1a2ba230cb7d3e Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Mon, 16 Nov 2026 17:46:27 -0500 Subject: [PATCH 05/10] Checked apps against the Files contract --- 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 2547090..89bcf11 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 and web views. + /// graphics, web views and files. nonisolated(unsafe) public static let modules: [any HostModule.Type] = [ - PlayerContracts.self, LinuxBluetooth.self, LinuxGraphics.self, LinuxWebKit.self, + PlayerContracts.self, LinuxBluetooth.self, LinuxGraphics.self, LinuxWebKit.self, LinuxFiles.self, ] public static var provided: [String: ContractDescriptor] { From ddae79b52271795ac584daf2e0391f8503124338 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Mon, 16 Nov 2026 17:46:27 -0500 Subject: [PATCH 06/10] Kept a port's files in its conf folder --- Sources/LinuxPackager/PortMaster.swift | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Sources/LinuxPackager/PortMaster.swift b/Sources/LinuxPackager/PortMaster.swift index dbd01b1..66895ec 100644 --- a/Sources/LinuxPackager/PortMaster.swift +++ b/Sources/LinuxPackager/PortMaster.swift @@ -241,8 +241,10 @@ public struct PortMasterPort { export TEXTINPUTINTERACTIVE="Y" # The host on a handheld: one fullscreen window, a drawn pointer, the - # port's fonts when fontconfig isn't there, and phone-sized layouts - # scaled to the screen. + # port's fonts when fontconfig isn't there, phone-sized layouts + # scaled to the screen, and the app's files in the port's conf/, + # where ports keep what's theirs. + export LINUXAPPRUNTIME_CONTAINER="$GAMEDIR/conf" export LINUXAPPRUNTIME_FULLSCREEN=1 export LINUXAPPRUNTIME_CURSOR=1 export LINUXAPPRUNTIME_FONTS="$GAMEDIR/fonts" From 4b0e3a6f3a39c47af6e0d6bbc4af7b747e8fc04c Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Mon, 16 Nov 2026 17:46:28 -0500 Subject: [PATCH 07/10] Showed ExampleFiles on Linux --- Documentation/ExampleFiles.png | Bin 0 -> 19309 bytes 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 Documentation/ExampleFiles.png diff --git a/Documentation/ExampleFiles.png b/Documentation/ExampleFiles.png new file mode 100644 index 0000000000000000000000000000000000000000..18966a1f5a49c90e7ac0d31fcc9be45e027b9240 GIT binary patch literal 19309 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 Date: Mon, 16 Nov 2026 17:46:28 -0500 Subject: [PATCH 08/10] Documented files --- Documentation/Plan.md | 40 ++++++++++++++++++++++++++++++++++------ 1 file changed, 34 insertions(+), 6 deletions(-) diff --git a/Documentation/Plan.md b/Documentation/Plan.md index f355360..b9d7727 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, 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, the built-ins | Location (GeoClue), Device (UPower, sysfs), Networking (libcurl), Formatting (ICU), Motion (iio-sensor-proxy), NFC (neard) | ## 2. Process model @@ -87,13 +87,13 @@ timers for `schedule`. | Module | Contents | |---|---| -| `LinuxHost` | `AppHost` (built-ins, modules, `rt_main`), `MainLoop`, `MainLoopClock`, the `Bundle` built-in; over AppRuntime's `RuntimeHost`, which every host shares: `AppInfo` (the bundle's `Info.plist` keys), the compatibility checks, `HostModule`, and the `Permissions` and `Application` built-ins | +| `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` | | `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) | | `LinuxWebKit` | `WebContent` over WPE WebKit, loaded at run time; the player's `WebView` view shows it (§8) | | `LinuxHostApp` | `main`: reads the app's keys, starts the host, and runs Cacao's SDL loop with one window showing the guest's first renderer | -| `LinuxPackager`, `linux-app` | The packager (§10, [Packager.md](Packager.md)) | +| `LinuxPackager`, `linux-app` | The packager (§11, [Packager.md](Packager.md)) | The package depends on AppRuntime without its `GuestExports` trait, like DarwinAppRuntime, so the slice's `rt_dispatch` and `rt_finalize` are the @@ -275,13 +275,41 @@ 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. Testing +## 9. Files + +`LinuxFiles` is the `Files` contract (AppRuntime's `Files.md`): AppRuntime's +`HostFiles`, which does it all over POSIX calls, with the app's directories +where Linux keeps them, and answers posted to the main loop from its queue. + +| Directory | In a container | Otherwise, XDG's | +|---|---|---| +| `documents` | `/Documents` | `$XDG_DATA_HOME//Documents` | +| `data` | `/Data` | `$XDG_DATA_HOME//Data` | +| `caches` | `/Caches` | `$XDG_CACHE_HOME/` | +| `temporary` | `/tmp` | `$XDG_RUNTIME_DIR/`, or `/tmp/-` | +| `bundle` | the bundle's `resources/` | the same | + +- **``** is the bundle identifier, which must name a directory. + `XDG_DATA_HOME` is `~/.local/share` and `XDG_CACHE_HOME` `~/.cache` when + they're unset or relative, as the XDG specification says. +- **A container** is `LINUXAPPRUNTIME_CONTAINER`, an absolute path: + - a PortMaster port's is its `conf/` folder, where ports keep what's + theirs; + - a launcher's sandbox would pass `/data` (AppRuntime's §7.8). +- **`temporary` is the app's own**, never `/tmp` itself, since `HostFiles` + empties it at every start. +- **If the directories can't be decided**, for example with no `HOME`, the + host logs why and every operation fails through its callback. + +## 10. Testing - `LinuxUI`: DarwinUI's tests, on Cacao (§5). - `LinuxBluetooth`: the contract against a fake `BlueZBus` that plays BlueZ's objects and signals. Runs on macOS and Linux. - `LinuxGraphics`: a surface's input order, focus and size, and on Linux 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. - `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 @@ -293,7 +321,7 @@ WebKit, and the player draws `WebView` nodes. It follows Perry's - Real BlueZ needs hardware: manual runs on a Raspberry Pi or a laptop with `bluetoothd`. -## 10. Phases +## 11. Phases 1. **Host runtime and player**: `LinuxHost`, `LinuxUI`, `LinuxBluetooth`, `LinuxHostApp`; `ExampleUI` runs in Docker. @@ -308,7 +336,7 @@ WebKit, and the player draws `WebView` nodes. It follows Perry's 4. **Player**: what DarwinUI and Cacao add: Cacao's AT-SPI bridge, input replay for end-to-end tests. -## 11. Open questions +## 12. Open questions - **Permissions.** Desktop Linux has no prompts for Bluetooth; Flatpak's portals cover location and the camera. `Permissions.request` answers from From a1247489153e3a1efdc4daa3dc7f1b7144ba92e3 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Mon, 16 Nov 2026 17:46:28 -0500 Subject: [PATCH 09/10] Listed the container a port's files go in --- Documentation/PortMaster.md | 1 + 1 file changed, 1 insertion(+) diff --git a/Documentation/PortMaster.md b/Documentation/PortMaster.md index 3667769..d0fc465 100644 --- a/Documentation/PortMaster.md +++ b/Documentation/PortMaster.md @@ -50,6 +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 | ## 3. Controls From 1dac3e493a2a7cc31bb52422ce621e996bb25a49 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Mon, 16 Nov 2026 17:46:28 -0500 Subject: [PATCH 10/10] Described files and their container --- README.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 2cbc7aa..e3a98d8 100644 --- a/README.md +++ b/README.md @@ -36,11 +36,16 @@ llvmpipe: ![ExampleWeb on Linux](Documentation/ExampleWeb.png) +`ExampleFiles` reads its welcome text from the bundle and lists the notes +in its `documents`: + +![ExampleFiles on Linux](Documentation/ExampleFiles.png) + ## Modules | Module | | |---|---| -| `LinuxHost` | `AppHost` (built-ins, modules, `rt_main`), `MainLoop` and its clock, and the `Bundle` built-in, over AppRuntime's shared `RuntimeHost` (`AppInfo`, compatibility checks, `HostModule`, `Permissions`, `Application`) | +| `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`) | | `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) | @@ -144,6 +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 | | `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 |