Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
36 commits
Select commit Hold shift + click to select a range
a648980
Moved the Linux targets into the host, for the runner
colemancda Nov 19, 2026
856fe74
Re-exported the host's targets and install locations from the packager
colemancda Nov 19, 2026
f3cdf20
Loaded an app's libapp.so after checking it against its signature
colemancda Nov 19, 2026
be7c979
Found installed apps by their identifier
colemancda Nov 19, 2026
45bd2f0
Defined arc4random_buf for musl too
colemancda Nov 19, 2026
7d63798
Declared naming the process after the app
colemancda Nov 19, 2026
59bba3d
Named the process after the app
colemancda Nov 19, 2026
e5bc56c
Listed what the runner exports for apps' libraries
colemancda Nov 19, 2026
2ef81e9
Made linux-app-host the runner
colemancda Nov 19, 2026
cd51fd0
Named GLES's library for the runner to preload
colemancda Nov 19, 2026
205a63f
Said the runner loads GLES for an app that draws
colemancda Nov 19, 2026
6b7c95e
Loaded the app's library at launch, by bundle or identifier
colemancda Nov 19, 2026
4e6d5e9
Stopped building a host for each app
colemancda Nov 19, 2026
183c573
Located the runner, and built it for ports
colemancda Nov 19, 2026
633b231
Took a slice's libapp.so
colemancda Nov 19, 2026
2fd8f90
Validated libapp.so and required a signature
colemancda Nov 19, 2026
963bd66
Passed arguments to the desktop entry's program
colemancda Nov 19, 2026
b749e50
Installed apps by thinning their bundles, with nothing built
colemancda Nov 19, 2026
02e7f67
Made ports carry the runner and libapp.so
colemancda Nov 19, 2026
1e3401a
Made linux-app install for the runner
colemancda Nov 19, 2026
32ef2dc
Exported rt.h from the runner and linked no app
colemancda Nov 19, 2026
678a2fb
Tested loading and refusing apps' libraries
colemancda Nov 19, 2026
3c4fea9
Gave the test bundles libapp.so slices
colemancda Nov 19, 2026
06e07a8
Tested thinning, installing for the runner and validating libapp.so
colemancda Nov 19, 2026
d4aaa32
Tested that a port carries each architecture's libapp.so
colemancda Nov 19, 2026
45c8c12
Ran bundles in the runner
colemancda Nov 19, 2026
b138f1f
Stopped passing an app library to builds
colemancda Nov 19, 2026
84d833f
Said WABT is for AppRuntime's wasm2c shim
colemancda Nov 19, 2026
ad0aacf
Documented the runner
colemancda Nov 19, 2026
f8733bf
Documented installing for the runner
colemancda Nov 19, 2026
3ee8a36
Documented ports carrying the runner
colemancda Nov 19, 2026
7902f75
Described the runner and installing apps for it
colemancda Nov 19, 2026
ba843a9
Gave the test bundles only libapp.so, as Linux slices now are
colemancda Nov 19, 2026
b5869d5
Said a Linux slice is only its libapp.so
colemancda Nov 19, 2026
8ca4c1c
Stopped mentioning libapp.a among what thinning drops
colemancda Nov 19, 2026
eed4037
Said AppRuntime's wasm2c shim makes a slice's libapp.so
colemancda Nov 19, 2026
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
3 changes: 1 addition & 2 deletions Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,7 @@
# Debian 13, SDL3, Cairo, FreeType, fontconfig and Wayland for Cacao, a font,
# Mesa's EGL and GLES 2.0 for GL surfaces (llvmpipe without a GPU), WPE WebKit
# and its FreeDesktop.org backend for web views, which the host loads at run
# time, Python for AppRuntime's scripts, and WABT for the packager's wasm2c
# engine.
# time, Python for AppRuntime's scripts, and WABT for its wasm2c shim.
#
# Debian rather than Ubuntu: Ubuntu 26.04 doesn't package WPE WebKit. SDL is
# built from source: Debian's is 3.2, and PureSwift/SDL needs 3.4.
Expand Down
128 changes: 64 additions & 64 deletions Documentation/Packager.md
Original file line number Diff line number Diff line change
@@ -1,107 +1,107 @@
# Packager — Design

**Status:** implemented, except Flatpak, AppImage and cross-building (§5).
`ExampleUI` packages from its bundle with either engine, and the packaged
app runs.

`linux-app` turns a universal bundle into a Linux app: phase 2 of the
[plan](Plan.md). It never compiles guest Swift. The bundle already has the
guest's code, as a sealed `libapp.a` per target and `App.wasm`, and its
`Info.plist` has the portable keys AppRuntime's manifest stage wrote
(DarwinAppRuntime's `ManifestPackager.md` §1).
**Status:** implemented, except Flatpak and AppImage (§5). `ExampleUI`,
`ExampleGL` and `ExampleModel` install from their bundles and run in the
runner.

`linux-app` installs a universal bundle's app for the runner,
`linux-app-host` ([Plan.md](Plan.md) §4): phase 2 of the plan. It never
compiles or links anything. The bundle has the guest's code, as a
`libapp.so` per Linux target, which `guest.py` linked when it built the
bundle (AppRuntime's `DynamicRuntime.md` §7.5), and its `Info.plist` has
the portable keys AppRuntime's manifest stage wrote (DarwinAppRuntime's
`ManifestPackager.md` §1). So a device needs the runner, and no compiler,
linker or SwiftPM; the runner and the OS update on their own, and the app's
ABI is what stays put.

```sh
linux-app validate App.app [--target linux-arm64]
linux-app package App.app [--target …] [--engine slice|wasm2c] [--output DIR] [--archive]
linux-app install App.app [--prefix ~/.local]
linux-app run App.app [-- host arguments]
linux-app package App.app [--target …] [--output DIR] [--archive]
linux-app install App.app [--prefix ~/.local] [--runner PATH]
linux-app run App.app [--runner PATH] [-- URL]
```

## 1. Validation

`validate`, and every other command first, checks the bundle against this
host:
host. The runner checks the ABI, the contracts and the library's signature
again at every launch, since it may have changed since.

| Check | Failure |
|---|---|
| `Info.plist` has the RT keys, a reverse-DNS `CFBundleIdentifier` and a single-component `CFBundleExecutable` | error |
| `RTABIVersion` ≤ the host's | error |
| Each `RTContracts` entry is implemented here, as the same kind | error; `--allow-missing-contracts` makes it a warning, and the guest sees the contract as absent |
| … at the same version or later | warning: methods added later resolve as absent |
| `_CodeSignature/CodeResources` matches every file's SHA-256 | error: a corrupt or tampered bundle |
| The engine's input: `lib/<target>/libapp.a` for `slice`, `wasm32/App.wasm` for `wasm2c` | error |
| The slice is an archive of ELF objects for the target's machine | error |
| The bundle has `_CodeSignature/CodeResources`, and it matches every file's SHA-256 | error: the runner loads no library its bundle doesn't vouch for |
| `lib/<target>/libapp.so` is there, and is a shared library for the target's machine and word size | error |
| A declared capability this host has no contract for (location, motion, NFC, …) | warning |

## 2. Targets and engines
`guest.py` has checked the rest of the library when it built it: that it
names no other library, binds as it loads, exports the three guest exports
only, and leaves undefined only what a runner supplies.

The target is the build machine's (`linux-arm64` on aarch64, `linux-x86_64`
on x86_64); cross-building waits on Swift SDKs for Linux targets.
## 2. Targets

- **`slice`** (the default when the bundle has one) links the bundle's
`lib/<target>/libapp.a`.
- **`wasm2c`** (the default otherwise) runs AppRuntime's
`Scripts/wasm2c-shim.py build` on `App.wasm`, which needs WABT (`apt
install wabt`) and clang, and links its `libapp.a` the same way.
Ubuntu's `wabt` 1.0.36 leaves out two files its runtime source includes
(`wasm-rt-impl-tableops.inc`, `wasm-rt-mem-impl-helper.inc`); the
`Dockerfile` adds them from the same release. The
AppRuntime checkout comes from `--appruntime`, `APPRUNTIME_PATH`, or the
one SwiftPM resolved for the host build.
The target is this machine's (`linux-arm64` on aarch64, `linux-x86_64` on
x86_64, `linux-armv7` on armv7l), or `--target`'s. A bundle carries a
`libapp.so` for each target it was built for.

## 3. Building the host
There's no wasm2c engine: it needs a C compiler, which a device doesn't
have. A bundle without a slice for a target gets one where there's a
toolchain, before it's installed: AppRuntime's
`Scripts/wasm2c-shim.py slice --bundle App.app --target linux-arm64` makes
`lib/linux-arm64/libapp.so` from `wasm32/App.wasm` and re-signs the bundle,
and the runner loads it like a native slice. Running `App.wasm` itself is
for an engine in the runner.

As on Darwin, the host is built per app from a generated SwiftPM package in
the work directory (`.build/linux-app/<identifier>/<target>`, reused
between builds):
## 3. The runner

```
Package.swift an executable product, LinuxAppMain, depending on this
package's LinuxHostApp, linking the app's libapp.a; the
tree names its copy CFBundleExecutable
Sources/<Executable>/main.swift
HostApp.main(AppEntryPoints(main: rt_main, …))
```
Apps don't get a program of their own: every app runs in `linux-app-host`,
installed once (Plan.md §4). `install` and `run` find it from `--runner`,
`LINUXAPPRUNTIME_RUNNER`, beside `linux-app`, or on `PATH`.

`swift build -c release` (or `--configuration debug`) builds it. The app's library is copied in as `lib/libapp-<hash>.a`: SwiftPM
doesn't relink when a library named in linker flags changes, but a new name
changes the manifest. This
package is found from `--host-package`, `LINUXAPPRUNTIME_PATH`, or the
source tree `linux-app` was built from.
A PortMaster port is the exception: a handheld has no runner installed, so
the port carries one, built by `linux-app portmaster` for the handheld's
glibc ([PortMaster.md](PortMaster.md)). It's the same program for every
app.

## 4. The app

`package` writes an install tree under `--output` (default
`.build/linux-app/<identifier>/<target>/out`):
`install` writes the app into `--prefix` (`~/.local` by default):

```
bin/<executable> → ../lib/<identifier>/<executable>
lib/<identifier>/<executable> the host, linked with the app
lib/<identifier>/App.app/Info.plist the bundle, without lib/ and wasm32/
lib/<identifier>/App.app/resources/…
lib/linux-app/<identifier>.app/Info.plist the bundle, thinned:
lib/linux-app/<identifier>.app/resources/…
lib/linux-app/<identifier>.app/icon.png
lib/linux-app/<identifier>.app/_CodeSignature/CodeResources
lib/linux-app/<identifier>.app/lib/<target>/libapp.so this target's only
share/applications/<identifier>.desktop
share/icons/hicolor/256x256/apps/<identifier>.png from the bundle's icon.png
share/icons/hicolor/256x256/apps/<identifier>.png from the bundle's icon.png
```

The host finds `App.app` next to its executable, through the `bin/`
symlink. `--archive` also writes `<identifier>-<version>-<target>.tar.gz`
of the tree.
Thinning drops the other targets' libraries and `App.wasm`.
The signature is kept as it was: every file still in the bundle matches it,
and the runner checks the library against it. The new copy is written
beside the old one and replaces it whole.

The desktop entry names the app (`CFBundleName`), runs it (`Exec`, with
The desktop entry names the app (`CFBundleName`), runs it
(`Exec=<runner> <identifier> %u`, the runner by its absolute path, with
`%u` so URLs reach `Application.open`), and matches its windows: the host
sets SDL's app metadata, so the window's Wayland app ID and X11 class are
the identifier, which `StartupWMClass` repeats.
the identifier, which `StartupWMClass` repeats. `install` refreshes the
desktop database when `update-desktop-database` is there.

`install` packages and copies the tree into `--prefix` (`~/.local` by
default), with `Exec` an absolute path, and refreshes the desktop database
when `update-desktop-database` is there. `run` packages a debug build into
the work directory and runs it.
`package` writes the same tree to `--output` (default
`.build/linux-app/<identifier>/<target>`) for a distribution's package,
with the runner named by `Exec` from `PATH`, and `--archive` also writes
`<identifier>-<version>-<target>.tar.gz` of it. `run` checks the bundle and
runs it in the runner as it is.

## 5. Later

- **Flatpak and AppImage.** A Flatpak manifest carries the capabilities as
sandbox permissions (`bluetooth` → `--system-talk-name=org.bluez`,
`network` → `--share=network`).
- **Localized names** in the desktop entry, from the bundle's
`<language>.lproj` tables.
- **Cross-building** for another architecture with a Swift SDK.
- **A read-only image** per app (squashfs), as AppRuntime's launcher
mounts them (§7.8 there).
105 changes: 76 additions & 29 deletions Documentation/Plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,11 @@ design, [Packager.md](Packager.md), and so do PortMaster ports,
- **PortMaster ports** don't build on Cacao yet: they need Cairo built for
their glibc, and Cacao options for fullscreen, scale and a drawn pointer
([PortMaster.md](PortMaster.md) §7).
- **One runner for every app.** `linux-app-host` loads an app's
`libapp.so` (AppRuntime's §7.5, §7.6) instead of being built per app
with its `libapp.a` linked in, so installing an app copies files and
needs no toolchain, and the runner and the OS update on their own while
the app's ABI stays put (§4).
- **Bluetooth** is tested against a fake bus that plays BlueZ's objects and
signals; it hasn't run against `bluetoothd` and a device.
- **AppRuntime's `guest.py bundle`** needed one fix to run on Linux: it
Expand All @@ -19,12 +24,13 @@ design, [Packager.md](Packager.md), and so do PortMaster ports,

The Linux host for [AppRuntime](https://github.com/PureSwift/AppRuntime)
apps, the counterpart of DarwinAppRuntime. An AppRuntime app is guest code
only: a universal bundle with `App.wasm` and native `libapp.a` slices
(`linux-arm64`, `linux-x86_64`, `linux-armv7`). This repository turns one
into a Linux program:
only: a universal bundle with `App.wasm` and a native slice for each Linux
target (`linux-arm64`, `linux-x86_64`, `linux-armv7`), a `libapp.so`. This
repository runs one on Linux:

- the **host runtime**: `main`, the event loop, the runtime core behind
`rt.h`, and the contract implementations over Linux services;
- the **runner**, `linux-app-host`: `main`, the event loop, the runtime core
behind `rt.h`, and the contract implementations over Linux services, into
which it loads an app's `libapp.so`;
- the **SwiftUI player**: DarwinAppRuntime's renderer of the SwiftUI
frontend's render IR, on Cacao's SwiftUI for Linux;
- **Bluetooth** over BlueZ's D-Bus API;
Expand All @@ -44,14 +50,14 @@ AppRuntime's contracts.
| In | Later |
|---|---|
| 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 |
| Native slices, loaded by the runner | `App.wasm`, in an engine in the runner; wasm2c for a target a bundle lacks, before it's installed |
| Wayland and X11 through SDL3; a headless driver for tests | Multiple windows |
| `Renderer`, `BluetoothCentral` and friends, GL surfaces, web views, files, settings, model stores, date and number formatting, the built-ins | Location (GeoClue), Device (UPower, sysfs), Networking (libcurl), Motion (iio-sensor-proxy), NFC (neard) |

## 2. Process model

```
┌────────────────────── app (one executable) ──────────────────────┐
┌──────────────────── linux-app-host (the runner) ─────────────────┐
│ LinuxHostApp main │
│ ├── runtime core: RuntimeCore + RuntimeNative (rt_* symbols) │
│ ├── MainLoop: timers, jobs from other threads │
Expand All @@ -60,7 +66,7 @@ AppRuntime's contracts.
│ ├── LinuxWebKit: WPE WebKit pages, frames in shared memory │
│ ├── LinuxUI: DarwinUI, render IR → SwiftUI views → events │
│ │ └── Cacao: SwiftUI, Silica/Cairo, SDL3 windows and input │
│ └── libapp.a: the app's sealed linux-arm64 / linux-x86_64 slice│
│ └── libapp.so: the app's slice, loaded from its bundle │
└──────────────────────────────────────────────────────────────────┘
```

Expand Down Expand Up @@ -112,22 +118,56 @@ every host written in Swift; this host registers them as they are:

## 4. Startup

1. Read the app's keys (`RTABIVersion`, `RTContracts`, `RTCapabilities`,
`CFBundleIdentifier`, version and build) from the universal bundle's
`Info.plist`: the path from `--bundle`, or `App.app` next to the
executable.
2. Check the ABI and contract versions (§7.6); refuse a newer ABI or a
contract this host lacks.
3. `NativeRuntime.shared.bindDirectly()`; set capabilities; set the clock.
4. Register the built-ins (`Permissions`, `Bundle`, `Application`) and each
module the app uses (`LinuxUI` for `Renderer`, `LinuxBluetooth`,
`LinuxGraphics`, `LinuxWebKit`).
5. Call `rt_main`. When the guest calls `Renderer.make`, the player adds
`linux-app-host` is the one program every app runs in. No app is linked
into it: it loads the app's `libapp.so`, which names no other library and
leaves undefined only `rt.h`, a few libc functions and, for an app that
draws, GLES 2.0 (AppRuntime's §7.5).

```
linux-app-host [--bundle] App.app | IDENTIFIER [[--open] URL]
```

1. Find the app: a bundle's path, or an installed app's identifier, looked
up as `<prefix>/lib/linux-app/<identifier>.app` in `~/.local`, the
runner's own prefix, `/usr/local` and `/usr` (`LINUXAPPRUNTIME_PREFIXES`
replaces the list). Without one, `LINUXAPPRUNTIME_BUNDLE`, or `App.app`
next to the executable, as a PortMaster port has it.
2. Name the process after the app (`PR_SET_NAME`, `CFBundleExecutable`),
so `ps` and `top` show it and not the runner.
3. Read the app's keys from its `Info.plist` and check the ABI and contract
versions (§7.6), at every launch: the runner may have changed since the
app was installed. A newer ABI or a contract this host lacks refuses it.
4. `NativeRuntime.shared.bindDirectly()`; set capabilities; set the clock.
Register the built-ins (`Permissions`, `Bundle`, `Application`) and each
module the app uses.
5. Load the library (`AppLibrary`):
- check `lib/<target>/libapp.so` against the bundle's
`_CodeSignature/CodeResources`, and load the bytes checked: the file is
opened once, hashed, and loaded through its descriptor
(`/proc/self/fd`);
- for an app whose contracts include `Surface`, load
`libGLESv2.so.2` into the global scope first;
- `dlopen` it. It binds every symbol as it loads, so one the runner
lacks refuses the app, by name;
- look up `rt_main`, `rt_dispatch` and `rt_finalize`.
6. Call `rt_main`. When the guest calls `Renderer.make`, the player adds
its scene; the first tree is there before `rt_main` returns.
6. Run Cacao's loop until the window closes, the window showing the first
7. Run Cacao's loop until the window closes, the window showing the first
scene (or, for an app with no renderer, the `MainLoop` until it's
interrupted).

What the runner's process supplies to the library:

- **`rt.h`.** RuntimeNative defines its functions in Swift (`@c`).
`linux-app-host` is linked with a dynamic list
(`Sources/LinuxAppHost/exports.list`) that exports `rt_*`, which keeps
them though nothing in the runner calls them.
- **libc's part.** The library binds to the C library the runner runs on,
glibc or musl. Where it lacks `arc4random_buf` (musl, glibc before 2.36),
`CLinuxHost` defines it and the runner exports it; its executable is
searched first, so that's the definition the app binds to.
- **GLES 2.0**, loaded as above.

## 5. The SwiftUI player

The player is DarwinAppRuntime's: `DarwinUI`, its renderer of the render IR
Expand Down Expand Up @@ -367,6 +407,11 @@ SQLite one, CoreModel-SQLite, with SQLite compiled in, so a device needs no
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.
- `LinuxHost`'s loader: libraries compiled by the test with the
toolchain's clang, in signed bundles: loaded, and their exports called;
refused unsigned, changed after signing, or not listed; a symbol the
process lacks named in the refusal; a library to preload that isn't
there. Where installed apps are found.
- `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,
Expand All @@ -377,10 +422,13 @@ SQLite one, CoreModel-SQLite, with SQLite compiled in, so a device needs no
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`. `ExampleModel`
the same way, launched twice on one container, with to-dos written into
- End to end: AppRuntime's `ExampleUI`, `ExampleGL` and `ExampleModel`
bundles, their `linux-arm64` `libapp.so` loaded by `linux-app-host` and
run headless with SDL's `offscreen` driver, each first frame saved with
`CACAO_SCREENSHOT`; `ExampleGL` with GLES loaded first. `ExampleModel`
installed with `linux-app install` and launched by its identifier,
shown by `ps` as `ExampleModel`, and refused once its library is
changed; and 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 All @@ -389,11 +437,10 @@ SQLite one, CoreModel-SQLite, with SQLite compiled in, so a device needs no

1. **Host runtime and player**: `LinuxHost`, `LinuxUI`, `LinuxBluetooth`,
`LinuxHostApp`; `ExampleUI` runs in Docker.
2. **Packager**: `linux-app` builds the host for a target triple, links the
bundle's slice (or wasm2c output), and writes an installable directory:
the executable, `Info.plist`, resources, a `.desktop` file and icon;
later Flatpak and AppImage, whose manifests carry the capabilities
(`--system-talk-name=org.bluez` for `bluetooth`).
2. **Packager**: `linux-app` checks an app and installs it: its bundle
thinned to the target's `libapp.so`, a `.desktop` file and icon, for
the runner; later Flatpak and AppImage, whose manifests carry the
capabilities (`--system-talk-name=org.bluez` for `bluetooth`).
3. **More contracts**: Location (GeoClue2), Device (UPower, sysfs),
Networking (libcurl or AsyncHTTPClient), Motion (iio-sensor-proxy),
NFC (neard). Formatting is done: AppRuntime's `RuntimeFormatting`
Expand Down
Loading
Loading