ja
ee592cc21b
Hyprland 0.53+ requires launching via start-hyprland (watchdog) for proper crash diagnostics and signal handling. Without it a warning banner appears on login. Override package-managed hyprland.desktop with local copy pointing to start-hyprland. XDG_DATA_DIRS priority ensures the override wins without modifying system files. - ansible/roles/hyprland/tasks/main.yml: manage override in ~/.local/share/wayland-sessions/ - docs/adr/0004-start-hyprland-override.md: full decision record - docs/hyprland-uwsm.md: document override behavior
73 lines
2.9 KiB
Markdown
73 lines
2.9 KiB
Markdown
---
|
||
description: >-
|
||
Override the package-managed hyprland.desktop with a local copy that points
|
||
to start-hyprland (watchdog binary), ensuring Hyprland launches with proper
|
||
crash diagnostics, signal handling, and XDG portal support via uwsm.
|
||
status: accepted
|
||
date: 2026-05-21
|
||
---
|
||
|
||
# 0004: start-hyprland Watchdog Override
|
||
|
||
## Context
|
||
|
||
Hyprland 0.53+ ships `start-hyprland`, a watchdog binary that monitors the
|
||
compositor process, collects crash diagnostics (crash reports, memory dumps),
|
||
and ensures proper signal handling. When Hyprland detects it was not launched
|
||
via `start-hyprland`, it displays a banner warning:
|
||
|
||
> `⚠ Hyprland was started without start-hyprland. This is highly not
|
||
> recommended unless you are in a debugging environment.`
|
||
|
||
Our setup uses: greetd → tuigreet → `uwsm start -e -D Hyprland hyprland.desktop`
|
||
|
||
uwsm reads the `.desktop` file's `Exec=` field and spawns that binary inside
|
||
a systemd user session. The package-provided `hyprland.desktop` has
|
||
`Exec=Hyprland` (direct binary), bypassing the watchdog.
|
||
|
||
### Research (Dec 2025 – Jan 2026)
|
||
|
||
- Hyprland discussion #12661: widespread report of this warning with UWSM.
|
||
- UWSM maintainer Vladimir-csp confirmed: "I'd recommend feeding
|
||
`hyprland.desktop` to uwsm" with the watchdog binary.
|
||
- fufexan (Hyprland maintainer) acknowledged the incompatibility; no upstream
|
||
fix landed as of Jan 2026.
|
||
- Community consensus: point `.desktop` Exec to `start-hyprland` via local
|
||
override to preserve uwsm session management while enabling the watchdog.
|
||
|
||
## Decision
|
||
|
||
Create a local override at `~/.local/share/wayland-sessions/hyprland.desktop`
|
||
pointing to `start-hyprland`.
|
||
|
||
### Why local override (not system-wide)?
|
||
|
||
- The system file (`/usr/share/wayland-sessions/hyprland.desktop`) is owned by
|
||
the `hyprland` package and gets overwritten on updates.
|
||
- `~/.local/share` has higher XDG_DATA_DIRS priority than `/usr/share`, so
|
||
greetd/tuigreet discover the override first without touching system files.
|
||
- Ansible manages the override idempotently.
|
||
|
||
### Why not modify greetd's command?
|
||
|
||
The greetd command (`uwsm start -e -D Hyprland hyprland.desktop`) references
|
||
`hyprland.desktop` generically. Changing the greeting command to
|
||
`start-hyprland` directly would bypass uwsm entirely. The override approach
|
||
keeps the uwsm session management intact while fixing the watchdog issue.
|
||
|
||
## Status
|
||
|
||
Implemented in Ansible role `hyprland/tasks/main.yml`:
|
||
- Task registers the override at `~/.local/share/wayland-sessions/hyprland.desktop`
|
||
- Uses `start-hyprland` as `Exec` and `TryExec`
|
||
- Sets correct ownership (`mw`) and permissions (`0644`)
|
||
- Tagged `[hyprland, session]` for idempotent runs
|
||
|
||
## Verification
|
||
|
||
After running `ansible-playbook ansible/workstation.yml`:
|
||
1. `cat ~/.local/share/wayland-sessions/hyprland.desktop` should show
|
||
`Exec=start-hyprland`
|
||
2. Next login: the warning banner should no longer appear.
|
||
3. `ps aux | grep start-hyprland` should show the watchdog parent process.
|