phoebus_os/docs/adr/0009-mango-dankmaterialshell-desktop.md
Phoebus fe8de3904b
Some checks are pending
ci / test (push) Waiting to run
refactor(desktop): unify desktop stack on Mango + DarkMaterial and excise standalone dwl
- Excised standalone dwl packages: gui-wm/dwl, waybar, wofi, mako, swaybg, swayidle, swaylock
- Removed standalone dwl session and helper assets: PHOEBUS_SESSION_SCRIPT, PHOEBUS_MENU_SCRIPT, PHOEBUS_LOCK_SCRIPT, PHOEBUS_IDLE_SCRIPT, WAYBAR_CONFIG, WAYBAR_STYLE, phoebus-dwl.desktop
- Consolidated DesktopProfile enum to Mango (default) and None (headless), rejecting legacy dwl configurations
- PHOEBUS_MANGO_SESSION_SCRIPT (/usr/local/bin/phoebus-session-mango) fails visibly/diagnostically on error without silent fallback
- Provided /usr/local/bin/phoebus-session as a direct wrapper to phoebus-session-mango
- Live ISO emitted assets reduced from 24 to 17 and verified clean
2026-09-24 15:49:15 -07:00

6.5 KiB

ADR 0009: Mango + DankMaterialShell desktop option

  • Status: Accepted
  • Date: 2026-09-21

Context

Phoebus's original desktop was a hand-assembled dwl session (dwl, waybar, wofi, mako, swaybg, swayidle, swaylock, polkit-gnome). It was lightweight, but required manual assembly and duplicated effort. Mango (gui-wm/mangowm, a wlroots dwl derivative) plus DankMaterialShell (DMS, a Quickshell shell providing panel, launcher, notifications, network/Bluetooth/audio controls, locking, idle and display management) is a complete, coherent desktop that fits the Wayland/systemd/PipeWire architecture.

The decision was made to make Mango + DarkMaterial the sole, canonical desktop experience for Phoebus OS, completely retiring standalone dwl and eliminating any secondary or fallback desktop paths.

Upstream and packaging facts (verified 2026-09-21)

Component Package Version Source License Keyword
Compositor gui-wm/mangowm 0.17.2 GURU (community) CC0-1.0 / GPL-3+ / MIT ~amd64
Shell gui-apps/dankmaterialshell 1.5.3 GURU (community) MIT ~amd64
Framework gui-apps/quickshell 0.3.1 GURU (community) LGPL-3 ~amd64
Search gui-apps/danksearch 0.3.2 GURU (community) MIT ~amd64
Effects lib gui-libs/scenefx 0.5 GURU (community) MIT ~amd64
  • mangowm depends on the wlroots 0.20 slot and scenefx:0.5.
  • gui-wm/dwl (wlroots 0.18) and standalone dwl helpers (waybar, wofi, mako, swaybg, swayidle, swaylock) are completely removed from the desktop package set and session configurations.
  • DMS is installed from DMS's released tarballs (its ebuild SRC_URI points at GitHub release assets); no live/git package is used.
  • GURU is git-only, so dev-vcs/git is installed from the main tree before the overlay is synced.
  • Upstream (Quickshell/DMS) requires Qt 6.6+, which the selected default/linux/amd64/23.0/desktop/systemd profile provides.

Decision

  1. One canonical desktop profile: desktop.profile = "mango" installs Mango + DMS. Standalone dwl has been excised; none remains for headless installations.
  2. Portage owns the stack. The installer writes repos.conf for GURU (git), installs dev-vcs/git, syncs GURU with emaint sync -r guru, and installs the packages with emerge. There is no curl | sh, no Nix, and no live package.
  3. Testing keywords are scoped. package.accept_keywords/phoebus lists only gui-wm/mangowm, gui-apps/dankmaterialshell, gui-apps/danksearch, gui-apps/quickshell and gui-libs/scenefx. ~amd64 is never enabled globally, and Portage is not silently auto-unmasked: additional ~amd64 dependencies must be reviewed and added deliberately.
  4. Single canonical session entry point. /usr/share/wayland-sessions ships phoebus-mango.desktop. The session starts only mango, DMS (panel, launcher, notifications, lock, idle), and Quickshell's polkit agent. No competing standalone dwl session entry or helpers are shipped.
  5. User configuration is separate from packaged defaults. The session seeds ~/.config/mango/config.conf from /etc/xdg/mango/config.conf only when absent, and DMS manages ~/.config/mango/dms/*.conf. Portage upgrades never overwrite user files.
  6. Administration stays behind sys. DMS's system-update controls are not wired up; updates continue through sys/Portage. The assistant is reachable from a launcher (phoebus-assistant) that simply runs sys ask, keeping the typed-action and approval boundary.
  7. Mango + DankMaterialShell is the canonical Phoebus desktop. desktop.profile defaults to mango, Flatpak is on by default, and greetd launches the Mango session upon authentication. Silent fallback to dwl is prohibited: any failure fails visibly and diagnostically. Recovery consoles (serial and TTY) remain available.

Live medium

The installer ISO boots into the same Mango + DankMaterialShell desktop. The live image is a Debian testing rootfs (wlroots 0.20, scenefx 0.5, quickshell) plus a pinned Mango source build and a pinned DMS release; it autologins as an unprivileged phoebus user, exposes a serial/VT recovery console, and provides an "Install Phoebus" launcher that opens the uninstrumented installer UI. The installed target is Gentoo and never receives Debian packages. See installer/live/README.md. The live and installed login configurations are generated from the same assets but differ in one property: the live config has [initial_session] (autologin) and the installed config never does.

Update procedure

GURU is synced by emaint sync -r guru on every Portage sync. To move to a new upstream release, bump the reviewed versions in the keyword list only after emerge --pretend confirms the dependency set, then rebuild the profile's packages. The overlay is community-maintained; its ebuilds are attributed to their maintainers (see each metadata.xml).

Consequences and risks

  • The Mango install pulls Qt, Quickshell and scenefx, so it is much heavier to build than the dwl session; a matching signed binhost does not exist for these GURU packages, so they compile.
  • GURU is a community overlay: provenance is documented but it is not the main Gentoo tree. The keyword scope keeps the risk limited to the listed packages.
  • DMS is a fast-moving project; the integration pins a reviewed release and documents the update path rather than tracking 9999.
  • If DMS's polkit integration does not cover every prompt, a fallback PHOEBUS_POLKIT_AGENT hook is available but defaults off to avoid two agents.

Verification status

Unit and source-level tests cover the default configuration and explicit overrides, the profile and package set, keyword scope, generated session scripts, config seeding, the two session entries, the greetd configuration, the live/installed login separation, and the live ISO's desktop-payload guards. The ISO is built by installer/live/build.sh (see the evidence recorded in docs/VM-BOOT-VERIFICATION.md).

Graphical-VM acceptance gates (real seat, panel/launcher/notifications/polkit, lock/unlock, shell restart, logout cleanup, suspend/resume, Flatpak portals, idle/memory under load) are tracked in docs/VM-BOOT-VERIFICATION.md and are not all passed. The default is set by explicit owner decision, not because those gates passed; docs/STATUS.md distinguishes "default in configuration", "successfully built" and "graphically verified".