diff --git a/tests/syntax-tests/highlighted/Manpage/uwsm-0.26.3.man b/tests/syntax-tests/highlighted/Manpage/uwsm-0.26.3.man index 8395d816..319020e8 100644 --- a/tests/syntax-tests/highlighted/Manpage/uwsm-0.26.3.man +++ b/tests/syntax-tests/highlighted/Manpage/uwsm-0.26.3.man @@ -1,399 +1,399 @@ -UWSM(1) General Commands Manual UWSM(1) - -NAME - UWSM - Universal Wayland Session Manager. - -SYNOPSIS - uwsm [-h|-v] {subcommand} [options ...] - -DESCRIPTION - 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. - -SUBCOMMANDS - select Select default compositor Entry. - start Start compositor and graphical session. - finalize Send compositor-set variables and unit startup notification to systemd user manager. - stop Stop graphical session and compositor. - app Application unit launcher (with Desktop Entry support). - check Perform state checks (for scripting and info). - aux Technical functions for use inside units. - - See corresponding SUBCOMMANDS subsections below for further info. - - Help for each subcommand is accessible by running "uwsm {subcommand} -h". - -CONFIGURATION - Files - In XDG config hierarchy: - uwsm/env - uwsm/env.d/* - uwsm/env-${compositor} - uwsm/env-${compositor}.d/* 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 XDG_CURRENT_SESSION var (lowercased). - 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‐ - tro level defaults. - - Environment vars - UWSM_UNIT_RUNG (run|home) - Which rung of systemd/user/ hierarchy to manage generated unit - and drop-in files in: $XDG_RUNTIME_DIR or $XDG_CONFIG_HOME. - UWSM_TWEAKS (boolean value) - Set to False to remove and not generate tweak drop-ins for - other software. - UWSM_FINALIZE_VARNAMES (whitespace-separated names of env vars) - Additional variables for "uwsm finalize". - UWSM_WAIT_VARNAMES (whitespace-separated names of env vars) - Variables to wait for in activation environment before proceed‐ - ing to graphical session (in addition to WAYLAND_DISPLAY). - UWSM_WAIT_VARNAMES_TIMEOUT (int value) - Seconds to wait for variables to appear in activation environ‐ - ment. Essentially, startup timeout (default: 10). - UWSM_WAIT_VARNAMES_SETTLETIME (float value) - Seconds to pause after all expected vars found in activation - environment (default: 0.2). - UWSM_APP_UNIT_TYPE (scope|service) - Default unit type for launching apps (default: scope). - UWSM_SILENT_START (int or boolean value) - True or 1 to inhibit stdout messages from "uwsm start". 2 to - also inhibit warnings. - DEBUG (int or boolean value) - True or positive number to dump debug info to stderr. - -OPERATION OVERVIEW - Login Sequence Integration - uwsm can be launched by using conditional exec in shell profile to replace login shell (see - Shell Profile Integration section). - - 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). - - Compositor Selection - uwsm can run arbitrary compositor command line or a Desktop Entry by ID (specifying Action ID - is also supported). - - Desktop Entry can also be selected via a whiptail menu (see select subcommand section). - - Startup - See start subcommand section for command syntax. - - UWSM uses a set of units bound to standard user session targets: - - • wayland-session-pre@.target (bound to graphical-session-pre.target) - • wayland-wm-env@.service (environment preloader service) - • wayland-session@.target (bound to graphical-session.target) - • wayland-wm@.service (service for the selected compositor) - • wayland-session-xdg-autostart@.target (bound to xdg-desktop-autostart.target) - • wayland-session-envelope@.target (lives through entire lifecycle) - • wayland-session-shutdown.target (conflicts with targets above for shutdown) - • wayland-session-bindpid@.service (PID-tracking session killswitch) - • wayland-session-waitenv.service (delays graphical session until vars appear) - - Compositor ID (Desktop Entry ID or executable name) becomes the specifier for all templated - units. - - 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 - 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 - IN_UWSM_ENV_PRELOADER var set to true. - - At the stage of graphical-session.target (before it) the main compositor unit wayland- - wm@${ID}.service and wayland-session-waitenv.service are started. - - 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‐ - ronment startup will timeout in 10 seconds. - - 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 - (see Environment vars section). - - Successful activation of compositor unit and existence of WAYLAND_DISPLAY in activation envi‐ - ronment will allow graphical-session.target to be declared reached. - - Finally, xdg-desktop-autostart.target is activated. - - Inside session - 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 - provides custom nested slices for apps to live in and be terminated on session end: - • app-graphical.slice - • background-graphical.slice - • session-graphical.slice - - A helper app subcommand is provided to handle all the systemd-run invocations for you (see app - subcommand section). - - The compositor is launched in session.slice by default (as recommended by systemd.special(7)). - - Shutdown - Can be initiated by either: - • running uwsm stop - • stopping wayland-wm@*.service or wayland-session-envelope@*.target - • starting wayland-session-shutdown.target - - 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‐ - 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. - -SUBCOMMANDS - select - Selects default wayland session compositor Desktop Entry. - - uwsm select - - 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 - if selection is cancelled. Can be used for scripting launch condition in shell profile. - - check - Performs tests, returns 0 on success, 1 on failure. - - is-active: - - uwsm check is-active [-h] [-v] [compositor] - - -v show additional info - compositor check for specific compositor - - Checks if unit of specific compositor or graphical-session*.target in general is in active or - activating state. - - may-start: - - uwsm check may-start [-h] [-g [S]] [-v|-q] [N ...] - - N ... allowed VT numbers (default: 1) - -g S wait S seconds for graphical.target in queue (default: 60; 0 or less disables - check). - -i do not check for login shell - -r do not check for local session (allow remote session) - -v show all failed tests - -q be quiet - - Checks whether it is OK to launch a wayland session via the following conditions: - • DBUS_SESSION_BUS_ADDRESS is set - • Running from login shell - • System is at graphical.target - • User graphical-session*.target units are not yet active - • Foreground VT is among allowed (default: 1) - • Login session's VT is matching - - start - 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] - [-o] [-n] -- compositor [args ...] - - -F Hardcode mode, always write command line to unit drop-ins and use full - paths. - -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. - -a Append desktop names set by -D to other sources (default). - -e Use desktop names set by -D exclusively, discard other sources. - -N Name Fancy name for compositor (filled from Desktop Entry by default). - -C Comment Fancy description for compositor (filled from Desktop Entry by de‐ - fault). - -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 - destination 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 environment var. - -t Do not generate (and remove) tweak unit files. Can be preset with - UWSM_TWEAKS=false environment var. - -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 - 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 - timed out or not in queue (overrides -g, default: -1, (disabled)). - -o Only generate units, but do not start. - -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: - • Executable name - • Desktop Entry ID (optionally with ":"-delimited action ID) - • Special value: - • select - invoke menu to select compositor. - • default - run previously selected compositor (or select if no selection was saved). - - If given as path, hardcode mode will be used implicitly. - - 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 - PID of invoking uwsm, then uwsm process replaces itself with systemctl execution that starts - 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 - systemd activation environment. This can be done explicitly by making compositor run "uwsm fi‐ - nalize" command (see the next subsection). - - finalize - For running by a compositor on startup. - - uwsm finalize [-h] [VAR_NAME ...] - - 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 - unit to systemd user manager. - - 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 - unit will terminate due to startup timeout. - - UWSM_FINALIZE_VARNAMES variable can be prefilled by plugins. - - Direct assignment as VAR_NAME=value is also possible, but recommended only for creating flags - for UWSM_WAIT_VARNAMES mechanism. - - stop - Stops compositor and optionally removes generated units. - - uwsm stop [-h] [-r [compositor] [-U {run|home}] [-n] - - -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 - (default), or home: $XDG_CONFIG_HOME/systemd/user. Permanent destination - 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‐ - ronment var. - -n Dry run, do not stop or remove anything. - - app - 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] - [-d unit_description] [-S ] [-T] -- application [args ...] - - -s {a,b,s,custom.slice} Slice selector (default: a): - a - app-graphical.slice - b - background-graphical.slice - s - session-graphical.slice - any slice by full name - -t {scope,service} Type of unit to launch (default: scope, can be preset by - UWSM_APP_UNIT_TYPE env var). - -a app_name Override app name (a substring in unit name). - -u unit_name Override the whole autogenerated unit name. - -d unit_description Unit Description. - -p Property=value Set additional unit property (option is repeatable). - -S {out,err,both} Silence stdout, stderr, or both. - -T Launch app in a terminal. Allows command to be empty to just - launch a terminal. - - 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 - should be compatible with it. - - Always use "--" to disambiguate dashed arguments intended for application itself. - - aux - 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 - wayland-session-pre@.target). - cleanup-env Cleans up environment (for use ExecStop in in wayland-wm-env@.service bound to - wayland-session-pre@.target). - exec Executes a command with arguments or a desktop entry (for use in Exec in wayland- - wm@.service bound to wayland-session@.target). - app-daemon Daemon for faster app argument generation, used by uwsm-app client. - -APP DAEMON - Provided as wayland-wm-app-daemon.service to be started on-demand. +UWSM(1) General Commands Manual UWSM(1) + +NAME + UWSM - Universal Wayland Session Manager. + +SYNOPSIS + uwsm [-h|-v] {subcommand} [options ...] + +DESCRIPTION + 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. + +SUBCOMMANDS + select Select default compositor Entry. + start Start compositor and graphical session. + finalize Send compositor-set variables and unit startup notification to systemd user manager. + stop Stop graphical session and compositor. + app Application unit launcher (with Desktop Entry support). + check Perform state checks (for scripting and info). + aux Technical functions for use inside units. + + See corresponding SUBCOMMANDS subsections below for further info. + + Help for each subcommand is accessible by running "uwsm {subcommand} -h". + +CONFIGURATION + Files + In XDG config hierarchy: + uwsm/env + uwsm/env.d/* + uwsm/env-${compositor} + uwsm/env-${compositor}.d/* 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 XDG_CURRENT_SESSION var (lowercased). + 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‐ + tro level defaults. + + Environment vars + UWSM_UNIT_RUNG (run|home) + Which rung of systemd/user/ hierarchy to manage generated unit + and drop-in files in: $XDG_RUNTIME_DIR or $XDG_CONFIG_HOME. + UWSM_TWEAKS (boolean value) + Set to False to remove and not generate tweak drop-ins for + other software. + UWSM_FINALIZE_VARNAMES (whitespace-separated names of env vars) + Additional variables for "uwsm finalize". + UWSM_WAIT_VARNAMES (whitespace-separated names of env vars) + Variables to wait for in activation environment before proceed‐ + ing to graphical session (in addition to WAYLAND_DISPLAY). + UWSM_WAIT_VARNAMES_TIMEOUT (int value) + Seconds to wait for variables to appear in activation environ‐ + ment. Essentially, startup timeout (default: 10). + UWSM_WAIT_VARNAMES_SETTLETIME (float value) + Seconds to pause after all expected vars found in activation + environment (default: 0.2). + UWSM_APP_UNIT_TYPE (scope|service) + Default unit type for launching apps (default: scope). + UWSM_SILENT_START (int or boolean value) + True or 1 to inhibit stdout messages from "uwsm start". 2 to + also inhibit warnings. + DEBUG (int or boolean value) + True or positive number to dump debug info to stderr. + +OPERATION OVERVIEW + Login Sequence Integration + uwsm can be launched by using conditional exec in shell profile to replace login shell (see + Shell Profile Integration section). + + 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). + + Compositor Selection + uwsm can run arbitrary compositor command line or a Desktop Entry by ID (specifying Action ID + is also supported). + + Desktop Entry can also be selected via a whiptail menu (see select subcommand section). + + Startup + See start subcommand section for command syntax. + + UWSM uses a set of units bound to standard user session targets: + + • wayland-session-pre@.target (bound to graphical-session-pre.target) + • wayland-wm-env@.service (environment preloader service) + • wayland-session@.target (bound to graphical-session.target) + • wayland-wm@.service (service for the selected compositor) + • wayland-session-xdg-autostart@.target (bound to xdg-desktop-autostart.target) + • wayland-session-envelope@.target (lives through entire lifecycle) + • wayland-session-shutdown.target (conflicts with targets above for shutdown) + • wayland-session-bindpid@.service (PID-tracking session killswitch) + • wayland-session-waitenv.service (delays graphical session until vars appear) + + Compositor ID (Desktop Entry ID or executable name) becomes the specifier for all templated + units. + + 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 + 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 + IN_UWSM_ENV_PRELOADER var set to true. + + At the stage of graphical-session.target (before it) the main compositor unit wayland- + wm@${ID}.service and wayland-session-waitenv.service are started. + + 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‐ + ronment startup will timeout in 10 seconds. + + 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 + (see Environment vars section). + + Successful activation of compositor unit and existence of WAYLAND_DISPLAY in activation envi‐ + ronment will allow graphical-session.target to be declared reached. + + Finally, xdg-desktop-autostart.target is activated. + + Inside session + 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 + provides custom nested slices for apps to live in and be terminated on session end: + • app-graphical.slice + • background-graphical.slice + • session-graphical.slice + + A helper app subcommand is provided to handle all the systemd-run invocations for you (see app + subcommand section). + + The compositor is launched in session.slice by default (as recommended by systemd.special(7)). + + Shutdown + Can be initiated by either: + • running uwsm stop + • stopping wayland-wm@*.service or wayland-session-envelope@*.target + • starting wayland-session-shutdown.target + + 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‐ + 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. + +SUBCOMMANDS + select + Selects default wayland session compositor Desktop Entry. + + uwsm select + + 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 + if selection is cancelled. Can be used for scripting launch condition in shell profile. + + check + Performs tests, returns 0 on success, 1 on failure. + + is-active: + + uwsm check is-active [-h] [-v] [compositor] + + -v show additional info + compositor check for specific compositor + + Checks if unit of specific compositor or graphical-session*.target in general is in active or + activating state. + + may-start: + + uwsm check may-start [-h] [-g [S]] [-v|-q] [N ...] + + N ... allowed VT numbers (default: 1) + -g S wait S seconds for graphical.target in queue (default: 60; 0 or less disables + check). + -i do not check for login shell + -r do not check for local session (allow remote session) + -v show all failed tests + -q be quiet + + Checks whether it is OK to launch a wayland session via the following conditions: + • DBUS_SESSION_BUS_ADDRESS is set + • Running from login shell + • System is at graphical.target + • User graphical-session*.target units are not yet active + • Foreground VT is among allowed (default: 1) + • Login session's VT is matching + + start + 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] + [-o] [-n] -- compositor [args ...] + + -F Hardcode mode, always write command line to unit drop-ins and use full + paths. + -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. + -a Append desktop names set by -D to other sources (default). + -e Use desktop names set by -D exclusively, discard other sources. + -N Name Fancy name for compositor (filled from Desktop Entry by default). + -C Comment Fancy description for compositor (filled from Desktop Entry by de‐ + fault). + -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 + destination 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 environment var. + -t Do not generate (and remove) tweak unit files. Can be preset with + UWSM_TWEAKS=false environment var. + -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 + 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 + timed out or not in queue (overrides -g, default: -1, (disabled)). + -o Only generate units, but do not start. + -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: + • Executable name + • Desktop Entry ID (optionally with ":"-delimited action ID) + • Special value: + • select - invoke menu to select compositor. + • default - run previously selected compositor (or select if no selection was saved). + + If given as path, hardcode mode will be used implicitly. + + 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 + PID of invoking uwsm, then uwsm process replaces itself with systemctl execution that starts + 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 + systemd activation environment. This can be done explicitly by making compositor run "uwsm fi‐ + nalize" command (see the next subsection). + + finalize + For running by a compositor on startup. + + uwsm finalize [-h] [VAR_NAME ...] + + 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 + unit to systemd user manager. + + 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 + unit will terminate due to startup timeout. + + UWSM_FINALIZE_VARNAMES variable can be prefilled by plugins. + + Direct assignment as VAR_NAME=value is also possible, but recommended only for creating flags + for UWSM_WAIT_VARNAMES mechanism. + + stop + Stops compositor and optionally removes generated units. + + uwsm stop [-h] [-r [compositor] [-U {run|home}] [-n] + + -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 + (default), or home: $XDG_CONFIG_HOME/systemd/user. Permanent destination + 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‐ + ronment var. + -n Dry run, do not stop or remove anything. + + app + 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] + [-d unit_description] [-S ] [-T] -- application [args ...] + + -s {a,b,s,custom.slice} Slice selector (default: a): + a - app-graphical.slice + b - background-graphical.slice + s - session-graphical.slice + any slice by full name + -t {scope,service} Type of unit to launch (default: scope, can be preset by + UWSM_APP_UNIT_TYPE env var). + -a app_name Override app name (a substring in unit name). + -u unit_name Override the whole autogenerated unit name. + -d unit_description Unit Description. + -p Property=value Set additional unit property (option is repeatable). + -S {out,err,both} Silence stdout, stderr, or both. + -T Launch app in a terminal. Allows command to be empty to just + launch a terminal. + + 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 + should be compatible with it. + + Always use "--" to disambiguate dashed arguments intended for application itself. + + aux + 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 + wayland-session-pre@.target). + cleanup-env Cleans up environment (for use ExecStop in in wayland-wm-env@.service bound to + wayland-session-pre@.target). + exec Executes a command with arguments or a desktop entry (for use in Exec in wayland- + wm@.service bound to wayland-session@.target). + app-daemon Daemon for faster app argument generation, used by uwsm-app client. + +APP DAEMON + 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‐ - ments are formatted as shell code and written to ${XDG_RUNTIME_DIR}/uwsm-app-daemon-out pipe. + 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. - Arguments are expected to be \0-delimited, leading \0 are stripped. One command is received per - write+close. + Arguments are expected to be \0-delimited, leading \0 are stripped. One command is received per + 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" - • ping just "pong" is returnedn - • stop daemon is stoppedn + • app the rest is processed the same as in "uwsm app" + • ping just "pong" is returnedn + • stop daemon is stoppedn - Single commands are prepended with exec, iterated commands are assembled with trailing & each, - followed by wait. + Single commands are prepended with exec, iterated commands are assembled with trailing & each, + followed by wait. - 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‐ - 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. + 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‐ + 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. - The simplest script is: + The simplest script is: - #!/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" + #!/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" - Provided uwsm-app client script is a bit smarter: it can start the daemon, applies timeouts, - and supports newlines in returned args. + Provided uwsm-app client script is a bit smarter: it can start the daemon, applies timeouts, + and supports newlines in returned args. -SHELL PROFILE INTEGRATION - To launch uwsm automatically on login, add one of constructs below (or similar) to shell pro‐ - file. +SHELL PROFILE INTEGRATION + To launch uwsm automatically on login, add one of constructs below (or similar) to shell pro‐ + file. - This asks to select a compositor (or refuse and continue with login shell) when logged in on VT - 1: + This asks to select a compositor (or refuse and continue with login shell) when logged in on VT + 1: - if uwsm check may-start && uwsm select; then - exec systemd-cat -t uwsm_start uwsm start default - fi + if uwsm check may-start && uwsm select; then + exec systemd-cat -t uwsm_start uwsm start default + 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 - exec systemd-cat -t uwsm_start uwsm start sway.desktop - elif uwsm check may-start 2; then - exec systemd-cat -t uwsm_start uwsm start labwc.desktop - fi + if uwsm check may-start 1; then + exec systemd-cat -t uwsm_start uwsm start sway.desktop + elif uwsm check may-start 2; then + exec systemd-cat -t uwsm_start uwsm start labwc.desktop + fi - 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 - profile, which might lead to nasty loops. - - See check subcommand section for info on may-start checker. + 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 + profile, which might lead to nasty loops. + + 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 - session termination. + exec allows uwsm to replace login shell in order to properly bind to user session and handle + session termination. - "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- - cat(1) for more options. + "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- + cat(1) for more options. -USE INSIDE DESKTOP ENTRY - 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: - - [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 +USE INSIDE DESKTOP ENTRY + 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: + + [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 - Things to keep in mind: + Things to keep in mind: - • For consistency, command line arguments should mirror the keys of the entry - • 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 a Desktop Entry ID and Action ID that also uses ‘uwsm‘ + • For consistency, command line arguments should mirror the keys of the entry + • 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 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‐ - 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‐ - fects. + 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 + properly recognize itself and parse requested arguments inside the entry without any side ef‐ + fects. -SEE ALSO - uwsm-plugins(3), systemd-run(1), systemd-cat(1), systemd.special(7) +SEE ALSO + uwsm-plugins(3), systemd-run(1), systemd-cat(1), systemd.special(7) - 2026-02-14 UWSM(1) + 2026-02-14 UWSM(1)