- desktop.profile defaults to mango with Flatpak on; explicit none/minimal/dwl/ full still win. The plan shows the selected session. - Installed login uses greetd + tuigreet (authentication required, Mango default, dwl selectable); live autologin is a separate live-only configuration. - installer/live/build.sh builds a rootless Debian testing rootfs with Mango (pinned source build), DankMaterialShell (pinned SHA-256 release), Quickshell, scenefx, Qt Wayland and greetd, then splices it into the base Debian-Live boot equipment. Live autologin, an Install Phoebus launcher and a serial/VT recovery console are included and the build fails clearly if a desktop component is missing. Verified in a graphical seat-providing VM (Mango + DMS + Quickshell; DMS panel captured). - Shared desktop assets emitted by phoebus-installer --emit-asset, a graphical VM driver (live-driver.py), and regression tests for defaults/overrides, login, live/installed separation and the live ISO guards. - Docs updated: ADR 0005/0009, STATUS, HANDOFF, CHANGELOG, ROADMAP, DEVELOPMENT and VM-BOOT-VERIFICATION.
6.8 KiB
ADR 0009: Mango + DankMaterialShell desktop option
- Status: Accepted
- Date: 2026-09-21
Context
Phoebus's flagship desktop is a hand-assembled dwl session (dwl, waybar, wofi,
mako, swaybg, swayidle, swaylock, polkit-gnome). It is lightweight and proven,
but it requires the user to assemble everyday desktop functions. 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 task is to offer it as an explicit profile, keep dwl as a fallback, and promote Mango to the default only after verification.
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 |
mangowmdepends on the wlroots 0.20 slot andscenefx:0.5.gui-wm/dwl(the fallback) depends on the wlroots 0.18 slot. The two are different slots, so dwl and mangowm install side by side without a forced wlroots upgrade.- DMS is installed from DMS's released tarballs (its ebuild
SRC_URIpoints at GitHub release assets); no live/git package is used. - GURU is git-only, so
dev-vcs/gitis 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/systemdprofile provides.
Decision
- A new explicit profile
desktop.profile = "mango"installs Mango + DMS and also the dwl session as a fallback. Legacy values (none,minimal,dwl,full) keep their exact meaning. - Portage owns the stack. The installer writes
repos.conffor GURU (git), installsdev-vcs/git, syncs GURU withemaint sync -r guru, and installs the packages withemerge. There is nocurl | sh, no Nix, and no live package. - Testing keywords are scoped.
package.accept_keywords/phoebuslists onlygui-wm/mangowm,gui-apps/dankmaterialshell,gui-apps/danksearch,gui-apps/quickshellandgui-libs/scenefx.~amd64is never enabled globally, and Portage is not silently auto-unmasked: additional~amd64dependencies must be reviewed and added deliberately. - Two session entry points, one shell each.
/usr/share/wayland-sessionsgetsphoebus-mango.desktop(default when the Mango profile is installed) andphoebus-dwl.desktop(fallback). The Mango session starts only mango, DMS (panel, launcher, notifications, lock, idle), and the shell's polkit agent; it never starts waybar/mako/swaybg/swayidle/swaylock. The dwl session is unchanged. - User configuration is separate from packaged defaults. The session seeds
~/.config/mango/config.conffrom/etc/xdg/mango/config.confonly when absent, and DMS manages~/.config/mango/dms/*.conf. Portage upgrades never overwrite user files. - Administration stays behind
sys. DMS's system-update controls are not wired up; updates continue throughsys/Portage. The assistant is reachable from a launcher (phoebus-assistant) that simply runssys ask, keeping the typed-action and approval boundary. - Mango + DankMaterialShell is the default desktop (explicit owner decision,
2026-09-21).
desktop.profiledefaults tomango, Flatpak is on by default, and the default login experience selects the Mango session. Explicit values — includingnoneanddwl— are still respected. This supersedes the earlier "verify before default promotion" policy; the graphical-VM gates below are still tracked honestly, but they no longer gate the default.dwlremains shipped as a fallback and selectable at login.
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_AGENThook 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".