Useful Utilities/Systemd-start: init with uwsm instructions (#850)

Co-authored-by: Mihai Fufezan <mihai@fufexan.net>
Co-authored-by: Vladimir-csp <4061903+Vladimir-csp@users.noreply.github.com>

pages/Configuring/Dispatchers.md

@@ -85,6 +85,14 @@ layout pages (See the sidebar).
 
 {{< callout type=warning >}}
 
+[uwsm](../../Systemd-start) users should avoid using `exit` dispatcher, or terminating Hyprland process directly, as exiting Hyprland this way removes it from under its clients and may cause some systemd services to enter inconsistent states causing problems in the next session. Use `exec, loginctl terminate-user ""` instead.
+
+It's also strongly advised to replace the `exit` dispatcher with `exec, loginctl terminate-user ""` inside `hyprland.conf` keybinds section.
+
+{{< /callout >}}
+
+{{< callout type=warning >}}
+
 It is NOT recommended to set DPMS with a keybind directly, as it might cause
 undefined behavior. Instead, consider something like
 

pages/Configuring/Environment-variables.md

@@ -72,6 +72,12 @@ them explicitly.
 If your [desktop portal](https://wiki.archlinux.org/title/XDG_Desktop_Portal) is malfunctioning for seemingly
 no reason (no errors), it's likely your XDG env isn't set correctly.
 
+ {{< callout type=info >}}
+
+ [uwsm](../../Systemd-start) users don't need to explicitly set XDG environment variables, as uwsm sets them, automatically.
+
+ {{< /callout >}}
+
 ## Qt Variables
 
 - `env = QT_AUTO_SCREEN_SCALE_FACTOR,1` -

pages/Getting Started/Installation.md

@@ -383,7 +383,7 @@ C++ standard library has to support that (`gcc>=14` or `clang>=18`).
 {{% details title="Arch" closed="true" %}}
 
 ```plain
-yay -S gdb ninja gcc cmake meson libxcb xcb-proto xcb-util xcb-util-keysyms libxfixes libx11 libxcomposite libxrender pixman wayland-protocols cairo pango seatd libxkbcommon xcb-util-wm xorg-xwayland libinput libliftoff libdisplay-info cpio tomlplusplus hyprlang-git hyprcursor-git hyprwayland-scanner-git xcb-util-errors hyprutils-git
+yay -S ninja gcc cmake meson libxcb xcb-proto xcb-util xcb-util-keysyms libxfixes libx11 libxcomposite libxrender pixman wayland-protocols cairo pango seatd libxkbcommon xcb-util-wm xorg-xwayland libinput libliftoff libdisplay-info cpio tomlplusplus hyprlang-git hyprcursor-git hyprwayland-scanner-git xcb-util-errors hyprutils-git
 ```
 
 _(Please make a pull request or open an issue if any packages are missing from

pages/Getting Started/Master-Tutorial.md

@@ -47,7 +47,8 @@ Please bear in mind 3D acceleration in VMs may be pretty slow.
 
 Hyprland can be executed by typing `Hyprland` in your tty.
 
-Systemd users can also start Hyprland, by typing `systemctl --user start hyprland-session.service` in tty. This method provides additional features, such as [xdg-autostart](https://www.freedesktop.org/software/systemd/man/latest/systemd-xdg-autostart-generator.html) support and ability to enable services for programs that rely on a graphical session and provide such services (e.g waybar).
+Systemd users can also start Hyprland, using [uwsm](https://github.com/Vladimir-csp/uwsm). This is the recommended method of launching Hyprland on systemd-based distros, as it provides additional features such as [xdg-autostart](https://www.freedesktop.org/software/systemd/man/latest/systemd-xdg-autostart-generator.html) support, launching any application as a systemd-unit with `uwsm app` helper, and the ability to enable services for programs that rely on a graphical session and provide such services (e.g waybar). See [uwsm](../../Systemd-start) page for further instructions.
+
 
 {{< callout type=warning >}}
 

pages/Hypr Ecosystem/hypridle.md

@@ -9,7 +9,7 @@ hypridle is Hyprland's idle management daemon.
 
 Configuration is done via the config file at `~/.config/hypr/hypridle.conf`. A
 config file is required; hypridle won't run without one. To run hypridle at
-startup, edit `hyprland.conf` and add: `exec-once = hypridle`. If Hyprland is started as a systemd service, you can use `systemctl --user enable --now hypridle.service`.
+startup, edit `hyprland.conf` and add: `exec-once = hypridle`. If Hyprland is started with [uwsm](../../Systemd-start), you can use `systemctl --user enable --now hypridle.service`.
 
 ### General
 

pages/Hypr Ecosystem/hyprpaper.md

@@ -124,7 +124,7 @@ preload another and set it to your monitor(s). It has the same syntax as
 ### Run at startup
 
 To run hyprpaper at startup edit `hyprland.conf` and add: `exec-once =
-hyprpaper`. If you start Hyprland as a systemd service, you can also use `systemctl --user enable --now hyprpaper.service` command.
+hyprpaper`. If you start Hyprland with [uwsm](../../Systemd-start), you can also use `systemctl --user enable --now hyprpaper.service` command.
 
 ### Misc options
 

pages/Hypr Ecosystem/hyprpolkitagent.md

@@ -14,7 +14,7 @@ or use a different agent, e.g. [KDE's one](https://github.com/KDE/polkit-kde-age
 Add `exec-once = systemctl --user start hyprpolkitagent` to your Hyprland config and restart hyprland.
 (obviously change that to whatever you are using if you are not using the hypr one)
 
-If Hyprland is started as a systemd service, you can autostart for polkit with the command `systemctl --user enable --now hyprpolkitagent.service`.
+If Hyprland is started with [uwsm](../../Systemd-start), you can autostart the polkit agent with the command `systemctl --user enable --now hyprpolkitagent.service`.
 
 On distributions that use a different init system, such as Gentoo, it may be
 necessary to use

pages/Useful Utilities/Other.md

@@ -65,10 +65,6 @@ exec-once = udiskie
 
 [See more uses here](https://github.com/coldfix/udiskie/wiki/Usage).
 
-### Advanced Systemd Session Management
-
-[UWSM](https://github.com/Vladimir-csp/uwsm) by _Vladimir-csp_: Wraps standalone Wayland compositors into a set of Systemd units on the fly. Provides robust session management including environment, XDG autostart support, bi-directional binding with login session, login shell integration, and clean shutdown. Optional user unit control utility via dmenu-like menu, failed unit monitor.
-
 ### Other useful utilities
 
 The website [We Are Wayland Now](https://wearewaylandnow.com/) details some other useful utilities and applications for Wayland like docks, email clients, and so on, along with some other useful information about compatibility on Wayland.

pages/Useful Utilities/Status-Bars.md

@@ -27,6 +27,12 @@ Hyprland, add this line to your Hyprland configuration:
 exec-once = waybar
 ```
 
+Waybar also provides a systemd service. If you use Hyprland with [uwsm](../../Systemd-start), you can enable it, using the following command.
+
+```ini
+systemctl --user enable --now waybar.service
+```
+
 ### Waybar FAQ
 
 #### Waybar popups render behind the windows

pages/Useful Utilities/Systemd-start.md

@@ -0,0 +1,102 @@
+---
+weight: 12
+title: Systemd startup
+---
+
+## UWSM
+
+- [Universal Wayland Session Manager](https://github.com/Vladimir-csp/uwsm) is a recommended way to start Hyprland session on systemd distros. uwsm wraps standalone Wayland compositors into a set of Systemd units and provides robust session management including environment, XDG autostart support, bi-directional binding with login session, and clean shutdown.
+
+## Installation
+
+{{% details title="Arch" closed="true" %}}
+
+uwsm is available in AUR. You can install it either with an AUR helper, or build PKGBUILD manually. Here's an example for yay.
+
+```sh
+yay -S uwsm
+```
+
+{{% /details %}}
+
+{{% details title="Nix/NixOS" closed="true" %}}
+
+```nix
+programs.uwsm = {
+  enable = true;
+  waylandCompositors.hyprland = {
+    binPath = "/run/current-system/sw/bin/Hyprland";
+    comment = "Hyprland session managed by uwsm";
+    prettyName = "Hyprland";
+  };
+};
+```
+
+The above option generates a new desktop entry, `hyprland-uwsm.desktop`, which will be available in display managers.
+
+For more info, read the [option](https://search.nixos.org/options?channel=unstable&show=programs.uwsm.enable&from=0&size=50&sort=relevance&type=packages&query=uwsm).
+
+{{< callout >}}
+
+If you use the [Home Manager module](../../Nix/Hyprland-on-Home-Manager), make sure to disable the systemd integration, as it conflicts with uwsm.
+
+```nix
+wayland.windowManager.hyprland.systemd.enable = false;
+```
+
+{{< /callout >}}
+
+{{% /details %}}
+
+{{< callout type=info >}}
+
+For instructions for other distros and manual building, see [building and installing](https://github.com/Vladimir-csp/uwsm?tab=readme-ov-file#installation) section on the project's page.
+
+{{< /callout >}}
+
+## Launching Hyprland with uwsm
+
+{{< callout type=info >}}
+
+Pay attention to the warnings in [Environment variables](../../Environment-variables#xdg-specifications) and [Dispatchers](../../Dispatchers) sections.
+
+{{< /callout >}}
+
+### In tty
+
+To launch Hyprland with uwsm, add this code in your shell profile.
+
+```
+if uwsm check may-start && uwsm select; then
+	exec systemd-cat -t uwsm_start uwsm start default
+fi
+```
+
+This will bring uwsm compositor selection menu after you log in tty1. Choose Hyprland entry and you're good to go.
+
+If you want to bypass compositor selection menu and launch Hyprland directly, use this code in your shell profile, instead.
+
+```
+if uwsm check may-start; then
+    exec uwsm start hyprland.desktop
+fi
+```
+
+### Using a display manager
+
+If you use a display manager, choose `hyprland (uwsm-managed)` entry in a display manager selection menu.
+
+## Launching applications inside session
+
+The concept of a session managed by Systemd implies also running applications as units. Uwsm [provides](https://github.com/Vladimir-csp/uwsm#3-applications-and-slices) a helper to do it.
+
+Prefix application startup commands with `uwsm app --`. It also supports launching Desktop Entries by IDs or paths. See `man uwsm` or `uwsm app --help`.
+
+Examples for autostart and bind entries:
+
+```
+exec-once = uwsm app -- mycommand --arg1 --arg2
+bind = SUPER, E, exec, uwsm app -- pcmanfm-qt.desktop
+```
+
+Running applications as child processes inside compositor's unit is discouraged.