navigine/bat
1
0 Fork 0
mirror of https://github.com/sharkdp/bat.git synced 2026-10-28 08:05:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

Fixed manpage syntax-test format

Browse Source
This commit is contained in:
Guy Barzilai committed 2026-02-19 18:11:36 +02:00
1 parent 5bd08845a3
commit a71d16fa1b
1 file changed
+376 -376
Download Patch File Download Diff File Expand all files Collapse all files
tests/syntax-tests/highlighted/Manpage/uwsm-0.26.3.man
Vendored
+376 -376
View File
@@ -1,399 +1,399 @@
UWSM(1) General Commands Manual UWSM(1) UWSM(1) General Commands Manual UWSM(1)
NAME NAME
UWSM - Universal Wayland Session Manager.  UWSM - Universal Wayland Session Manager.
SYNOPSIS SYNOPSIS
uwsm [-h|-v] {subcommand} [options ...]  uwsm [-h|-v] {subcommand} [options ...]
DESCRIPTION DESCRIPTION
Launches arbitrary wayland compositor via a set of systemd user units to provide graphical user  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  session with environment management, XDG autostart support, clean shutdown. Provides helpers
for launching applications as scopes or services.  for launching applications as scopes or services.
SUBCOMMANDS SUBCOMMANDS
select Select default compositor Entry.  select Select default compositor Entry.
start Start compositor and graphical session.  start Start compositor and graphical session.
finalize Send compositor-set variables and unit startup notification to systemd user manager.  finalize Send compositor-set variables and unit startup notification to systemd user manager.
stop Stop graphical session and compositor.  stop Stop graphical session and compositor.
app Application unit launcher (with Desktop Entry support).  app Application unit launcher (with Desktop Entry support).
check Perform state checks (for scripting and info).  check Perform state checks (for scripting and info).
aux Technical functions for use inside units.  aux Technical functions for use inside units.
See corresponding SUBCOMMANDS subsections below for further info.  See corresponding SUBCOMMANDS subsections below for further info.
Help for each subcommand is accessible by running "uwsm {subcommand} -h".  Help for each subcommand is accessible by running "uwsm {subcommand} -h".
CONFIGURATION CONFIGURATION
Files  Files
In XDG config hierarchy:  In XDG config hierarchy:
uwsm/env  uwsm/env
uwsm/env.d/*  uwsm/env.d/*
uwsm/env-${compositor}  uwsm/env-${compositor}
uwsm/env-${compositor}.d/* Environment (shell) to be sourced for the graphical session.  uwsm/env-${compositor}.d/* Environment (shell) to be sourced for the graphical session.
Sourced from directories of increasing priority, in each directory  Sourced from directories of increasing priority, in each directory
common file is sourced first, then suffixed files in the order of  common file is sourced first, then suffixed files in the order of
items listed in XDG_CURRENT_SESSION var (lowercased).  items listed in XDG_CURRENT_SESSION var (lowercased).
uwsm/default-id Stores Desktop Entry ID of default compositor.  uwsm/default-id Stores Desktop Entry ID of default compositor.
Fallback is also extended into the system part of XDG data hierarchy, this can be used for dis‐  Fallback is also extended into the system part of XDG data hierarchy, this can be used for dis‐
tro level defaults.  tro level defaults.
Environment vars  Environment vars
UWSM_UNIT_RUNG (run|home)  UWSM_UNIT_RUNG (run|home)
Which rung of systemd/user/ hierarchy to manage generated unit  Which rung of systemd/user/ hierarchy to manage generated unit
and drop-in files in: $XDG_RUNTIME_DIR or $XDG_CONFIG_HOME.  and drop-in files in: $XDG_RUNTIME_DIR or $XDG_CONFIG_HOME.
UWSM_TWEAKS (boolean value)  UWSM_TWEAKS (boolean value)
Set to False to remove and not generate tweak drop-ins for  Set to False to remove and not generate tweak drop-ins for
other software.  other software.
UWSM_FINALIZE_VARNAMES (whitespace-separated names of env vars)  UWSM_FINALIZE_VARNAMES (whitespace-separated names of env vars)
Additional variables for "uwsm finalize".  Additional variables for "uwsm finalize".
UWSM_WAIT_VARNAMES (whitespace-separated names of env vars)  UWSM_WAIT_VARNAMES (whitespace-separated names of env vars)
Variables to wait for in activation environment before proceed‐  Variables to wait for in activation environment before proceed‐
ing to graphical session (in addition to WAYLAND_DISPLAY).  ing to graphical session (in addition to WAYLAND_DISPLAY).
UWSM_WAIT_VARNAMES_TIMEOUT (int value)  UWSM_WAIT_VARNAMES_TIMEOUT (int value)
Seconds to wait for variables to appear in activation environ‐  Seconds to wait for variables to appear in activation environ‐
ment. Essentially, startup timeout (default: 10).  ment. Essentially, startup timeout (default: 10).
UWSM_WAIT_VARNAMES_SETTLETIME (float value)  UWSM_WAIT_VARNAMES_SETTLETIME (float value)
Seconds to pause after all expected vars found in activation  Seconds to pause after all expected vars found in activation
environment (default: 0.2).  environment (default: 0.2).
UWSM_APP_UNIT_TYPE (scope|service)  UWSM_APP_UNIT_TYPE (scope|service)
Default unit type for launching apps (default: scope).  Default unit type for launching apps (default: scope).
UWSM_SILENT_START (int or boolean value)  UWSM_SILENT_START (int or boolean value)
True or 1 to inhibit stdout messages from "uwsm start". 2 to  True or 1 to inhibit stdout messages from "uwsm start". 2 to
also inhibit warnings.  also inhibit warnings.
DEBUG (int or boolean value)  DEBUG (int or boolean value)
True or positive number to dump debug info to stderr.  True or positive number to dump debug info to stderr.
OPERATION OVERVIEW OPERATION OVERVIEW
Login Sequence Integration  Login Sequence Integration
uwsm can be launched by using conditional exec in shell profile to replace login shell (see  uwsm can be launched by using conditional exec in shell profile to replace login shell (see
Shell Profile Integration section).  Shell Profile Integration section).
Alternatively "uwsm start ..." command can be put into wayland session's Desktop Entry to be  Alternatively "uwsm start ..." command can be put into wayland session's Desktop Entry to be
launched by a display manager (see Use Inside Desktop Entry section).  launched by a display manager (see Use Inside Desktop Entry section).
Compositor Selection  Compositor Selection
uwsm can run arbitrary compositor command line or a Desktop Entry by ID (specifying Action ID  uwsm can run arbitrary compositor command line or a Desktop Entry by ID (specifying Action ID
is also supported).  is also supported).
Desktop Entry can also be selected via a whiptail menu (see select subcommand section).  Desktop Entry can also be selected via a whiptail menu (see select subcommand section).
Startup  Startup
See start subcommand section for command syntax.  See start subcommand section for command syntax.
UWSM uses a set of units bound to standard user session targets:  UWSM uses a set of units bound to standard user session targets:
• wayland-session-pre@.target (bound to graphical-session-pre.target)  • wayland-session-pre@.target (bound to graphical-session-pre.target)
• wayland-wm-env@.service (environment preloader service)  • wayland-wm-env@.service (environment preloader service)
• wayland-session@.target (bound to graphical-session.target)  • wayland-session@.target (bound to graphical-session.target)
• wayland-wm@.service (service for the selected compositor)  • wayland-wm@.service (service for the selected compositor)
• wayland-session-xdg-autostart@.target (bound to xdg-desktop-autostart.target)  • wayland-session-xdg-autostart@.target (bound to xdg-desktop-autostart.target)
• wayland-session-envelope@.target (lives through entire lifecycle)  • wayland-session-envelope@.target (lives through entire lifecycle)
• wayland-session-shutdown.target (conflicts with targets above for shutdown)  • wayland-session-shutdown.target (conflicts with targets above for shutdown)
• wayland-session-bindpid@.service (PID-tracking session killswitch)  • wayland-session-bindpid@.service (PID-tracking session killswitch)
• wayland-session-waitenv.service (delays graphical session until vars appear)  • wayland-session-waitenv.service (delays graphical session until vars appear)
Compositor ID (Desktop Entry ID or executable name) becomes the specifier for all templated  Compositor ID (Desktop Entry ID or executable name) becomes the specifier for all templated
units.  units.
At the stage of graphical-session-pre.target, the environment saved from "uwsm start" context  At the stage of graphical-session-pre.target, the environment saved from "uwsm start" context
is loaded (or POSIX shell profile is sourced), uwsm environment files are sourced. The delta is  is loaded (or POSIX shell profile is sourced), uwsm environment files are sourced. The delta is
exported to the systemd and D-Bus activation environments by the environment preloader service  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  and is marked for cleanup at shutdown stage. Preloader shell context for convenience has
IN_UWSM_ENV_PRELOADER var set to true.  IN_UWSM_ENV_PRELOADER var set to true.
At the stage of graphical-session.target (before it) the main compositor unit wayland-  At the stage of graphical-session.target (before it) the main compositor unit wayland-
wm@${ID}.service and wayland-session-waitenv.service are started.  wm@${ID}.service and wayland-session-waitenv.service are started.
Compositor should at least put WAYLAND_DISPLAY variable to systemd activation environment. This  Compositor should at least put WAYLAND_DISPLAY variable to systemd activation environment. This
will trigger uwsm's automatic finalization logic. Without WAYLAND_DISPLAY in activation envi‐  will trigger uwsm's automatic finalization logic. Without WAYLAND_DISPLAY in activation envi‐
ronment startup will timeout in 10 seconds.  ronment startup will timeout in 10 seconds.
Manual finalization is possible by running "uwsm finalize" (see finalize subcommand section),  Manual finalization is possible by running "uwsm finalize" (see finalize subcommand section),
also in combination with tweaking UWSM_WAIT_VARNAMES and UWSM_WAIT_VARNAMES_SETTLETIME vars  also in combination with tweaking UWSM_WAIT_VARNAMES and UWSM_WAIT_VARNAMES_SETTLETIME vars
(see Environment vars section).  (see Environment vars section).
Successful activation of compositor unit and existence of WAYLAND_DISPLAY in activation envi‐  Successful activation of compositor unit and existence of WAYLAND_DISPLAY in activation envi‐
ronment will allow graphical-session.target to be declared reached.  ronment will allow graphical-session.target to be declared reached.
Finally, xdg-desktop-autostart.target is activated.  Finally, xdg-desktop-autostart.target is activated.
Inside session  Inside session
It is highly recommended to configure the compositor or app launcher to launch apps as scopes  It is highly recommended to configure the compositor or app launcher to launch apps as scopes
or services in special user session slices (app.slice, background.slice, session.slice). uwsm  or services in special user session slices (app.slice, background.slice, session.slice). uwsm
provides custom nested slices for apps to live in and be terminated on session end:  provides custom nested slices for apps to live in and be terminated on session end:
• app-graphical.slice  • app-graphical.slice
• background-graphical.slice  • background-graphical.slice
• session-graphical.slice  • session-graphical.slice
A helper app subcommand is provided to handle all the systemd-run invocations for you (see app  A helper app subcommand is provided to handle all the systemd-run invocations for you (see app
subcommand section).  subcommand section).
The compositor is launched in session.slice by default (as recommended by systemd.special(7)).  The compositor is launched in session.slice by default (as recommended by systemd.special(7)).
Shutdown  Shutdown
Can be initiated by either:  Can be initiated by either:
• running uwsm stop  • running uwsm stop
• stopping wayland-wm@*.service or wayland-session-envelope@*.target  • stopping wayland-wm@*.service or wayland-session-envelope@*.target
• starting wayland-session-shutdown.target  • starting wayland-session-shutdown.target
Systemd stops all user units in reverse, as it usually does. During deactivation of graphical-  Systemd stops all user units in reverse, as it usually does. During deactivation of graphical-
session-pre.target, the environment preloader service cleans activation environments by unset‐  session-pre.target, the environment preloader service cleans activation environments by unset‐
ting all variables that were marked for removal during startup and finalization stages.  ting all variables that were marked for removal during startup and finalization stages.
Do not use compositor's native exit mechanism or kill its process directly.  Do not use compositor's native exit mechanism or kill its process directly.
SUBCOMMANDS SUBCOMMANDS
select  select
Selects default wayland session compositor Desktop Entry.  Selects default wayland session compositor Desktop Entry.
uwsm select  uwsm select
Invokes a whiptail menu to select default session among Desktop Entries in wayland-sessions XDG  Invokes a whiptail menu to select default session among Desktop Entries in wayland-sessions XDG
data hierarchy. Writes to ${XDG_CONFIG_HOME}/uwsm/default-id. Nothing else is done. Returns 1  data hierarchy. Writes to ${XDG_CONFIG_HOME}/uwsm/default-id. Nothing else is done. Returns 1
if selection is cancelled. Can be used for scripting launch condition in shell profile.  if selection is cancelled. Can be used for scripting launch condition in shell profile.
check  check
Performs tests, returns 0 on success, 1 on failure.  Performs tests, returns 0 on success, 1 on failure.
is-active:  is-active:
uwsm check is-active [-h] [-v] [compositor]  uwsm check is-active [-h] [-v] [compositor]
-v show additional info  -v show additional info
compositor check for specific compositor  compositor check for specific compositor
Checks if unit of specific compositor or graphical-session*.target in general is in active or  Checks if unit of specific compositor or graphical-session*.target in general is in active or
activating state.  activating state.
may-start:  may-start:
uwsm check may-start [-h] [-g [S]] [-v|-q] [N ...]  uwsm check may-start [-h] [-g [S]] [-v|-q] [N ...]
N ... allowed VT numbers (default: 1)  N ... allowed VT numbers (default: 1)
-g S wait S seconds for graphical.target in queue (default: 60; 0 or less disables  -g S wait S seconds for graphical.target in queue (default: 60; 0 or less disables
check).  check).
-i do not check for login shell  -i do not check for login shell
-r do not check for local session (allow remote session)  -r do not check for local session (allow remote session)
-v show all failed tests  -v show all failed tests
-q be quiet  -q be quiet
Checks whether it is OK to launch a wayland session via the following conditions:  Checks whether it is OK to launch a wayland session via the following conditions:
• DBUS_SESSION_BUS_ADDRESS is set  • DBUS_SESSION_BUS_ADDRESS is set
• Running from login shell  • Running from login shell
• System is at graphical.target  • System is at graphical.target
• User graphical-session*.target units are not yet active  • User graphical-session*.target units are not yet active
• Foreground VT is among allowed (default: 1)  • Foreground VT is among allowed (default: 1)
• Login session's VT is matching  • Login session's VT is matching
start  start
Generates units for given compositor command line or Desktop Entry and starts them.  Generates units for given compositor command line or Desktop Entry and starts them.
uwsm start [-h] [-D name[:name...]] [-a|-e] [-N Name] [-C Comment] [-U {run|home}] [-t]  uwsm start [-h] [-D name[:name...]] [-a|-e] [-N Name] [-C Comment] [-U {run|home}] [-t]
[-o] [-n] -- compositor [args ...]  [-o] [-n] -- compositor [args ...]
-F Hardcode mode, always write command line to unit drop-ins and use full  -F Hardcode mode, always write command line to unit drop-ins and use full
paths.  paths.
-D name[:name...] Names to fill XDG_CURRENT_DESKTOP with (:-separated). Existing var con‐  -D name[:name...] Names to fill XDG_CURRENT_DESKTOP with (:-separated). Existing var con‐
tent is a starting point if no active session is running.  tent is a starting point if no active session is running.
-a Append desktop names set by -D to other sources (default).  -a Append desktop names set by -D to other sources (default).
-e Use desktop names set by -D exclusively, discard other sources.  -e Use desktop names set by -D exclusively, discard other sources.
-N Name Fancy name for compositor (filled from Desktop Entry by default).  -N Name Fancy name for compositor (filled from Desktop Entry by default).
-C Comment Fancy description for compositor (filled from Desktop Entry by de‐  -C Comment Fancy description for compositor (filled from Desktop Entry by de‐
fault).  fault).
-U {run|home} Select rung for generated unit files: run: $XDG_RUNTIME_DIR/sys‐  -U {run|home} Select rung for generated unit files: run: $XDG_RUNTIME_DIR/sys‐
temd/user (default), or home: $XDG_CONFIG_HOME/systemd/user. Permanent  temd/user (default), or home: $XDG_CONFIG_HOME/systemd/user. Permanent
destination will save some time by removing need for reloading systemd.  destination will save some time by removing need for reloading systemd.
Managed files from other rung will be removed. Can be preset with  Managed files from other rung will be removed. Can be preset with
UWSM_UNIT_RUNG environment var.  UWSM_UNIT_RUNG environment var.
-t Do not generate (and remove) tweak unit files. Can be preset with  -t Do not generate (and remove) tweak unit files. Can be preset with
UWSM_TWEAKS=false environment var.  UWSM_TWEAKS=false environment var.
-T Generate tweak unit files for other software. This is default behavior.  -T Generate tweak unit files for other software. This is default behavior.
-g S Wait for S seconds for system graphical.target in queue and warn if  -g S Wait for S seconds for system graphical.target in queue and warn if
timed out or not in queue (default: 60, negative to disable).  timed out or not in queue (default: 60, negative to disable).
-G S Wait for S seconds for system graphical.target in queue and abort if  -G S Wait for S seconds for system graphical.target in queue and abort if
timed out or not in queue (overrides -g, default: -1, (disabled)).  timed out or not in queue (overrides -g, default: -1, (disabled)).
-o Only generate units, but do not start.  -o Only generate units, but do not start.
-n Dry run, do not write or start anything.  -n Dry run, do not write or start anything.
The first argument of the compositor command line acts as an ID and should be either one of:  The first argument of the compositor command line acts as an ID and should be either one of:
• Executable name  • Executable name
• Desktop Entry ID (optionally with ":"-delimited action ID)  • Desktop Entry ID (optionally with ":"-delimited action ID)
• Special value:  • Special value:
• select - invoke menu to select compositor.  • select - invoke menu to select compositor.
• default - run previously selected compositor (or select if no selection was saved).  • default - run previously selected compositor (or select if no selection was saved).
If given as path, hardcode mode will be used implicitly.  If given as path, hardcode mode will be used implicitly.
Always use "--" to disambiguate dashed arguments intended for compositor itself.  Always use "--" to disambiguate dashed arguments intended for compositor itself.
After units are (re)generated, wayland-session-bindpid@${PID}.service is started, to track the  After units are (re)generated, wayland-session-bindpid@${PID}.service is started, to track the
PID of invoking uwsm, then uwsm process replaces itself with systemctl execution that starts  PID of invoking uwsm, then uwsm process replaces itself with systemctl execution that starts
wayland-wm@${ID}.service and waits for it to finish.  wayland-wm@${ID}.service and waits for it to finish.
In order to complete the startup sequence, the compositor has to put WAYLAND_DISPLAY into the  In order to complete the startup sequence, the compositor has to put WAYLAND_DISPLAY into the
systemd activation environment. This can be done explicitly by making compositor run "uwsm fi‐  systemd activation environment. This can be done explicitly by making compositor run "uwsm fi‐
nalize" command (see the next subsection).  nalize" command (see the next subsection).
finalize  finalize
For running by a compositor on startup.  For running by a compositor on startup.
uwsm finalize [-h] [VAR_NAME ...]  uwsm finalize [-h] [VAR_NAME ...]
Exports WAYLAND_DISPLAY, DISPLAY and any defined vars mentioned by names in arguments or in  Exports WAYLAND_DISPLAY, DISPLAY and any defined vars mentioned by names in arguments or in
UWSM_FINALIZE_VARNAMES variable (whitespace-separated). Then sends startup notification for the  UWSM_FINALIZE_VARNAMES variable (whitespace-separated). Then sends startup notification for the
unit to systemd user manager.  unit to systemd user manager.
This is required if compositor itself does not put WAYLAND_DISPLAY to systemd activation envi‐  This is required if compositor itself does not put WAYLAND_DISPLAY to systemd activation envi‐
ronment, otherwise wayland-session@.service unit or a dedicated wayland-session-waitenv.service  ronment, otherwise wayland-session@.service unit or a dedicated wayland-session-waitenv.service
unit will terminate due to startup timeout.  unit will terminate due to startup timeout.
UWSM_FINALIZE_VARNAMES variable can be prefilled by plugins.  UWSM_FINALIZE_VARNAMES variable can be prefilled by plugins.
Direct assignment as VAR_NAME=value is also possible, but recommended only for creating flags  Direct assignment as VAR_NAME=value is also possible, but recommended only for creating flags
for UWSM_WAIT_VARNAMES mechanism.  for UWSM_WAIT_VARNAMES mechanism.
stop  stop
Stops compositor and optionally removes generated units.  Stops compositor and optionally removes generated units.
uwsm stop [-h] [-r [compositor] [-U {run|home}] [-n]  uwsm stop [-h] [-r [compositor] [-U {run|home}] [-n]
-r [compositor] Also remove units (all or only compositor-specific).  -r [compositor] Also remove units (all or only compositor-specific).
-U {run|home} Select rung for generated unit files: run: $XDG_RUNTIME_DIR/systemd/user  -U {run|home} Select rung for generated unit files: run: $XDG_RUNTIME_DIR/systemd/user
(default), or home: $XDG_CONFIG_HOME/systemd/user. Permanent destination  (default), or home: $XDG_CONFIG_HOME/systemd/user. Permanent destination
will save some time by removing need for reloading systemd. Managed files  will save some time by removing need for reloading systemd. Managed files
from other rung will be removed. Can be preset with UWSM_UNIT_RUNG envi‐  from other rung will be removed. Can be preset with UWSM_UNIT_RUNG envi‐
ronment var.  ronment var.
-n Dry run, do not stop or remove anything.  -n Dry run, do not stop or remove anything.
app  app
Application-to-unit launcher with Desktop Entry support.  Application-to-unit launcher with Desktop Entry support.
uwsm app [-h] [-s {a,b,s,custom.slice}] [-t {scope,service}] [-a app_name] [-u unit_name]  uwsm app [-h] [-s {a,b,s,custom.slice}] [-t {scope,service}] [-a app_name] [-u unit_name]
[-d unit_description] [-S ] [-T] -- application [args ...]  [-d unit_description] [-S ] [-T] -- application [args ...]
-s {a,b,s,custom.slice} Slice selector (default: a):  -s {a,b,s,custom.slice} Slice selector (default: a):
a - app-graphical.slice  a - app-graphical.slice
b - background-graphical.slice  b - background-graphical.slice
s - session-graphical.slice  s - session-graphical.slice
any slice by full name  any slice by full name
-t {scope,service} Type of unit to launch (default: scope, can be preset by  -t {scope,service} Type of unit to launch (default: scope, can be preset by
UWSM_APP_UNIT_TYPE env var).  UWSM_APP_UNIT_TYPE env var).
-a app_name Override app name (a substring in unit name).  -a app_name Override app name (a substring in unit name).
-u unit_name Override the whole autogenerated unit name.  -u unit_name Override the whole autogenerated unit name.
-d unit_description Unit Description.  -d unit_description Unit Description.
-p Property=value Set additional unit property (option is repeatable).  -p Property=value Set additional unit property (option is repeatable).
-S {out,err,both} Silence stdout, stderr, or both.  -S {out,err,both} Silence stdout, stderr, or both.
-T Launch app in a terminal. Allows command to be empty to just  -T Launch app in a terminal. Allows command to be empty to just
launch a terminal.  launch a terminal.
Application can be provided as a command with optional arguments, or a Desktop Entry ID, op‐  Application can be provided as a command with optional arguments, or a Desktop Entry ID, op‐
tionally suffixed with ":"-delimited Action ID. If Desktop Entry is being launched, arguments  tionally suffixed with ":"-delimited Action ID. If Desktop Entry is being launched, arguments
should be compatible with it.  should be compatible with it.
Always use "--" to disambiguate dashed arguments intended for application itself.  Always use "--" to disambiguate dashed arguments intended for application itself.
aux  aux
For use in systemd user services. Can only be called by systemd user manager.  For use in systemd user services. Can only be called by systemd user manager.
prepare-env Prepares environment (for use in ExecStart in wayland-wm-env@.service bound to  prepare-env Prepares environment (for use in ExecStart in wayland-wm-env@.service bound to
wayland-session-pre@.target).  wayland-session-pre@.target).
cleanup-env Cleans up environment (for use ExecStop in in wayland-wm-env@.service bound to  cleanup-env Cleans up environment (for use ExecStop in in wayland-wm-env@.service bound to
wayland-session-pre@.target).  wayland-session-pre@.target).
exec Executes a command with arguments or a desktop entry (for use in Exec in wayland-  exec Executes a command with arguments or a desktop entry (for use in Exec in wayland-
wm@.service bound to wayland-session@.target).  wm@.service bound to wayland-session@.target).
app-daemon Daemon for faster app argument generation, used by uwsm-app client.  app-daemon Daemon for faster app argument generation, used by uwsm-app client.
APP DAEMON APP DAEMON
Provided as wayland-wm-app-daemon.service to be started on-demand.  Provided as wayland-wm-app-daemon.service to be started on-demand.
Daemon receives app arguments from ${XDG_RUNTIME_DIR}/uwsm-app-daemon-in pipe. Resulting argu‐  Daemon receives app arguments from ${XDG_RUNTIME_DIR}/uwsm-app-daemon-in pipe. Resulting argu‐
ments are formatted as shell code and written to ${XDG_RUNTIME_DIR}/uwsm-app-daemon-out pipe.  ments are formatted as shell code and written to ${XDG_RUNTIME_DIR}/uwsm-app-daemon-out pipe.
Arguments are expected to be \0-delimited, leading \0 are stripped. One command is received per  Arguments are expected to be \0-delimited, leading \0 are stripped. One command is received per
write+close.  write+close.
The first argument determines the behavior:  The first argument determines the behavior:
• app the rest is processed the same as in "uwsm app"  • app the rest is processed the same as in "uwsm app"
• ping just "pong" is returnedn  • ping just "pong" is returnedn
• stop daemon is stoppedn  • stop daemon is stoppedn
Single commands are prepended with exec, iterated commands are assembled with trailing & each,  Single commands are prepended with exec, iterated commands are assembled with trailing & each,
followed by wait.  followed by wait.
The purpose of all this is to skip all the expensive Python startup and import routines that  The purpose of all this is to skip all the expensive Python startup and import routines that
slow things down every time "uwsm app" is called. Instead the daemon does it once and then lis‐  slow things down every time "uwsm app" is called. Instead the daemon does it once and then lis‐
tens for requests, while a simple shell script may dump arguments to one pipe and run the code  tens 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.  received from another via eval, which is much faster.
The simplest script is:  The simplest script is:
#!/bin/sh  #!/bin/sh
printf '0%s' app "$@" > "${XDG_RUNTIME_DIR}/uwsm-app-daemon-in"  printf '0%s' app "$@" > "${XDG_RUNTIME_DIR}/uwsm-app-daemon-in"
IFS='' read -r cmd < "${XDG_RUNTIME_DIR}/uwsm-app-daemon-out"  IFS='' read -r cmd < "${XDG_RUNTIME_DIR}/uwsm-app-daemon-out"
eval "$cmd"  eval "$cmd"
Provided uwsm-app client script is a bit smarter: it can start the daemon, applies timeouts,  Provided uwsm-app client script is a bit smarter: it can start the daemon, applies timeouts,
and supports newlines in returned args.  and supports newlines in returned args.
SHELL PROFILE INTEGRATION SHELL PROFILE INTEGRATION
To launch uwsm automatically on login, add one of constructs below (or similar) to shell pro‐  To launch uwsm automatically on login, add one of constructs below (or similar) to shell pro‐
file.  file.
This asks to select a compositor (or refuse and continue with login shell) when logged in on VT  This asks to select a compositor (or refuse and continue with login shell) when logged in on VT
1:  1:
if uwsm check may-start && uwsm select; then  if uwsm check may-start && uwsm select; then
exec systemd-cat -t uwsm_start uwsm start default  exec systemd-cat -t uwsm_start uwsm start default
fi  fi
This just starts a specific compositor depending on foreground VT:  This just starts a specific compositor depending on foreground VT:
if uwsm check may-start 1; then  if uwsm check may-start 1; then
exec systemd-cat -t uwsm_start uwsm start sway.desktop  exec systemd-cat -t uwsm_start uwsm start sway.desktop
elif uwsm check may-start 2; then  elif uwsm check may-start 2; then
exec systemd-cat -t uwsm_start uwsm start labwc.desktop  exec systemd-cat -t uwsm_start uwsm start labwc.desktop
fi  fi
Using "uwsm check may-start" as a condition is essential, not only to prevent accidental  Using "uwsm check may-start" as a condition is essential, not only to prevent accidental
startup attempts where they are not expected, but also since startup may involve sourcing shell  startup attempts where they are not expected, but also since startup may involve sourcing shell
profile, which might lead to nasty loops.  profile, which might lead to nasty loops.
See check subcommand section for info on may-start checker.  See check subcommand section for info on may-start checker.
exec allows uwsm to replace login shell in order to properly bind to user session and handle  exec allows uwsm to replace login shell in order to properly bind to user session and handle
session termination.  session termination.
"systemd-cat -t uwsm_start" (optional) executes the command given to it (uwsm) with its stdout  "systemd-cat -t uwsm_start" (optional) executes the command given to it (uwsm) with its stdout
and stderr connected to the systemd journal, tagged with identifier "uwsm_start". See systemd-  and stderr connected to the systemd journal, tagged with identifier "uwsm_start". See systemd-
cat(1) for more options.  cat(1) for more options.
USE INSIDE DESKTOP ENTRY USE INSIDE DESKTOP ENTRY
To launch uwsm from a display/login manager, "uwsm start" can be used inside Desktop Entries.  To launch uwsm from a display/login manager, "uwsm start" can be used inside Desktop Entries.
Example /usr/local/share/wayland-sessions/my-compositor.desktop:  Example /usr/local/share/wayland-sessions/my-compositor.desktop:
[Desktop Entry]  [Desktop Entry]
Name=My compositor (with UWSM)  Name=My compositor (with UWSM)
Comment=My cool compositor  Comment=My cool compositor
Exec=uwsm start -N "My compositor" -D mycompositor -C "My cool compositor" mywm  Exec=uwsm start -N "My compositor" -D mycompositor -C "My cool compositor" mywm
DesktopNames=mycompositor  DesktopNames=mycompositor
Type=Application  Type=Application
Things to keep in mind:  Things to keep in mind:
• For consistency, command line arguments should mirror the keys of the entry  • For consistency, command line arguments should mirror the keys of the entry
• Command in Exec= should start with "uwsm start"  • Command in Exec= should start with "uwsm start"
• It should not point to itself (as a combination of Desktop Entry ID and Action ID)  • It should not point to itself (as a combination of Desktop Entry ID and Action ID)
• It should not point to a Desktop Entry ID and Action ID that also uses ‘uwsm‘  • It should not point to a Desktop Entry ID and Action ID that also uses ‘uwsm‘
Potentially such entries may be found and used by uwsm itself, i.e. in shell profile integra‐  Potentially such entries may be found and used by uwsm itself, i.e. in shell profile integra‐
tion situation, or when launched manually. Following the principles above ensures uwsm will  tion 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 ef‐  properly recognize itself and parse requested arguments inside the entry without any side ef‐
fects.  fects.
SEE ALSO SEE ALSO
uwsm-plugins(3), systemd-run(1), systemd-cat(1), systemd.special(7)  uwsm-plugins(3), systemd-run(1), systemd-cat(1), systemd.special(7)
2026-02-14 UWSM(1)  2026-02-14 UWSM(1)