Skip to content
Binary file added Documentation/ExampleFiles.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
40 changes: 34 additions & 6 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, 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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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` | `<container>/Documents` | `$XDG_DATA_HOME/<id>/Documents` |
| `data` | `<container>/Data` | `$XDG_DATA_HOME/<id>/Data` |
| `caches` | `<container>/Caches` | `$XDG_CACHE_HOME/<id>` |
| `temporary` | `<container>/tmp` | `$XDG_RUNTIME_DIR/<id>`, or `/tmp/<id>-<uid>` |
| `bundle` | the bundle's `resources/` | the same |

- **`<id>`** 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
Expand All @@ -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.
Expand All @@ -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
Expand Down
1 change: 1 addition & 0 deletions Documentation/PortMaster.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
5 changes: 3 additions & 2 deletions Package.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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
),

Expand Down Expand Up @@ -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,
Expand Down
8 changes: 7 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) |
Expand Down Expand Up @@ -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 |
115 changes: 115 additions & 0 deletions Sources/LinuxHost/LinuxFiles.swift
Original file line number Diff line number Diff line change
@@ -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` | `<container>/Documents` | `$XDG_DATA_HOME/<id>/Documents` |
/// | `data` | `<container>/Data` | `$XDG_DATA_HOME/<id>/Data` |
/// | `caches` | `<container>/Caches` | `$XDG_CACHE_HOME/<id>` |
/// | `temporary` | `<container>/tmp` | `$XDG_RUNTIME_DIR/<id>`, or `/tmp/<id>-<uid>` |
/// | `bundle` | the bundle's `resources/` | the same |
///
/// `<id>` 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
}
}
7 changes: 5 additions & 2 deletions Sources/LinuxHostApp/HostApp.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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 = ""
Expand Down
6 changes: 4 additions & 2 deletions Sources/LinuxPackager/PortMaster.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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"
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 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] {
Expand Down
Loading
Loading