• Binds to the basic structure of graphical-session-pre.target, graphical-session.target, xdg-desktop-autostart.target.
• Adds custom nested slices app-graphical.slice, background-graphical.slice, session-graphical.slice to put apps in and terminate them cleanly on exit.
• Provides convenient way of launching apps into those slices.

• Templated units with specifiers.
• Named from common to specific where possible.
• Allowing for high-level name-.d drop-ins.

Using waitpid utility (or a built-in shim) together with native systemd mechanisms, uwsm binds lifetime of a login session (session-N.scope system unit) to graphical session (a set of user units) and vice versa.

Currently included:

• sway
• wayfire
• labwc
• hyprland
• niri
• mango

LXQt variants of the above are provided by the experimental LXQt Universal Wayland Session.

• On startup a specialized unit prepares environment by:
  • either loading environment context saved by uwsm start command or sourcing shell profile by itself
  • sourcing uwsm/env, uwsm/env.d/*, uwsm/env-${desktop}, uwsm/env-${desktop}.d/* files from each dir of reversed sequence ${XDG_CONFIG_HOME}:${XDG_CONFIG_DIRS}:${XDG_DATA_DIRS} (in increasing priority), where ${desktop} is each item of ${XDG_CURRENT_DESKTOP}, lowercased
• Difference between environment state before and after preparation is exported into systemd user manager (and D-Bus activation environment if reference D-Bus implementation is used)
• On shutdown previously exported variables are unset from systemd user manager (activation environment of reference D-Bus daemon does not support unsetting, so those vars are emptied instead (!))
• Lists of variables for export and cleanup are determined algorithmically by:
  • comparing environment before and after preparation procedures
  • boolean operations with predefined lists (can be configured)
  • manually exported vars by uwsm finalize action

• Actively select and launch compositor from Desktop entry (which is used as compositor instance ID):
  • Data taken from entry (can be amended or overridden via CLI arguments):
    • Exec for argument list
    • DesktopNames for XDG_CURRENT_DESKTOP and XDG_SESSION_DESKTOP
    • Name and Comment for unit Description
  • Entries can be overridden, masked or added in ${XDG_DATA_HOME}/wayland-sessions/
  • Optional interactive selector (requires whiptail), choice is saved in ${XDG_CONFIG_HOME}/uwsm/default-id, default is read from it, falling back all the way through ${XDG_CONFIG_DIRS}:${XDG_DATA_DIRS}
  • Desktop entry actions are supported
• Be launched via a Desktop entry by a login/display manager.

wayland-wm-env@${compositor}.service.d/50_custom.conf
wayland-wm@${compositor}.service.d/50_custom.conf

• XDG autostart services (app-*@autostart.service units) are placed into app-graphical.slice that receives stop action before compositor is stopped.
• Can be mass-controlled via stopping and starting wayland-session-xdg-autostart@${compositor}.target

Basic provided unit files (can be transient if project built with static-units=disabled):

background-graphical.slice
app-graphical.slice
session-graphical.slice
wayland-session-envelope@.target
wayland-session-pre@.target
wayland-session-shutdown.target
wayland-session-xdg-autostart@.target
wayland-session@.target
wayland-wm-app-daemon.service
wayland-wm-env@.service
wayland-wm@.service
wayland-session-bindpid@.service
wayland-session-waitenv.service

Managed generated files (in ${XDG_RUNTIME_DIR}/systemd/user or ${XDG_CONFIG_HOME}/systemd/user depending on -U option):

Compositor metadata customization drop-ins:

wayland-wm-env@${compositor}.service.d/50_custom.conf
wayland-wm@${compositor}.service.d/50_custom.conf

Tweaks for other units:

app-@autostart.service.d/slice-tweak.conf
plasma-xdg-desktop-portal-kde.service.d/order-tweak.conf

See Longer story section below for descriptions.

• uwsm finalize: for explicitly exporting variables to activation environments and signal compositor's unit readiness (compositor service unit uses Type=notify)
• uwsm check may-start: for checking conditions for launch at login (for integration into login shell profile)
• uwsm app: for launching applications as scopes or services in proper slices
  • desktop entries or plain executables are supported
  • support for launching a terminal/in terminal (proposed xdg-terminal-exec)
  • flexible unit metadata support
• uwsm-app: a simple and fast shell client to app-daemon feature of uwsm, a drop-in replacement of uwsm app. The daemon (started on-demand) handles finding requested desktop entries, parsing and generation of commands for client to execute. This avoids the overhead of repeated python startup and increases app launch speed.
• uuctl: optional graphical (requires a dmenu-like menu) tool for managing user units.
• fumon: optional background service for notifying about failed units (requires notify-send from libnotify or libnotify-bin package).
• ttyautolock: optional background service for locking session when its TTY loses focus (requires inotifywait from inotify-tools package).

meson setup --prefix=/usr/local -Duuctl=enabled -Dfumon=enabled -Duwsm-app=enabled -Dttyautolock=enabled build
meson install -C build

The example enables optional tools uuctl, fumon, ttyautolock, and uwsm-app available in this project (see helpers and tools spoiler in concepts section above).

Read and run ./build-deb.sh -i

Alternatively,

IFS='()' read -r _ current_version _ < debian/changelog
sudo apt install devscripts
mk-build-deps
sudo apt install --mark-auto ./uwsm-build-deps_${current_version}_all.deb
dpkg-buildpackage -b -tc --no-sign
sudo apt install ../uwsm_${current_version}_all.deb

pacman -S uwsm

Enable it using programs.uwsm.enable and configure available compositors using programs.uwsm.waylandCompositors. Please see the options' descriptions for more information.

List names of variable as arguments to uwsm finalize, or append them to whitespace-separated list in UWSM_FINALIZE_VARNAMES variable (do it beforehand, i.e. in env files or shell profile).

Example snippet for sway config (these vars are already covered by sway plugin via UWSM_FINALIZE_VARNAMES var and listed here just for clearness):

exec exec uwsm finalize SWAYSOCK I3SOCK XCURSOR_SIZE XCURSOR_THEME

Undefined variables will be are silently ignored.

Append names of variables to whitespace-separated list in UWSM_WAIT_VARNAMES variable (do it beforehand, i.e. in env files or shell profile). This will make uwsm delay graphical session startup until those vars appear in the systemd activation environment.

Depending on the situation, combine this with with uwsm finalize command to put more variables into activation environments and gain more control over delay mechanism of uwsm.

Be aware that uwsm finalize skips undefined vars, so be sure that all vars listed in UWSM_WAIT_VARNAMES are really being set, or use explicit assignment to serve as a marker. Example:

# in env file:
export UWSM_WAIT_VARNAMES="${UWSM_WAIT_VARNAMES} FINALIZED"

# in compositor's autostart:
uwsm finalize FINALIZED="I'm here" SWAYSOCK I3SOCK XCURSOR_SIZE XCURSOR_THEME

You can also tweak UWSM_WAIT_VARNAMES_SETTLETIME (float, default: 0.2) to change pause duration after all expected vars are found.

Inside wayland-wm@${compositor}.service before executing compositor itself, uwsm forks a process that probes systemd activation environment for WAYLAND_DISPLAY var and vars listed in UWSM_WAIT_VARNAMES variable (whitespace-separated). When all expected vars appear, it pauses for UWSM_WAIT_VARNAMES_SETTLETIME seconds (float, default: 0.2) and signals unit readiness. It also updates cleanup list with delta between states of activation environment at unit startup time and the end of settle pause. If classic D-Bus implementation is used, this delta is also synched to its activation environment.

A separate unit, wayland-session-waitenv.service is launched alongside compositor, with similar ordering after graphical-session-pre.target, before graphical-session.target. It also waits for the same variables in the same manner, then successfully exits (or times out). Its job is to delay graphical-session.target activation in case compositor signals its readiness prematurely. Or to fail startup if expected vars do not appear.

The uwsm finalize command fills systemd and D-Bus environments with essential vars set by the compositor: WAYLAND_DISPLAY (mandatory) and DISPLAY (if present). Optional vars are taken by name from arguments and UWSM_FINALIZE_VARNAMES var, which is also pre-filled by plugins. D-Bus implementation quirks are handled. Undefined vars are silently ignored. Any exported variables are also added to cleanup list.

Timeout for unit startup is 10 seconds.

• systemctl --user enable this-app.service (if it provides WantedBy=graphical-session.target)
• systemctl --user add-wants graphical-session.target that-app.service (if it does not)

In the end autostarted unit should have both dependency and ordering (be wanted by a target and ordered after it) see example-units.

Or just start with systemctl --user start not-a-service.service.

Units can be fully or partially overridden/edited via standard systemd mechanisms.

Their OnlyShowIn=/NotShowIn= lists should align with $XDG_CURRENT_DESKTOP items or be absent. Autostart entries can be overridden by copying and editing them in ${XDG_CONFIG_HOME}/autostart/. Generated app-*@autostart.service units are editable via drop-ins.

Also see example-units and refer to Desktop Application Autostart Specification

uwsm app can be quite slow on some setups due to repeated python startup overhead.

Included optional uwsm-app script uitilizes uwsm's on-demand app daemon for more responsiveness in repeated interactive launching.

app2unit is a faster shell alternative, with feature parity. It can also be used outside uwsm environment and can integrate with Fuzzel.

runapp a fast C++ executable, although it is not feature-complete yet.

uwsm launches the compositor's service as wayland-wm@${compositor}.service in session.slice.

Processes descendent from the compositor will be a part of its unit which might be mostly OK for short-lived one-off commands, i.e. volume adjustment. But processes inside comopositor's unit will have brief access to its notification socket before it is restricted after startup is complete. This may lead to unforeseen consequences, like compositor unit being erroneously declared entering stopping state.

Systemd documentation recommends launching apps as their own units (scopes or services). app.slice would be the default destination, background.slice and session.slice are available for low-priority non-interactive tasks and high-priority responsiveness-aware tasks respectively, (see man systemd.special)

uwsm provides a convenient way of handling this: special nested slices that will also receive stop action before wayland-wm@${compositor}.service shutdown:

• app-graphical.slice (default destination)
• background-graphical.slice
• session-graphical.slice

app-*@autostart.service units of XDG autostart entries are also modified to be started in app-graphical.slice.

To launch an app inside one of those slices, use:

uwsm app [-s a|b|s|custom.slice] [-t scope|service] -- your_app [with args]

Launching desktop entries via a valid ID is also supported (optionally with an action ID appended via :):

uwsm app [-s a|b|s|custom.slice] [-t scope|service] -- your_app.desktop[:action] [with args]

In this case args must be supported by the entry or its selected action according to the XDG Desktop Entry Specification.

Specifying paths to executables or desktop entry files is also supported.

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

Scopes are the default type of units for launching apps via uwsm app, they are executed in-place and behave like simple commands, inheriting environment and pty of origin.

Services are launched in the background by the systemd user manager and are given an environment based on the current state of the activation environment of systemd; their output is routed to the journal. uwsm app will return immediately after launch. This allows more control over the application, i.e. restarting it with an updated environment.

Example snippets for sway config for launching apps:

Launch proposed default terminal:

bindsym --to-code $mod+t exec exec uwsm app -T

Fuzzel has a very handy launch-prefix option:

bindsym --to-code $mod+r exec exec fuzzel --launch-prefix='uwsm app --'

Walker can prefix launching apps by setting app_launch_prefix variable in the config, so "app_launch_prefix": "uwsm app -- ".

Launch SpaceFM via a desktop entry:

bindsym --to-code $mod+e exec exec uwsm app spacefm.desktop

Featherpad desktop entry has "standalone-window" action:

bindsym --to-code $mod+n exec exec uwsm app featherpad.desktop:standalone-window

Unit type of launched apps can be controlled by -t service|scope argument or setting its default via UWSM_APP_UNIT_TYPE env var.

uwsm start \
	[-[a|e]D DesktopName1[:DesktopName2:...]] \
	[-N Name] \
	[-C "Compositor description"] \
	[-F] \
	[-g|-G seconds] \
	[-o] \
	[-U run|home] \
	[-t] \
	[-n] \
	-- ${compositor} [with "any complex" --arguments]

If ${compositor} is a desktop entry ID, uwsm will find it in wayland-sessions data hierarchy. Exec will be used for command line, and DesktopNames will fill $XDG_CURRENT_DESKTOP, Name and Comment will go to units' description.

Arguments provided on the command line are appended to the command line from session's desktop entry (unlike application entries); no argument processing is done. (Please file a bug report if you encounter any wayland-sessions desktop entry with %-fields which would require this behavior to be altered.)

If you want to customize compositor execution provided with a desktop entry, copy it to ~/.local/share/wayland-sessions/ and change to your liking, including adding actions.

If ${compositor} is select or default, uwsm invokes a menu to select desktop entries available in wayland-sessions data hierarchy (including their actions). Selection is saved, previous selection is highlighted (or launched right away in case of default). Selected entry is used as instance ID.

There is also a separate select action (uwsm select) that only selects and saves default ${compositor} and does nothing else, which is handy for seamless shell profile integration.

uwsm will also wait for activation of system graphical.target and either warn or abort if timed out, or if graphical.target was not found in queue. This behavior can be controlled via -g|-G option. It can not however stop automatically if system graphical.target becomes deactivated.

Things uwsm start ... will do:

• Prepare unit drop-ins for metadata and tweaks in runtime or home directory.
• Fork a process protected from TERM and HUP signals that will find future compositor unit's MainPID and wait for it to end, ensuring login session is kept open until graphical session ends.
• Start wayland-session-bindpid@.service unit pointing to uwsm's own PID to rig graphical session shutdown in case uwsm (or login session) ends.
• Finally, replace itself with systemctl command which will actually start the compositor unit and wait while wayland session is running.

Start and bind

Depending on static-units build option, units files are provided or generated on the fly. Customization drop-ins are always generated if needed. Tweak drop-ins can be disabled by -t option.

Run uwsm start -o ${compositor} to populate systemd/user/ conriguration with them and do nothing else (-o). Destination rung can be $XDG_RUNTIME_DIR or $XDG_CONFIG_HOME, depending on $UWSM_UNIT_RUNG or -U option. Managed files in the other rung are removed.

Any remainder arguments are appended to compositor argument list (even when ${compositor} is a desktop entry). Use -- to disambiguate:

uwsm start -o -- ${compositor} with "any complex" --arguments

Desktop entries can be overridden or added in ${XDG_DATA_HOME}/wayland-sessions/.

Basic set of unit files:

• templated targets bound to stock systemd user-level targets
  • wayland-session-pre@.target
  • wayland-session@.target
  • wayland-session-xdg-autostart@.target
• templated services
  • wayland-wm-env@.service - environment preloader service
  • wayland-wm@.service - main compositor service
  • wayland-wm-app-daemon.service - fast app command generator
• slices for apps nested in stock systemd user-level slices
  • app-graphical.slice
  • background-graphical.slice
  • session-graphical.slice
• metadata drop-ins
  • wayland-wm-env@${compositor}.service.d/50_custom.conf, wayland-wm@${compositor}.service.d/50_custom.conf - if arguments and/or various names, path to executable were given on command line, they go here.
• tweaks
  • app-@autostart.service.d/slice-tweak.conf - assigns XDG autostart apps to app-graphical.slice
  • plasma-xdg-desktop-portal-kde.service.d/order-tweak.conf - adds ordering After=graphical-session.target to KDE desktop portal.
• meta, shutdown, and cleanup units
  • wayland-session-envelope@.target - initiates/propagates startup and shutdown, itself brought up on startup, lives throughout whole startup, session lifetime, and shutdown.
  • wayland-session-bindpid@.service - starts waitpid utility for a given PID. Invokes wayland-session-shutdown.target when deactivated. uwsm start starts this unit pointing to itself just before replacing itself with a shell signal handler and systemctl unit startup command.
  • wayland-session-shutdown.target - conflicts with operational units. Triggered by deactivation of wayland-wm*@*.service and wayland-session-bindpid@*.service units, both successful or failed. But can also be called manually for shutdown.

After unit files are generated, compositor can be started by: systemctl --user start wayland-wm@${compositor}.service

But this would run it completely disconnected from a login session or any process that started it. To fix that use wayland-session-bindpid@.service to track PID of login shell ($$) and stop graphical session when it exits:

systemctl --user start wayland-session-bindpid@$$.service

Add --wait to hold the terminal until session ends, exec it to replace login shell with systemctl invocation reusing its PID, also use wayland-session-envelope@${compositor}.target instead of main service to wait until proper environment teardown at the end.

exec systemctl --user start --wait wayland-session-envelope@${compositor}.target

This makes the end of login shell also be the end of wayland session and vice versa.

Alternatively, for graceful handling of the parent login process one can use trap for TERM and HUP signals in the shell for forking systemctl process protected from direct termination and run systemctl --user stop wayland-wm@${compositor}.service (also protected from signals) upon receiving SIGTERM.

When wayland-wm-env@.service is started during graphical-session-pre.target startup, uwsm aux prepare-env ${compositor} is launched (with shared set of custom arguments).

It looks for environment saved by uwsm start command, then runs shell code to prepare environment. The code sources POSIX shell profile (if environment from uwsm start was not found), common and desktop-matching uwsm/env*, uwsm/env*.d/* files, anything that plugins dictate.

Environment state at the end of shell code is given back to the main process. uwsm is also smart enough to find login session associated with current TTY and set $XDG_SESSION_ID, $XDG_VTNR if it was not found in the context saved by uwsm start. In this case the presence of wayland-session-bindpid@.service being active is also checked, and an instance pointing to login session leader is launched automatically if none found, as the last best effort at binding to login session lifetime.

The difference between initial env (that is the state of activation environment) and after all the sourcing and setting is done, plus Varnames.always_export, minus Varnames.never_export, is added to activation environment of systemd user manager and D-Bus.

Those variable names, plus Varnames.always_cleanup minus Varnames.never_cleanup are written to a cleanup list file in runtime dir.

Startup finalization

This step is not needed if compositor at least puts WAYLAND_DISPLAY into systemd activation environment: uwsm will autodetect this and handle the rest. If something goes wrong, startup can be fixed by using combination of uwsm finalize command and configuration variables UWSM_FINALIZE_VARNAMES, UWSM_WAIT_VARNAMES, UWSM_WAIT_VARNAMES_SETTLETIME

wayland-wm@.service uses Type=notify and waits for compositor to signal started state. Activation environments will also need to receive essential variables like WAYLAND_DISPLAY to launch graphical applications successfully.

A forked process inside wayland-wm@.service waits for WAYLAND_DISPLAY and all vars mentioned in UWSM_WAIT_VARNAMES, then signals unit readiness and restricts notification socket access from all to exec. It also appends variable cleanup list with any delta it has seen since unit startup.

Separate wayland-session-waitenv.service does the same waiting thing and either exits successfully allowing graphical-session.target to proceed, or times out, bringing everything down.

uwsm finalize [VAR [VAR2...]] can be run by compositor, essentially it performs actions analogous to:

dbus-update-activation-environment WAYLAND_DISPLAY DISPLAY [VAR [VAR3...]]
systemctl --user import-environment WAYLAND_DISPLAY DISPLAY [VAR [VAR3...]]
systemd-notify READY=1 NOTIFYACCESS=exec

(dbus-update-activation-environment action equivalent is redundant for dbus-broker and is skipped automatically)

Additional variable names are taken from UWSM_FINALIZE_VARNAMES var.

Only defined variables are used. Variables that are not blacklisted by Varnames.never_cleanup set are also added to cleanup list in the runtime dir.

Stop

Just stop the main service: systemctl --user stop "wayland-wm@${compositor}.service", everything else will be stopped by systemd.

Wildcard systemctl --user stop "wayland-wm@*.service" will also work, as does stopping wayland-session@*.target

Or activate shutdown target: systemctl --user start wayland-session-shutdown.target

If an instance of wayland-session-bindpid@.service is active and pointing to a PID in login session, any of the above stop commands also doubles as a logout command.

When wayland-wm-env@${compositor}.service is stopped, uwsm aux cleanup-env is launched. It looks for any cleanup files (uwsm/env_cleanup_*.list) in runtime dir. Listed variables, plus Varnames.always_cleanup minus Varnames.never_cleanup are emptied in D-Bus activation environment and unset from systemd user manager environment.

When no compositor is running, units can be removed (-r) by uwsm stop -r.

Add compositor to -r to remove only customization drop-ins: uwsm stop -r ${compositor}.

Profile integration

This example does the same thing as check may-start + start subcommand combination described earlier: starts wayland session automatically upon login on tty1 if system is in graphical.target

Screening for being in interactive login shell here is essential ([ "${0}" != "${0#-}" ]). wayland-wm-env@${compositor}.service sources profile, which has a potential for nasty loops if run unconditionally. Other conditions are a recommendation:

MY_COMPOSITOR=sway
if [ "${0}" != "${0#-}" ] &&
   ! systemctl --user is-active -q wayland-wm@*.service &&
   [ "$XDG_VTNR" = "1" ] &&
   {
       # wait while graphical.target is in startup queue
       while case "$(systemctl list-jobs --plain --no-legend --full graphical.target)" in
       *start*) true ;; *) false ;; esac; do
         sleep 1
       done
       systemctl is-active -q graphical.target
   }
then
    # generate units
    uwsm start -o ${MY_COMPOSITOR}

    # save login environment
    mkdir -p "$XDG_RUNTIME_DIR/uwsm"
    env -0 > "$XDG_RUNTIME_DIR/uwsm/env_login"

    # bind wayland session to login shell PID $$ and start compositor
    echo Starting ${MY_COMPOSITOR} compositor
    systemctl --user start wayland-session-bindpid@$$.service

    # do not die right away on signals, stop gracefully
    trap "trap '' TERM HUP INT; systemctl --user stop --wait wayland-wm@${MY_COMPOSITOR}.service; wait \$SCPID; exit" TERM HUP INT
    {
    	trap '' TERM HUP INT
    	exec systemctl --user start --wait wayland-wm@${MY_COMPOSITOR}.service
    } &
    SCPID=$!
    # hold session open
    wait $SCPID
fi

uwsm start also replaces itself with lightweight shell signal handler with similar algorithm that holds the login session open until the compositor unit is deactivated and prevents premature end of login session and login process.