This branch is a frozen, hardware-validated baseline of Cage, maintained by the BLOSSOM project as a vendored compositor dependency.

• Upstream is the original project. All compositor code, design, and prior history here belong to Cage's own authors — see cage-kiosk/cage for the real upstream, and LICENSE (MIT, unmodified) below.
• This baseline starts from upstream tag v0.1.4 (via the Debian/Ubuntu-patched cage 0.1.4-3 source package, which carries one packaging patch — Upgrade-to-wlroots-0.15.patch — to build against wlroots 0.15; that patch is included and attributed in git history here, not authored by us).
• On top of that, four fixes are ours, found and validated independently on real hardware (see git log on this branch for the exact commits and reasoning in each message):
  1. output: fall back to the first advertised mode when no mode is flagged preferred by the driver, instead of silently leaving the output at 0×0.
  2. cage: guard wl_display_terminate() so it's only ever invoked once during shutdown.
  3. output: route the last-output-destroyed shutdown path through that same guard.
  4. cage: fix the signal handler receiving the address of the wl_display pointer instead of the pointer itself — the actual root cause of a 100%-reproducible crash on every SIGTERM/SIGINT, confirmed via a gdb backtrace, not guessed.

We independently diagnosed both of these against v0.1.4, then found upstream had already fixed the same underlying issues in v0.2.0 (2024-08-27/28) — commit eaeab71 ("cage: fix SIGINT/SIGTERM handler data") for the pointer bug, and 412c11e ("cage: fix abort on shutdown") for a related, deeper libwayland-level edge case, plus a broader output-state rewrite (8a00921, 3da3ec0) that supersedes our mode-fallback patch with a more thorough version (it tests every mode, not just the first one).

This is not a claim that current upstream Cage contains these bugs. It doesn't. This baseline exists because we were, at the time, running the older v0.1.4 line (as packaged by Ubuntu 22.04's universe repo, which had not — and still has not, as of this baseline's date — picked up anything past 0.1.4-3), and needed a fixed, reproducible build of that line rather than an upstream version jump. If your own cage is v0.2.0 or newer, none of this applies to you.

Tested on real hardware, not just built: NVIDIA GeForce RTX 4070, proprietary driver 580.119.02, kernel 6.17.9, nvidia-drm.modeset=1. Validation ran cage from a genuine, freshly-authenticated Linux login session on an otherwise-unused virtual terminal (not nested inside an existing desktop session, and with that desktop session fully stopped first so cage had exclusive access to the DRM device) — confirming real DRM/KMS + NVIDIA rendering, visually observed on the physical display, and a clean shutdown on SIGTERM (no crash, no core dump).

See BASELINE-MANIFEST.md for the exact dependency versions this was built and validated against, and the "Building and running Cage" section below for generic build instructions (unchanged from upstream — this baseline doesn't change how Cage is built, only what a few lines of its own code do).

This is Cage, a Wayland kiosk. A kiosk runs a single, maximized application.

This README is only relevant for development resources and instructions. For a description of Cage and installation instructions for end-users, please see its project page and the Wiki.

Releases are signed with 6EBC43B1 and published on GitHub.

You can build Cage with the meson build system. It requires wayland, wlroots, and xkbcommon to be installed. Optionally, install scdoc for manual pages. Note that Cage is developed against the latest tag of wlroots, in order to not constantly chase breaking changes as soon as they occur.

Simply execute the following steps to build Cage:

$ meson build
$ ninja -C build

By default, this builds a debug build. To build a release build, use meson build --buildtype=release.

Cage comes with compile-time support for XWayland. To enable this, first make sure that your version of wlroots is compiled with this option. Then, add -Dxwayland=true to the meson command above. Note that you'll need to have the XWayland binary installed on your system for this to work.

You can run Cage by running ./build/cage APPLICATION. If you run it from within an existing X11 or Wayland session, it will open in a virtual output as a window in your existing session. If you run it at a TTY, it'll run with the KMS+DRM backend. In debug mode (default build type with Meson), press Alt+Esc to quit. For more configuration options, see Configuration.

Cage is based on the annotated source of tinywl and rootston.

For any bug, please create an issue on GitHub.

Please see LICENSE on GitHub.

Copyright © 2018-2020 Jente Hidskes dev@hjdskes.nl