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
83 lines
2.9 KiB
Markdown
83 lines
2.9 KiB
Markdown
# Hyprland Configuration - uwsm Integration
|
|
|
|
## Architecture
|
|
|
|
Session management uses **UWSM** (Universal Wayland Session Manager) wrapping Hyprland in systemd user services.
|
|
|
|
```
|
|
greetd → tuigreet → uwsm start → systemd user session → Hyprland
|
|
↓
|
|
systemd units: hyprpaper, waybar, dunst, hypridle, hyprlauncher, cliphist
|
|
XDG autostart: Nextcloud, JetBrains Toolbox, Flameshot, etc.
|
|
```
|
|
|
|
## Session Services
|
|
|
|
All session services are managed via systemd user units (`~/.config/systemd/user/*.service`):
|
|
|
|
| Service | Purpose | Status |
|
|
|---------|---------|--------|
|
|
| `hyprpaper.service` | Wallpaper daemon | active |
|
|
| `waybar.service` | Status bar | active |
|
|
| `dunst.service` | Notification daemon | active |
|
|
| `hypridle.service` | Idle/screenlock control | active |
|
|
| `hyprlauncher.service` | App launcher daemon | active |
|
|
| `cliphist.service` | Clipboard history store | active |
|
|
|
|
### Management Commands
|
|
|
|
```bash
|
|
# Check all session services
|
|
systemctl --user list-units | grep -E 'hypr|waybar|dunst|cliphist'
|
|
|
|
# Restart a specific service
|
|
systemctl --user restart waybar.service
|
|
|
|
# View logs
|
|
journalctl --user -u waybar.service -f
|
|
```
|
|
|
|
## Launchers
|
|
|
|
| Component | Tool | Keybind |
|
|
|-----------|------|---------|
|
|
| App Launcher | hyprlauncher | SUPER+D |
|
|
| Keybind Menu | hyprlauncher -o (piped) | SUPER+CTRL+K |
|
|
|
|
hypr launcher config: `~/.config/hypr/hyprlauncher.conf`
|
|
- `desktop_launch_prefix = uwsm app --` (proper systemd scoping)
|
|
- Cache enabled for frequency-based sorting
|
|
- Finders: desktop (default), math (=), unicode (.), font (')
|
|
|
|
## Login Manager
|
|
|
|
**greetd** with **tuigreet** on VT 1.
|
|
Config: `/etc/greetd/config.toml`
|
|
Default command: `tuigreet --time --remember --asterisks --cmd 'uwsm start -e -D Hyprland hyprland.desktop'`
|
|
|
|
### Wayland Session Override (start-hyprland)
|
|
|
|
The package provides `/usr/share/wayland-sessions/hyprland.desktop` with
|
|
`Exec=Hyprland` (direct binary), but Hyprland 0.53+ requires launching through
|
|
`start-hyprland` (watchdog parent process) for crash diagnostics and proper
|
|
signal handling. Otherwise a warning banner appears on login.
|
|
|
|
A local override at `~/.local/share/wayland-sessions/hyprland.desktop` sets
|
|
`Exec=start-hyprland`, which uwsm then manages inside the systemd session.
|
|
XDG_DATA_DIRS priority ensures the override wins without touching system files.
|
|
Managed by Ansible role `hyprland` — see `docs/adr/0004-start-hyprland-override.md`.
|
|
|
|
## Key Categories
|
|
|
|
| Category | Modifier | Keys | Action |
|
|
|----------|----------|------|--------|
|
|
| Focus | SUPER | H/J/K/L, Arrows | Move focus |
|
|
| Move Window | SUPER+SHIFT | H/J/K/L, Arrows | Move window |
|
|
| Resize Window | SUPER+ALT | H/J/K/L | Resize active window |
|
|
| Windows | SUPER | F, SPACE, TAB, `, P, J | Window actions |
|
|
| Apps | SUPER | Q, B, E, D | Launch apps |
|
|
| Workspaces | SUPER | 1-9 | Switch/move workspaces |
|
|
| Lock | SUPER+CTRL | L | Lock screen |
|
|
|
|
See `~/.config/hypr/cheatsheet.txt` for the full reference.
|