Universal Wayland Session Manager

The Universal Wayland Session Manager (uwsm) wraps standalone Wayland compositors into a set of systemd units on the fly. This provides robust session management including environment, XDG Autostart support, bi-directional binding with login session, and clean shutdown.

Note: It is highly recommended to use dbus-broker as the D-Bus daemon implementation. Among other benefits, it reuses the systemd activation environment instead of having a separate one. This simplifies environment management and allows proper cleanup. The reference implementation is also supported, but it does not allow unsetting vars, so a best effort cleanup is performed by setting them to an empty string instead. The only way to properly clean up the separate environment of the reference D-Bus daemon is to run loginctl terminate-user "".

Installation

Install the uwsm package.

Configuration

Service startup notification and vars set by compositor

Note: If managed compositors already set WAYLAND_DISPLAY (and other useful environment variables) into the systemd activation environment, then you can skip this section and you do not need to use uwsm finalize.

In order to find the current compositor wayland applications need the WAYLAND_DISPLAY (or DISPLAY variable, if they are intended to run through Xwayland). Therefore this and other useful environment variables should be put into the systemd/dbus activation environment once the compositor has set their value.

The command uwsm finalize puts WAYLAND_DISPLAY, DISPLAY and other environment variables listed via the whitespace-separated UWSM_FINALIZE_VARNAMES list into the activation environment. Therefore you need to execute this command after the compositor is ready.

If other variables set by the compositors are needed in your activation environment, then you can also pass them as arguments:

exec uwsm finalize VAR1 VAR2 ...

Environment variables

All environment variables set in ${XDG_CONFIG_HOME}/uwsm/env file are sourced by uwsm and available to all managed compositors and graphical applications run inside such a session.

If you need certain environment variables to be set only for a specific compositor (and graphical applications in that graphical session), then put them in ${XDG_CONFIG_HOME}/uwsm/env-compositor instead.

All these files should set environment variables with the following format:

export ''KEY1''=''VAR1''
export ''KEY2''=''VAR2''
export ''KEY3''=''VAR3''
''...''

and should not contain comments.

Usage

Startup

uwsm can be started both by TTY and by a display manager.

TTY

Add in your ~/.profile file:

if uwsm check may-start && uwsm select; then
  exec uwsm start default
fi

If you want to always start the same compositor, then you can use instead in your ~/.profile file:

if uwsm check may-start; then
  exec uwsm start ''compositor''.desktop
fi

Display manager

You can create a custom session desktop entry which starts your compositor through uwsm:

/usr/share/wayland-sessions/my-compositor-uwsm.desktop

[Desktop Entry]
Name=My compositor (with UWSM)
Comment=My cool compositor, UWSM session

# either full command line with metadata and executable
Exec=uwsm start -N "My compositor" -D mycompositor:mylib -C "My cool compositor" -- my-compositor

# or a reference to another entry
Exec=uwsm start -- my-compositor.desktop

DesktopNames=mycompositor;mylib
Type=Application

Session termination

If you want to terminate the current uwsm session, then you should use either loginctl terminate-user "" (terminates the entire user session) or uwsm stop (executes code after uwsm start or terminates user session, if it replaced the login shell).

Warning: Do not use a compositor's native exit mechanism or kill its process directly. This will yank the compositor from under all the clients and interfere with ordered unit deactivation sequence.

This article is issued from Archlinux. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.