Some checks are pending
ci / test (push) Waiting to run
- 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.
122 lines
6.8 KiB
Markdown
122 lines
6.8 KiB
Markdown
# 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` |
|
|
|
|
- `mangowm` depends on the **wlroots 0.20 slot** and `scenefx: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_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. **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.
|
|
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. **Two session entry points, one shell each.** `/usr/share/wayland-sessions`
|
|
gets `phoebus-mango.desktop` (default when the Mango profile is installed)
|
|
and `phoebus-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.
|
|
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 default desktop (explicit owner decision,
|
|
2026-09-21).** `desktop.profile` defaults to `mango`, Flatpak is on by
|
|
default, and the default login experience selects the Mango session.
|
|
Explicit values — including `none` and `dwl` — 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. `dwl` remains 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_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".
|