.\" Generated by scdoc 1.11.3
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "UWSM" "1" "2025-01-30"
.PP
.SH NAME
.PP
\fBUWSM\fR - Universal Wayland Session Manager.\&
.PP
.SH SYNOPSIS
.PP
\fBuwsm\fR [-h] {\fIsubcommand\fR} [\fIoptions\fR .\&.\&.\&]
.PP
.SH DESCRIPTION
.PP
Launches arbitrary wayland compositor via a set of systemd user units to
provide graphical user session with environment management, XDG autostart
support, clean shutdown.\& Provides helpers for launching applications as
scopes or services.\&
.PP
.SH SUBCOMMANDS
.PP
.TS
l lx
l lx
l lx
l lx
l lx
l lx
l lx.
T{
\fBselect\fR
T}	T{
Select default compositor Entry.\&
T}
T{
\fBstart\fR
T}	T{
Start compositor and graphical session.\&
T}
T{
\fBfinalize\fR
T}	T{
Send compositor-set variables and unit startup notification to systemd user manager.\&
T}
T{
\fBstop\fR
T}	T{
Stop graphical session and compositor.\&
T}
T{
\fBapp\fR
T}	T{
Application unit launcher (with Desktop Entry support).\&
T}
T{
\fBcheck\fR
T}	T{
Perform state checks (for scripting and info).\&
T}
T{
\fBaux\fR
T}	T{
Technical functions for use inside units.\&
T}
.TE
.sp 1
See corresponding \fISUBCOMMANDS\fR subsections below for further info.\&
.PP
Help for each subcommand is accessible by running "\fBuwsm\fR {\fIsubcommand\fR} \fB-h\fR".\&
.PP
.SH CONFIGURATION
.PP
.SS Files
.PP
In XDG config hierarchy:
.TS
l lx
l lx
l lx.
T{
\fBuwsm/env\fR
T}	T{

T}
T{
\fBuwsm/env-\fR\fI${compositor}\fR
T}	T{
Environment (shell) to be sourced for the graphical session.\& Sourced from directories of increasing priority, in each directory common file is sourced first, then suffixed files in the order of items listed in \fBXDG_CURRENT_SESSION\fR var (lowercased).\&
T}
T{
\fBuwsm/default-id\fR
T}	T{
Stores Desktop Entry ID of default compositor.\&
T}
.TE
.sp 1
Fallback is also extended into the system part of XDG data hierarchy, this can
be used for distro level defaults.\&
.PP
.SS Environment vars
.PP
.TS
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx.
T{
\fBUWSM_USE_SESSION_SLICE\fR
T}	T{
(\fBtrue\fR|\fBfalse\fR)
T}
T{

T}	T{
Put compositor unit in \fBsession.\&slice\fR
T}
T{
\fBUWSM_FINALIZE_VARNAMES\fR
T}	T{
(whitespace-separated names of env vars)
T}
T{

T}	T{
Additional variables for "\fBuwsm finalize\fR"
T}
T{
\fBUWSM_WAIT_VARNAMES\fR
T}	T{
(whitespace-separated names of env vars)
T}
T{

T}	T{
Variables to wait for in activation environemnt before proceeding to graphical session (in addition to \fBWAYLAND_DISPLAY\fR)
T}
T{
\fBUWSM_WAIT_VARNAMES_SETTLETIME\fR
T}	T{
(float value)
T}
T{

T}	T{
Seconds to pause after all expected vars found in activation environment
T}
T{
\fBUWSM_APP_UNIT_TYPE\fR
T}	T{
(\fBservice\fR|\fBscope\fR)
T}
T{

T}	T{
Default unit type for launching apps
T}
T{
\fBDEBUG\fR
T}	T{
Dump debug info to stderr
T}
.TE
.sp 1
.SH OPERATION OVERVIEW
.PP
.SS Login Sequence Integration
.PP
\fBuwsm\fR can be launched by using conditional \fBexec\fR in shell profile to replace
login shell (see \fIShell Profile Integration\fR section).\&
.PP
Alternatively "\fBuwsm start\fR .\&.\&.\&" command can be put into wayland session'\&s
Desktop Entry to be launched by a display manager (see \fIUse Inside Desktop
Entry\fR section).\&
.PP
.SS Compositor Selection
.PP
\fBuwsm\fR can run arbitrary compositor command line or a Desktop Entry by ID
(specifying Action ID is also supported).\&
.PP
Desktop Entry can also be selected via a \fBwhiptail\fR menu (see \fIselect\fR
subcommand section).\&
.PP
.SS Startup
.PP
See \fIstart\fR subcommand section for command syntax.\&
.PP
A set of runtime units bound to standard user session targets is generated:
.PP
.PD 0
.IP \(bu 4
\fBwayland-session-pre@.\&target\fR (bound to \fBgraphical-session-pre.\&target\fR)
.RS 4
.IP \(bu 4
\fBwayland-wm-env@.\&service\fR (environment preloader service)
.RE
.IP \(bu 4
\fBwayland-session@.\&target\fR (bound to \fBgraphical-session.\&target\fR)
.RS 4
.IP \(bu 4
\fBwayland-wm@.\&service\fR (service for the selected compositor)
.RE
.IP \(bu 4
\fBwayland-session-xdg-autostart@.\&target\fR (bound to
\fBxdg-desktop-autostart.\&target\fR)
.IP \(bu 4
\fBwayland-session-shutdown.\&target\fR (conflicts with targets above for shutdown)
.IP \(bu 4
\fBwayland-session-bindpid@.\&service\fR (PID-tracking session killswitch)
.IP \(bu 4
\fBwayland-session-waitenv.\&service\fR (delays graphical session until vars appear)
.PD
.PP
Compositor ID (Desktop Entry ID or executable name) becomes the specifier
for all templated units.\&
.PP
At the stage of \fBgraphical-session-pre.\&target\fR, the environment is sourced from
the shell profile and from uwsm environment \fIfiles\fR.\& The delta is exported to
the systemd and D-Bus activation environments by the environment preloader
service and is marked for cleanup at shutdown stage.\& Preloader shell context for
convenience has \fBIN_UWSM_ENV_PRELOADER\fR var set to \fBtrue\fR.\&
.PP
At the stage of \fBgraphical-session.\&target\fR (before it) the main compositor unit
\fBwayland-wm@\fR\fI${ID}\fR\fB.\&service\fR and \fBwayland-session-waitenv.\&service\fR are
started.\&
.PP
Compositor should at least put \fBWAYLAND_DISPLAY\fR variable to systemd activation
environment.\& This will trigger uwsm'\&s automatic finalization logic.\& Without
\fBWAYLAND_DISPLAY\fR in activation environment startup will timeout in 10 seconds.\&
.PP
Manual finalization is possible by running "\fBuwsm finalize\fR" (see \fIfinalize\fR
subcommand section), also in combination with tweaking \fBUWSM_WAIT_VARNAMES\fR
and \fBUWSM_WAIT_VARNAMES_SETTLETIME\fR vars (see \fIEnvironment vars\fR section).\&
.PP
Successful activation of compositor unit and existence of \fBWAYLAND_DISPLAY\fR
in activation environment will allow \fBgraphical-session.\&target\fR to be declared
reached.\&
.PP
Finally, \fBxdg-desktop-autostart.\&target\fR is activated.\&
.PP
.SS Inside session
.PP
It is highly recommended to configure the compositor or app launcher to launch
apps as scopes or services in special user session slices (\fBapp.\&slice\fR,
\fBbackground.\&slice\fR, \fBsession.\&slice\fR).\& \fBuwsm\fR provides custom nested slices for
apps to live in and be terminated on session end:
.PD 0
.IP \(bu 4
\fBapp-graphical.\&slice\fR
.IP \(bu 4
\fBbackground-graphical.\&slice\fR
.IP \(bu 4
\fBsession-graphical.\&slice\fR
.PD
.PP
A helper \fBapp\fR subcommand is provided to handle all the systemd-run invocations
for you (see \fIapp\fR subcommand section).\&
.PP
If app launching is configured as recommended, \fBuwsm\fR can be set to launch
the compositor in \fBsession.\&slice\fR (as recommended by \fBsystemd.\&special\fR(7)) by
adding "-S" to \fBstart\fR subcommand, or adding this to the environment in which
"\fBuwsm start\fR" is launched:
.PP
.RS 4
UWSM_USE_SESSION_SLICE=true
.PP
.RE
.SS Shutdown
.PP
Can be initiated by either:
.PD 0
.IP \(bu 4
running \fBuwsm stop\fR
.IP \(bu 4
stopping \fBwayland-wm@*.\&service\fR
.IP \(bu 4
starting \fBwayland-session-shutdown.\&target\fR
.PD
.PP
Systemd stops all user units in reverse, as it usually does.\& During deactivation
of \fBgraphical-session-pre.\&target\fR, the environment preloader service cleans
activation environments by unsetting all variables that were marked for removal
during startup and finalization stages.\&
.PP
Do not use compositor'\&s native exit mechanism or kill its process directly.\&
.PP
.SH SUBCOMMANDS
.PP
.SS select
.PP
Selects default wayland session compositor Desktop Entry.\&
.PP
.RS 4
\fBuwsm\fR select
.PP
.RE
Invokes a whiptail menu to select default session among Desktop Entries in
\fBwayland-sessions\fR XDG data hierarchy.\& Writes to
\fB${XDG_CONFIG_HOME}/uwsm/default-id\fR.\& Nothing else is done.\& Returns \fB1\fR if
selection is cancelled.\& Can be used for scripting launch condition in shell
profile.\&
.PP
.SS check
.PP
Performs tests, returns \fB0\fR on success, \fB1\fR on failure.\&
.PP
\fBis-active\fR:
.PP
.RS 4
\fBuwsm\fR check is-active [-h] [-v] [\fIcompositor\fR]
.PP
.RE
.TS
l lx
l lx.
T{
    \fB-v\fR
T}	T{
show additional info
T}
T{
    \fIcompositor\fR
T}	T{
check for specific compositor
T}
.TE
.sp 1
.PP
Checks if unit of specific \fBcompositor\fR or \fBgraphical-session*.\&target\fR in
general is in active or activating state.\&
.PP
\fBmay-start\fR:
.PP
.RS 4
\fBuwsm\fR check may-start [-h] [-g [\fIS\fR]] [-v|-q] [\fIN\fR .\&.\&.\&]
.PP
.RE
.TS
l lx
l lx
l lx
l lx.
T{
    \fB-g\fR \fIS\fR
T}	T{
wait \fIS\fR seconds for graphical.\&target in queue (default: 60; 0 or less disables check).\&
T}
T{
    \fB-v\fR
T}	T{
show all failed tests
T}
T{
    \fB-q\fR
T}	T{
be quiet
T}
T{
    \fIN\fR .\&.\&.\&
T}	T{
allowed VT numbers (default: 1)
T}
.TE
.sp 1
.PP
Checks whether it is OK to launch a wayland session via the following conditions:
.PD 0
.IP \(bu 4
Running from login shell
.IP \(bu 4
System is at \fBgraphical.\&target\fR
.IP \(bu 4
User \fBgraphical-session*.\&target\fR units are not yet active
.IP \(bu 4
Foreground VT is among allowed (default: 1)
.PD
.PP
.SS start
.PP
Generates units for given compositor command line or Desktop Entry and starts
them.\&
.PP
.RS 4
\fBuwsm\fR start [-h] [-D \fIname\fR[:\fIname\fR.\&.\&.\&]] [-a|-e] [-N \fIName\fR] [-C \fIComment\fR]
[-S|-A] [-o] [-n] -- \fIcompositor\fR [\fIargs\fR .\&.\&.\&]
.PP
.RE
.TS
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx.
T{
    \fB-F\fR
T}	T{
Hardcode mode, always write command line to unit drop-ins and use full paths.\&
T}
T{
    \fB-D\fR \fIname\fR[:\fIname\fR.\&.\&.\&]
T}	T{
Names to fill \fBXDG_CURRENT_DESKTOP\fR with (:-separated).\& Existing var content is a starting point if no active session is running.\&
T}
T{
    \fB-a\fR
T}	T{
Append desktop names set by -D to other sources (default).\&
T}
T{
    \fB-e\fR
T}	T{
Use desktop names set by -D exclusively, discard other sources.\&
T}
T{
    \fB-N\fR \fIName\fR
T}	T{
Fancy name for compositor (filled from Desktop Entry by default).\&
T}
T{
    \fB-C\fR \fIComment\fR
T}	T{
Fancy description for compositor (filled from Desktop Entry by default).\&
T}
T{
    \fB-S\fR
T}	T{
Launch compositor in session.\&slice.\&
T}
T{
    \fB-A\fR
T}	T{
Launch compositor in app.\&slice.\&
T}
T{
    \fB-o\fR
T}	T{
Only generate units, but do not start.\&
T}
T{
    \fB-n\fR
T}	T{
Do not write or start anything.\&
T}
.TE
.sp 1
The first argument of the compositor command line acts as an ID and should be
either one of:
.PD 0
.IP \(bu 4
Executable name
.IP \(bu 4
Desktop Entry ID (optionally with "\fB:\fR"-delimited action ID)
.IP \(bu 4
Special value:
.RS 4
.IP \(bu 4
\fBselect\fR - invoke menu to select compositor.\&
.IP \(bu 4
\fBdefault\fR - run previously selected compositor (or select if no
selection was saved).\&
.PD
.PP
.RE
If given as path, hardcode mode will be used implicitly.\&
.PP
Always use "\fB--\fR" to disambiguate dashed arguments intended for compositor
itself.\&
.PP
After units are (re)generated, \fBwayland-session-bindpid@\fR\fI${PID}\fR\fB.\&service\fR is
started, to track the PID of invoking \fBuwsm\fR, then \fBuwsm\fR process replaces
itself with \fBsystemctl\fR execution that starts \fBwayland-wm@\fR\fI${ID}\fR\fB.\&service\fR
and waits for it to finish.\&
.PP
In order to complete the startup sequence, the compositor has to put
\fBWAYLAND_DISPLAY\fR into the systemd activation environment.\& This can be done
explicitly by making compositor run "\fBuwsm finalize\fR" command (see the next
subsection).\&
.PP
.SS finalize
.PP
For running by a compositor on startup.\&
.PP
.RS 4
\fBuwsm\fR finalize [-h] [\fIVAR_NAME\fR .\&.\&.\&]
.PP
.RE
Exports \fBWAYLAND_DISPLAY\fR, \fBDISPLAY\fR and any defined vars mentioned by names
in arguments or in \fBUWSM_FINALIZE_VARNAMES\fR variable (whitespace-separated).\&
Then sends startup notification for the unit to systemd user manager.\&
.PP
\fBThis is required\fR if compositor itself does not put \fBWAYLAND_DISPLAY\fR to
systemd activation environment, otherwise \fBwayland-session@.\&service\fR unit
or a dedicated \fBwayland-session-waitenv.\&service\fR unit will terminate due to
startup timeout.\&
.PP
\fBUWSM_FINALIZE_VARNAMES\fR variable can be prefilled by plugins.\&
.PP
Direct assignment as \fIVAR_NAME\fR=\fIvalue\fR is also possible, but recommended only
for creating flags for \fBUWSM_WAIT_VARNAMES\fR mechanism.\&
.PP
.SS stop
.PP
Stops compositor and optionally removes generated units.\&
.PP
.RS 4
\fBuwsm\fR stop [-h] [-r [\fIcompositor\fR] [-n]
.PP
.RE
.TS
l lx
l lx.
T{
\fB-r\fR [\fIcompositor\fR]
T}	T{
Also remove units (all or only \fIcompositor\fR-specific).\&
T}
T{
\fB-n\fR
T}	T{
Dry run, do not stop or remove anything.\&
T}
.TE
.sp 1
.SS app
.PP
Application-to-unit launcher with Desktop Entry support.\&
.PP
.RS 4
\fBuwsm\fR app [-h] [-s {\fBa\fR,\fBb\fR,\fBs\fR,\fIcustom\fR.\&slice}] [-t {scope,service}]
[-a \fIapp_name\fR] [-u \fIunit_name\fR] [-d \fIunit_description\fR]
[-S ] [-T] -- \fIapplication\fR[\fIargs\fR .\&.\&.\&]
.PP
.RE
.TS
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx.
T{
\fB-s\fR {\fBa\fR,\fBb\fR,\fBs\fR,\fIcustom\fR.\&slice}
T}	T{
Slice selector (default: \fBa\fR):
T}
T{

T}	T{
   \fBa\fR - \fBapp-graphical.\&slice\fR
T}
T{

T}	T{
   \fBb\fR - \fBbackground-graphical.\&slice\fR
T}
T{

T}	T{
   \fBs\fR - \fBsession-graphical.\&slice\fR
T}
T{

T}	T{
   any slice by full name
T}
T{
\fB-t\fR {\fBscope\fR,\fBservice\fR}
T}	T{
Type of unit to launch (default: \fBscope\fR, can be preset by \fBUWSM_APP_UNIT_TYPE\fR env var).\&
T}
T{
\fB-a\fR \fIapp_name\fR
T}	T{
Override app name (a substring in unit name).\&
T}
T{
\fB-u\fR \fIunit_name\fR
T}	T{
Override the whole autogenerated unit name.\&
T}
T{
\fB-d\fR \fIunit_description\fR
T}	T{
Unit Description.\&
T}
T{
\fB-S\fR {\fBout\fR,\fBerr\fR,\fBboth\fR}
T}	T{
Silence stdout, stderr, or both.\&
T}
T{
\fB-T\fR
T}	T{
Launch app in a terminal.\& Allows command to be empty to just launch a terminal.\&
T}
.TE
.sp 1
.PP
Application can be provided as a command with optional arguments, or a Desktop
Entry ID, optionally suffixed with "\fB:\fR"-delimited Action ID.\& If Destop Entry
is being launched, arguments should be compatible with it.\&
.PP
Always use "\fB--\fR" to disambiguate dashed arguments intended for application
itself.\&
.PP
.SS aux
.PP
For use in systemd user services.\& Can only be called by systemd user manager.\&
.PP
.TS
l lx
l lx
l lx
l lx.
T{
\fBprepare-env\fR
T}	T{
Prepares environment (for use in ExecStart in \fBwayland-wm-env@.\&service\fR bound to \fBwayland-session-pre@.\&target\fR).\&
T}
T{
\fBcleanup-env\fR
T}	T{
Cleans up environment (for use ExecStop in in \fBwayland-wm-env@.\&service\fR bound to \fBwayland-session-pre@.\&target\fR).\&
T}
T{
\fBexec\fR
T}	T{
Executes a command with arguments or a desktop entry (for use in Exec in \fBwayland-wm@.\&service\fR bound to \fBwayland-session@.\&target\fR).\&
T}
T{
\fBapp-daemon\fR
T}	T{
Daemon for faster app argument generation, used by \fBuwsm-app\fR client.\&
T}
.TE
.sp 1
.SH APP DAEMON
.PP
Provided as \fBwayland-wm-app-daemon.\&service\fR to be started on-demand.\&
.PP
Daemon receives app arguments from \fB${XDG_RUNTIME_DIR}/uwsm-app-daemon-in\fR
pipe.\&
Resulting arguments are formatted as shell code and written to
\fB${XDG_RUNTIME_DIR}/uwsm-app-daemon-out\fR pipe.\&
.PP
Arguments are expected to be \fB\e0\fR-delimited, leading \fB\e0\fR are stripped.\&
One command is received per write+close.\&
.PP
The first argument determines the behavior:
.PP
.PD 0
.IP \(bu 4
\fBapp\fR	the rest is processed the same as in "uwsm app"
.IP \(bu 4
\fBping\fR	just "pong" is returnedn
.IP \(bu 4
\fBstop\fR	daemon is stoppedn
.PD
.PP
.PP
Single commands are prepended with \fBexec\fR, iterated commands are assembled with
trailing \fB&\fR each, followed by \fBwait\fR.\&
.PP
The purpose of all this is to skip all the expensive Python startup and import
routines that slow things down every time "\fBuwsm app\fR" is called.\& Instead the
daemon does it once and then listens for requests, while a simple shell script
may dump arguments to one pipe and run the code received from another via eval,
which is much faster.\&
.PP
The simplest script is:
.PP
.nf
.RS 4
	#!/bin/sh
	printf \&'0%s\&' app "$@" > "${XDG_RUNTIME_DIR}/uwsm-app-daemon-in"
	IFS=\&'\&' read -r cmd < "${XDG_RUNTIME_DIR}/uwsm-app-daemon-out"
	eval "$cmd"
.fi
.RE
.PP
Provided \fBuwsm-app\fR client script is a bit smarter: it can start the daemon,
applies timeouts, and supports newlines in returned args.\&
.PP
.SH SHELL PROFILE INTEGRATION
.PP
To launch \fBuwsm\fR automatically on login, add one of constructs below (or
similar) to shell profile.\&
.PP
This asks to select a compositor (or refuse and continue with login shell)
when logged in on VT 1:
.PP
.nf
.RS 4
	if uwsm may-start && uwsm select; then
		exec systemd-cat -t uwsm_start uwsm start default
	fi
.fi
.RE
.PP
This just starts a specific compositor depending on foreground VT:
.PP
.nf
.RS 4
	if uwsm may-start 1; then
		exec systemd-cat -t uwsm_start uwsm start sway\&.desktop
	elif uwsm may-start 2; then
		exec systemd-cat -t uwsm_start uwsm start labwc\&.desktop
	fi
.fi
.RE
.PP
Using "\fBuwsm check may-start\fR" as a condition is \fBessential\fR, not only to
prevent accidental startup attempts where they are not expected, but also since
startup involves sourcing shell profile, which might lead to nasty loops.\&
.PP
See \fIcheck\fR subcommand section for info on \fBmay-start\fR checker.\&
.PP
\fBexec\fR allows uwsm to replace login shell in order to properly bind to user
session and handle session termination.\&
.PP
"\fBsystemd-cat -t uwsm_start\fR" (optional) executes the command given to it
(\fBuwsm\fR) with its stdout and stderr connected to the systemd journal, tagged
with identifier "uwsm_start".\& See \fIsystemd-cat(1)\fR for more options.\&
.PP
.SH USE INSIDE DESKTOP ENTRY
.PP
To launch \fBuwsm\fR from a display/login manager, "\fBuwsm start\fR" can be used inside
Desktop Entries.\& Example
\fB/usr/local/share/wayland-sessions/my-compositor.\&desktop\fR:
.PP
.nf
.RS 4
	[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
.fi
.RE
.PP
Things to keep in mind:
.PP
.PD 0
.IP \(bu 4
For consistency, command line arguments should mirror the keys of the entry
.IP \(bu 4
Command in \fBExec=\fR should start with "\fBuwsm start\fR"
.IP \(bu 4
It should not point to itself (as a combination of Desktop Entry ID and Action
ID)
.IP \(bu 4
It should not point to a Desktop Entry ID and Action ID that also uses `uwsm`
.PD
.PP
Potentially such entries may be found and used by \fBuwsm\fR itself, i.\&e.\& in shell
profile integration situation, or when launched manually.\& Following the
principles above ensures \fBuwsm\fR will properly recognize itself and parse
requested arguments inside the entry without any side effects.\&
.PP
.SH SEE ALSO
.PP
\fBuwsm-plugins\fR(3), \fBsystemd-run\fR(1), \fBsystemd-cat\fR(1), \fBsystemd.\&special\fR(7)