xiOS | Contributing

Where things live

x11/wayland: The compositor, iosc, plus the EGL shim, the Mutter iOS backend, and the small daemons that bridge hardware.
x11/apps: The Swift side: Xios.app, the per-window native host, the iosc shell, and the session tooling.
x11/ports and x11/linux-build: Everything cross-compiled from upstream source: patch series per port, recipes, and the build drivers that run them in Docker.
x11/packages: Packages we wrote ourselves, including the flavor metas.
x11/docs: Plans, per-subsystem handoff notes, and device snapshots. Most of this site is downstream of those documents.
bin: Repo generation, the publish pipeline and its gates.

Proving it on hardware

Nothing here is really done until it has run on an iPad. A cross-compile that links is not evidence, a package that installs is not evidence, and a screenshot of a desktop that might be a stale frame is worse than no evidence. So there is a harness for it: xios-device wraps the SSH details and the on-device helpers, and writes what it collects into a timestamped evidence directory.

xios-devicehost side

$ bin/xios-device doctor # host tools, SSH, on-device helpers

$ bin/xios-device session kde

$ bin/xios-device app konsole

$ bin/xios-device shot

shot is the interesting one, because capturing a screen on a device like this can lie to you in several ways. It tries grim against the Wayland output first, falls back to a screencopy client of our own, and can fall back again to a host-side capture over the pairing connection. It also runs a pixel probe and counts what is actually non-black, so you can measure whether the desktop rendered instead of squinting at it, and collects the status files and logs next to the image.

There is a matching pair of smoke drivers for app waves and for the KDE session, which launch a client, wait, capture, and diagnose the failure if it never mapped.

Say what you actually saw

Device reports in this project are expected to distinguish built, installed, launched and verified. "Should work" is not one of those states, and the difference between them is most of what the handoff notes in x11/docs are for.

Conventions to pick up early

+iosN versions: Anything rebuilt from upstream carries a marker on the Debian version, like 6.1.5+ios27. Packages that are ours carry no marker. Reading a version tells you which kind you are looking at, and how many times we have had to touch it.
Patch series, not sed: Upstream changes belong in a quilt-style series next to the port. Procedural edits inside build scripts exist, but they are debt, and they are tracked as debt.
Sign for the capability: A binary that touches the GPU or imports another process's IOSurface needs the matching entitlements at signing time. See the GPU path.
Never shadow the bootstrap: Publishing a package that replaces one Procursus already provides is how this project once bricked apt and sshd on its own test device. The publish step now refuses that unless the replacement is a genuine drop-in superset with a written waiver.
Rootless only: Everything bakes /var/jb. A rootful target is designed and partly scaffolded, but nothing rootful is built or published, and the converted packages refuse to produce one until a rootful server has been smoke-tested on hardware.

Filing something useful

Issues go to GitHub. The details that make a report actionable here are the device and iOS version, the jailbreak, the flavor and package versions, whether the screen was awake, and the compositor and session logs from /var/jb/tmp. If you can run the harness, xios-device collect gathers most of that for you.

Glossary

Names this project invented, which appear in logs, package lists and everywhere on this site.

iosc: this project's clean-room Wayland compositor, which composites into the output IOSurface
ioscd: the root daemon that starts, switches and supervises desktop sessions
xios-session: the command that launches a desktop flavor and tears the previous one down
xios-device: the host-side harness that drives the iPad over SSH and collects evidence
display slot: a named desktop with its own Wayland socket, config and status file
iosc_iosurface: the private Wayland protocol that passes IOSurfaces between clients and the compositor
rootless: a jailbreak layout where everything installs under /var/jb instead of /
rootful: the older jailbreak layout that writes directly into the system root
Procursus: the macOS-hosted bootstrap and cross-compile system this build stands on
shadowing: publishing a package that replaces one the bootstrap already provides
MinimumOSVersion: the iOS floor stamped into a binary, which the store uses to hide it from older devices