Jump to content

# Universal Wayland Session Manager

From ArchWiki

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, a Wayland application run as a systemd service needs the `WAYLAND_DISPLAY` environment variable (or `DISPLAY` 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 values.

The command `uwsm finalize` puts `WAYLAND_DISPLAY`, `DISPLAY` and other environment variables listed via the white-space separated `UWSM_FINALIZE_VARNAMES` list into the activation environment. It is recommended to execute this command after the compositor is ready.

If other variables set by the compositors are needed in the activation environment, they can be passed as arguments to `uwsm finalize` or put into a white-space separated list in `UWSM_FINALIZE_VARNAMES`. See the examples below:

    exec uwsm finalize VAR1 VAR2 ...
    export UWSM_FINALIZE_VARNAMES=VAR1 VAR2 ...

### Environment variables

All environment variables set in `${XDG_CONFIG_HOME}/uwsm/env` 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.

An example of such a file can be seen below:

    ~/.config/uwsm/env

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

## Usage

### Startup

Note Environment preloader no longer sources POSIX shell profile if environment from the context of `uwsm start` was successfully used.

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).

Note 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.

## Tips and tricks

### Applications and autostart

By default uwsm launches compositors through a custom systemd service in `session.slice`. Many Wayland compositors allow you to start other applications that would then be launched inside the compositor service, which would uselessly consume compositor resources or even interfere with notification sockets.

To start applications as separate systemd scope units you can use `uwsm app`, which can launch both executables

    uwsm app -- /my/program/path

and desktop entries

    uwsm app -- myprogram.desktop

By default uwsm puts launched scope units in `app-graphical.slice` slice. If you want to put them in `background-graphical.slice` or `session-graphical.slice`, then you should respectively use options `-s b`, `-s s`:

    uwsm app -s b -- background-app.desktop

#### Alternatives

Instead of `uwsm app` (which runs as a Python script), you can use a faster alternative:

- uwsm's `uwsm-app` script which communicates with uwsm's app daemon.
- app2unit-gitAUR, which is a shell script. You can use it as a drop-in replacement of `uwsm app` by setting the `APP2UNIT_SLICES` environment variable as follows:

      APP2UNIT_SLICES='a=app-graphical.slice b=background-graphical.slice s=session-graphical.slice'

- runappAUR, which is written in C++, but missing some features.

## See also

- uwsm(1)

Category:

- Wayland

Universal Wayland Session Manager
Add topic