Universal Wayland Session Manager

Provides graphical session with environment management, XDG autostart support, and clean shutdown by wrapping standalone Wayland compositors into a set of systemd units.

[!IMPORTANT] This project is currently in a stable phase with a slow-burning refactoring. Although no drastic changes are planned, keep an eye for commits with breaking changes, indicated by an exclamation point (e.g. fix!: ..., chore!: ..., feat!: ..., etc.).

[!IMPORTANT] uwsm-bin-name build option is considered deprecated and will be removed in future versions.

[!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 its own separate one. This simplifies environment management and allows proper cleanup. The separate activation environment of the reference D-Bus implementation doesn't allow unsetting vars, so they're set to an empty string instead, as a best effort cleanup. The only way to properly clean up in this case is to run loginctl terminate-user "".

Concepts and features

Installation

1. Building and installing

Runtime dependencies:

• python modules:
  • xdg (pyxdg)
  • dbus (dbus_python)
• waitpid (optional, but recommended for resources; from util-linux or util-linux-extra package)
• whiptail (optional, for select feature; from whiptail or libnewt package)
• a dmenu-like menu (optional; for uuctl script), supported:
  • fuzzel
  • wofi
  • rofi
  • tofi
  • bemenu
  • wmenu
  • dmenu

2. Service startup notification and vars set by compositor

Ensure your compositor runs uwsm finalize command at the end of its startup. If compositor sets any useful environment variables, list their names as arguments.

Example snippet for sway config (these vars are already covered by sway plugin by adding them to UWSM_FINALIZE_VARNAMES var, listed here just for clearness):

exec exec uwsm finalize SWAYSOCK I3SOCK XCURSOR_SIZE XCURSOR_THEME

3. Applications and Slices

To properly put applications in app-graphical.slice (or like), Configure application launching in compositor via:

uwsm app -- {executable|entry.desktop[:action]} [args ...]

When app launching is properly configured, compositor service itself can be placed in session.slice by either:

• Setting environment variable UWSM_USE_SESSION_SLICE=true before generating units. Best places to put this:
  • export in ~/.profile before uwsm invocation
  • put in ~/.config/environment.d/*.conf (see man environment.d)
• Adding -S argument to uwsm start subcommand.

Operation

Syntax and behavior

-h|--help option is available for uwsm and all of its subcommands.

Basics:

uwsm start [options] -- ${compositor} [arguments]

Always use -- to disambiguate command line if any dashed arguments are intended for launched compositor.

${compositor} can be an executable or a valid desktop entry ID (optionally with an action ID appended via ':'), or one of special values: select|default

Optional parameters to provide more metadata:

• -[a|e]D DesktopName1[:DesktopMame2:...]: append (-a) or exclusively set (-e) ${XDG_CURRENT_DESKTOP}
• -N Name
• -C "Compositor description"

Arguments and metadata are stored in specifier unit drop-ins if needed.

When started, uwsm will wait while wayland session is running, and terminate session if is itself interrupted or terminated.

Where to launch from

Shell profile integration

To launch automatically after login on virtual console 1, if systemd is at graphical.target, add this to shell profile:

if uwsm check may-start && uwsm select; then
    exec systemd-cat -t uwsm_start uwsm start default
fi

uwsm check may-start checker subcommand, among other things, screens for being in interactive login shell, which is essential, since profile sourcing can otherwise lead to nasty loops.

uwsm start select shows whiptail menu to select default desktop entry from wayland-sessions directories. At this point one can cancel and continue with the normal login shell.

exec in shell profile causes uwsm (via systemd-cat) to replace login shell, binding it to user's login session.

systemd-cat -t uwsm_start part is optional, it executes the command given to it (uwsm) with its stdout and stderr connected to the systemd journal, tagged with identifier uwsm_start. Otherwise it might be hard to see the output.

uwsm start default launches the previously selected default compositor.

From a display manager

To launch uwsm from a display/login manager, uwsm can be used inside desktop entries. Example /usr/local/share/wayland-sessions/my-compositor.desktop:

[Desktop Entry]
Name=My compositor (with UWSM)
Comment=My cool compositor
Exec=uwsm start -N "My compositor" -D mycompositor -C "My cool compositor" mywm
DesktopNames=mycompositor
Type=Application

Things to keep in mind:

• For consistency, command line arguments should mirror the keys of the entry
• Command in Exec= should start with uwsm start
• It should not launch a desktop entry, only an executable.

Potentially such entries may be found and used by uwsm itself, i.e. in shell profile integration situation, or when launched manually. Following the principles above ensures uwsm will properly recognize itself and parse requested arguments inside the entry without any side effects.

Testing and feedback is needed.

How to stop

Either of:

• loginctl terminate-user "" (this ends all login sessions and units of current user, good for resetting everything, including runtime units, environments, etc.)
• loginctl terminate-sesion "$XDG_SESSION_ID" (this ends current login session, uwsm in this session will bring down graphical session units before exiting. Empty argument will only work if loginctl is called from session scope itself)
• uwsm stop (brings down graphical session units. Login session will end if uwsm start replaces login shell)
• systemctl --user stop wayland-wm@*.service (effectively the same as previous one)

Longer story, tour under the hood

Some extended examples and partial recreation of some behaviors via excessive shell code, just for deeper explanation.

Compositor-specific actions

Shell plugins provide compositor-specific functions during environment preparation.

Named ${__WM_BIN_ID__}.sh, they should only contain specifically named functions.

${__WM_BIN_ID__} is derived from the item 0 of compositor command line by applying s/(^[^a-zA-Z]|[^a-zA-Z0-9_])+/_/ and converting to lower case.

It is used as plugin id and suffix in function names.

Variables available to plugins:

• __WM_ID__ - compositor ID, effective first argument of start.
• __WM_ID_UNIT_STRING__ - compositor ID escaped for systemd unit name.
• __WM_BIN_ID__ - processed first item of compositor argv.
• __WM_DESKTOP_NAMES__ - :-separated desktop names from DesktopNames= of entry and -D cli argument.
• __WM_FIRST_DESKTOP_NAME__ - first of the above.
• __WM_DESKTOP_NAMES_LOWERCASE__ - same as the above, but in lower case.
• __WM_FIRST_DESKTOP_NAME_LOWERCASE__ - first of the above.
• __WM_DESKTOP_NAMES_EXCLUSIVE__ - (true|false) indicates that __WM_DESKTOP_NAMES__ came from cli argument and are marked as exclusive.
• __OIFS__ - contains shell default field separator (space, tab, newline) for convenient restoring.

Standard functions:

• load_wm_env - standard function for loading env files
• process_config_dirs_reversed - called by load_wm_env, iterates over XDG_CONFIG hierarchy in reverse (increasing priority)
• in_each_config_dir_reversed - called by process_config_dirs_reversed for each config dir, loads uwsm-env, uwsm-env-${desktop} files
• process_config_dirs - called by load_wm_env, iterates over XDG_CONFIG hierarchy (decreasing priority)
• in_each_config_dir - called by process_config_dirs for each config dir, does nothing ATM
• source_file - sources $1 file, providing messages for log.

See code inside uwsm/main.py for more auxillary funcions.

Functions that can be added by plugins, replacing standard funcions:

• quirks__${__WM_BIN_ID__} - called before env loading.
• load_wm_env__${__WM_BIN_ID__}
• process_config_dirs_reversed__${__WM_BIN_ID__}
• in_each_config_dir_reversed__${__WM_BIN_ID__}
• process_config_dirs__${__WM_BIN_ID__}
• in_each_config_dir__${__WM_BIN_ID__}

Original functions are still available for calling explicitly if combined effect is needed.

Example:

#!/bin/false

# function to make arbitrary actions before loading environment
quirks__my_cool_wm() {
  # here additional vars can be set or unset
  export I_WANT_THIS_IN_SESSION=yes
  unset I_DO_NOT_WANT_THAT
  # or prepare a config for compositor
  # or set a var to modify what sourcing uwsm-env, uwsm-env-${__WM_ID__}
  # in the next stage will do
  ...
  # add a var to be exported by uwsm finalize:
  UWSM_FINALIZE_VARNAMES="${UWSM_FINALIZE_VARNAMES}${UWSM_FINALIZE_VARNAMES:+ }ANOTHER_VAR1 ANOTHER_VAR2"
}

in_each_config_dir_reversed__my_cool_wm() {
  # custom mechanism for loading of env files (or a stub)
  # replaces standard function, but we want it also
  # so call it explicitly
  in_each_config_dir_reversed "$1"
  # and additionally source our file
  source_file "${1}/${__WM_ID__}/env"
}

Compliments

Inspired by and adapted some techniques from:

• sway-services
• sway-systemd
• sway
• Presentation by Martin Pitt

Special thanks to @skewballfox for help with python and pointing me to useful tools.