From 1741c32b0b479bcf09d95bd1989cb02342369018 Mon Sep 17 00:00:00 2001 From: izmyname <135810812+izmyname@users.noreply.github.com> Date: Mon, 11 Nov 2024 19:53:20 +0500 Subject: [PATCH] Useful Utilities/Systemd-start: init with uwsm instructions (#850) Co-authored-by: Mihai Fufezan Co-authored-by: Vladimir-csp <4061903+Vladimir-csp@users.noreply.github.com> --- pages/Configuring/Dispatchers.md | 8 ++ pages/Configuring/Environment-variables.md | 6 ++ pages/Getting Started/Installation.md | 2 +- pages/Getting Started/Master-Tutorial.md | 3 +- pages/Hypr Ecosystem/hypridle.md | 2 +- pages/Hypr Ecosystem/hyprpaper.md | 2 +- pages/Hypr Ecosystem/hyprpolkitagent.md | 2 +- pages/Useful Utilities/Other.md | 4 - pages/Useful Utilities/Status-Bars.md | 6 ++ pages/Useful Utilities/Systemd-start.md | 102 +++++++++++++++++++++ 10 files changed, 128 insertions(+), 9 deletions(-) create mode 100644 pages/Useful Utilities/Systemd-start.md diff --git a/pages/Configuring/Dispatchers.md b/pages/Configuring/Dispatchers.md index 4b56f85..0c6e835 100644 --- a/pages/Configuring/Dispatchers.md +++ b/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 diff --git a/pages/Configuring/Environment-variables.md b/pages/Configuring/Environment-variables.md index c4eea9d..53ebe7c 100644 --- a/pages/Configuring/Environment-variables.md +++ b/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` - diff --git a/pages/Getting Started/Installation.md b/pages/Getting Started/Installation.md index 6523e02..7a3a67e 100644 --- a/pages/Getting Started/Installation.md +++ b/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 diff --git a/pages/Getting Started/Master-Tutorial.md b/pages/Getting Started/Master-Tutorial.md index a27bcb9..e0e9825 100644 --- a/pages/Getting Started/Master-Tutorial.md +++ b/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 >}} diff --git a/pages/Hypr Ecosystem/hypridle.md b/pages/Hypr Ecosystem/hypridle.md index 964a296..14b154b 100644 --- a/pages/Hypr Ecosystem/hypridle.md +++ b/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 diff --git a/pages/Hypr Ecosystem/hyprpaper.md b/pages/Hypr Ecosystem/hyprpaper.md index 16c38ae..e31745e 100644 --- a/pages/Hypr Ecosystem/hyprpaper.md +++ b/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 diff --git a/pages/Hypr Ecosystem/hyprpolkitagent.md b/pages/Hypr Ecosystem/hyprpolkitagent.md index 2d4ed76..3d89cf0 100644 --- a/pages/Hypr Ecosystem/hyprpolkitagent.md +++ b/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 diff --git a/pages/Useful Utilities/Other.md b/pages/Useful Utilities/Other.md index 9528d81..5f66408 100644 --- a/pages/Useful Utilities/Other.md +++ b/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. diff --git a/pages/Useful Utilities/Status-Bars.md b/pages/Useful Utilities/Status-Bars.md index 5b91987..d39b41c 100644 --- a/pages/Useful Utilities/Status-Bars.md +++ b/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 diff --git a/pages/Useful Utilities/Systemd-start.md b/pages/Useful Utilities/Systemd-start.md new file mode 100644 index 0000000..4516e48 --- /dev/null +++ b/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.