Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 15 additions & 3 deletions Documentation/Plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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) |
Expand Down Expand Up @@ -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
Expand All @@ -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 `<container>/Defaults` in a container. Otherwise it's
`$XDG_CONFIG_HOME/<id>/Defaults`, which is `~/.config/<id>/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).
Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion Documentation/PortMaster.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) |
Expand Down Expand Up @@ -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 |
54 changes: 54 additions & 0 deletions Sources/LinuxHost/LinuxDefaults.swift
Original file line number Diff line number Diff line change
@@ -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) |
/// |---|---|
/// | `<container>/Defaults` | `$XDG_CONFIG_HOME/<id>/Defaults` |
///
/// `<id>` 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"
}
}
7 changes: 4 additions & 3 deletions Sources/LinuxHost/LinuxFiles.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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) |
/// |---|---|---|
Expand Down Expand Up @@ -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 }
}

Expand Down
4 changes: 2 additions & 2 deletions Sources/LinuxHostApp/HostApp.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 2 additions & 2 deletions Sources/LinuxPackager/Validator.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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] {
Expand Down
60 changes: 60 additions & 0 deletions Tests/LinuxHostTests/LinuxDefaultsTests.swift
Original file line number Diff line number Diff line change
@@ -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"])
}
}
Loading