Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
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
Binary file added Documentation/ExampleModel.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
46 changes: 44 additions & 2 deletions Documentation/Plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,7 @@ timers for `schedule`.
| `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) |
| `LinuxCoreModel` | `LinuxModelStore`: the model store over CoreModel-SQLite, through AppRuntime's `HostModelStore` (§9) |
| `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 (§11, [Packager.md](Packager.md)) |

Expand Down Expand Up @@ -275,7 +276,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 and settings
## 9. App data: files, settings and model stores

`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 Down Expand Up @@ -311,6 +312,40 @@ it, rewritten atomically at each change.
- **If it can't be opened**, the host logs why. Reads then find nothing,
and writes are refused.

`LinuxModelStore`, in `LinuxCoreModel`, is the model store
(`Persistence.md`): the guest's CoreModel, through the `ModelStore`
contracts, to AppRuntime's `HostModelStore`, which turns them back into
CoreModel's requests for a backend. On Linux the backend is CoreModel's own
SQLite one, CoreModel-SQLite, with SQLite compiled in, so a device needs no
`libsqlite3`.

- **A store** is `<container>/Stores/<name>.sqlite` in a container, and
`$XDG_DATA_HOME/<id>/Stores/<name>.sqlite` otherwise: beside the app's
`Documents` and `Data`, out of reach of its `Files`.
- **The model** the store was made with is kept in it, in a table of its
own, so the model and the objects change together. An open with the same
model opens it. One that `canMigrate(from:to:)` allows (entities or
properties added or removed) is migrated by copying what both models
have into a new database, which then replaces the old one. Any other
fails with `migrationRequired`, or starts the store again with `.reset`.
- **One `SQLiteDatabase` per store**, whichever of the app's storages use
it, since it caches what it reads and must be its file's only writer. A
storage still open on a model that a later open migrated from fails with
`unavailable`: its file is gone.
- **A batch is one transaction**, in which each insert and delete is a
savepoint of its own: all of it, or none.
- **Requests answer as CoreModel's in-memory evaluation does**, which is
what defines them. Comparing the two found differences on both sides,
fixed in PureSwift/CoreModel-SQLite#14 and PureSwift/CoreModel#41, which
the package uses as branches until they're released. A predicate SQL
can't say is evaluated in memory, over the store's objects.
- **Indexes**: the app's, and one on each to-one relationship's column,
which its inverse to-many is read through. Those the app no longer
declares are dropped.
- **SQLite's errors** are the contract's: a full disk is `outOfSpace`, a
file that isn't a database `corrupted`, one that can't be opened or read
`unavailable`.

## 10. Testing

- `LinuxUI`: DarwinUI's tests, on Cacao (§5).
Expand All @@ -322,14 +357,21 @@ it, rewritten atomically at each change.
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.
- `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,
migrated, refused or emptied; indexes made and dropped; a file that isn't
a store; no directory. Runs on macOS and Linux.
- `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
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`.
driver, its first frame saved with `CACAO_SCREENSHOT`. `ExampleModel`
the same way, 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`.

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 and settings, where ports keep what's theirs |
| `LINUXAPPRUNTIME_CONTAINER` | `conf/`: the app's files, settings and model stores, where ports keep what's theirs |

## 3. Controls

Expand Down
33 changes: 31 additions & 2 deletions Package.swift
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,7 @@ let package = Package(
.library(name: "LinuxBluetooth", targets: ["LinuxBluetooth"]),
.library(name: "LinuxGraphics", targets: ["LinuxGraphics"]),
.library(name: "LinuxWebKit", targets: ["LinuxWebKit"]),
.library(name: "LinuxCoreModel", targets: ["LinuxCoreModel"]),
.library(name: "LinuxHostApp", targets: ["LinuxHostApp"]),
.executable(name: "linux-app-host", targets: ["LinuxAppHost"]),
.executable(name: "linux-app", targets: ["LinuxAppTool"]),
Expand All @@ -85,6 +86,13 @@ let package = Package(
.package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.5.0"),
// SHA-256, for bundles' CodeResources; the D-Bus package uses it too.
.package(url: "https://github.com/apple/swift-crypto.git", "3.0.0"..<"5.0.0"),
// Model stores: CoreModel's SQLite backend, and the SQLite it's
// over, which is compiled in on Linux. Both masters, until they're
// released: they answer requests as CoreModel's in-memory evaluation
// does (PureSwift/CoreModel-SQLite#14, PureSwift/CoreModel#41).
.package(url: "https://github.com/PureSwift/CoreModel-SQLite.git", branch: "master"),
.package(url: "https://github.com/PureSwift/CoreModel.git", branch: "master"),
.package(url: "https://github.com/PureSwift/SQLite.git", from: "0.2.2"),
],
targets: [

Expand Down Expand Up @@ -138,13 +146,28 @@ let package = Package(
swiftSettings: host
),

// MARK: - Model stores

// The guest's CoreModel, through the ModelStore contracts, to
// CoreModel-SQLite.
.target(
name: "LinuxCoreModel",
dependencies: [
"LinuxHost", runtime("DynamicCoreModel"), runtime("RuntimeCoreModel"), runtime("DynamicFiles"), runtime("DynamicRuntime"),
runtime("RuntimeABI"), runtime("RuntimeHost"),
.product(name: "CoreModelSQLite", package: "CoreModel-SQLite"),
.product(name: "SQLite", package: "SQLite"),
],
swiftSettings: host
),

// MARK: - App

// libc functions app slices need that older glibc lacks.
.target(name: "CLinuxHost"),
.target(
name: "LinuxHostApp",
dependencies: ["LinuxHost", "LinuxUI", "LinuxBluetooth", "LinuxGraphics", "LinuxWebKit", "CLinuxHost", runtime("CRuntime"),
dependencies: ["LinuxHost", "LinuxUI", "LinuxBluetooth", "LinuxGraphics", "LinuxWebKit", "LinuxCoreModel", "CLinuxHost", runtime("CRuntime"),
.product(name: "CacaoSDL", package: "Cacao")],
swiftSettings: host
),
Expand All @@ -166,7 +189,7 @@ let package = Package(
// doesn't build Cacao.
.target(
name: "LinuxPackager",
dependencies: ["LinuxHost", "LinuxBluetooth", "LinuxGraphics", "LinuxWebKit", runtime("DynamicUI"),
dependencies: ["LinuxHost", "LinuxBluetooth", "LinuxGraphics", "LinuxWebKit", "LinuxCoreModel", runtime("DynamicUI"),
.product(name: "Crypto", package: "swift-crypto")]
),
.executableTarget(
Expand All @@ -184,6 +207,12 @@ let package = Package(
),
.testTarget(name: "LinuxBluetoothTests", dependencies: ["LinuxBluetooth"], swiftSettings: host),
.testTarget(name: "LinuxGraphicsTests", dependencies: ["LinuxGraphics", runtime("DynamicGraphics")], swiftSettings: host),
.testTarget(
name: "LinuxCoreModelTests",
dependencies: ["LinuxCoreModel", runtime("DynamicCoreModel"), runtime("RuntimeCoreModel"),
.product(name: "CoreModelSQLite", package: "CoreModel-SQLite")],
swiftSettings: host
),
.testTarget(name: "LinuxWebKitTests", dependencies: ["LinuxWebKit", runtime("DynamicWebKit")], swiftSettings: host),
.testTarget(name: "LinuxPackagerTests", dependencies: ["LinuxPackager", "LinuxHostApp"]),
]
Expand Down
9 changes: 8 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,12 @@ in its `documents`:

![ExampleFiles on Linux](Documentation/ExampleFiles.png)

`ExampleModel` keeps to-do lists in a model store with CoreModel, kept in
SQLite. At its second launch it reads back what's there, here two to-dos
added to its database between launches:

![ExampleModel on Linux](Documentation/ExampleModel.png)

## Modules

| Module | |
Expand All @@ -50,6 +56,7 @@ in its `documents`:
| `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) |
| `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 |
| `LinuxPackager`, `linux-app` | The packager: validation, the host build, wasm2c, the install tree, PortMaster ports |

Expand Down Expand Up @@ -149,7 +156,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`) and settings (`Defaults`), in place of XDG's directories |
| `LINUXAPPRUNTIME_CONTAINER` | An absolute path that holds the app's files (`Documents`, `Data`, `Caches`, `tmp`) settings (`Defaults`) and model stores (`Stores`), 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 |
53 changes: 53 additions & 0 deletions Sources/LinuxCoreModel/LinuxModelStore.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
import DynamicFiles
import DynamicRuntime
import Foundation
import LinuxHost
import RuntimeABI
import RuntimeCoreModel
import RuntimeHost

/// The model store (AppRuntime's `Persistence.md`): the guest's CoreModel
/// through the `ModelStore` contracts to `RuntimeCoreModel`'s
/// `HostModelStore`, over CoreModel-SQLite (`Plan.md` §9).
///
/// | `LINUXAPPRUNTIME_CONTAINER` set | Otherwise (XDG) |
/// |---|---|
/// | `<container>/Stores/<name>.sqlite` | `$XDG_DATA_HOME/<id>/Stores/<name>.sqlite` |
///
/// Beside the app's `Documents` and `Data` (`LinuxFiles`), but not in
/// them: the app's files can't reach its stores.
public enum LinuxModelStore: HostModule {

public static var contracts: [ContractDescriptor] {
HostModelStoreModule.contracts
}

/// Says where the app's stores are, then registers the contracts.
/// Without a directory, `open` fails with `unavailable`.
public static func register(in registrar: some ContractRegistrar) {
do {
let directory = try self.directory(identifier: LinuxBundle.info.identifier, environment: LinuxFiles.environment)
HostModelStore.configure(HostModelStore.Configuration(
provider: SQLiteModelStorageProvider(directory: directory),
deliver: deliver))
HostLog.debug("model stores: \(directory)")
} catch {
HostLog.error("model stores: \(error)")
}
HostModelStoreModule.register(in: registrar)
}

/// Answers go to the main loop, from the stores' tasks.
static let deliver: @Sendable (@escaping @Sendable () -> Void) -> Void = { answer in
MainLoop.shared.post(answer)
}

/// The directory of the app `identifier`'s stores: beside its
/// documents.
public static func directory(identifier: String, environment: [String: String]) throws(LinuxFilesError) -> String {
let directories = try LinuxFiles.directories(identifier: identifier, resources: nil, environment: environment)
// `documents` is always there; it's `<base>/Documents`.
let documents = directories[.documents]!
return String(documents.dropLast("/Documents".count)) + "/Stores"
}
}
Loading
Loading