Universal Wayland Session Manager - ArchWiki

Jump to content

# Universal Wayland Session Manager

1 language

- 日本語

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 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.
Category:

- Wayland