diff --git a/assets/syntaxes/02_Extra/Manpage.sublime-syntax b/assets/syntaxes/02_Extra/Manpage.sublime-syntax index 80d1ff98..cebc28ac 100644 --- a/assets/syntaxes/02_Extra/Manpage.sublime-syntax +++ b/assets/syntaxes/02_Extra/Manpage.sublime-syntax @@ -9,6 +9,7 @@ scope: source.man variables: section_heading: '^(?!#)\S.*$' command_line_option: '(--?[A-Za-z0-9][_A-Za-z0-9-]*)' + ansi_escape_sequence: '\e\[[\?=]?(?:\d+;?)*[A-Za-z]' contexts: prototype: @@ -69,7 +70,7 @@ contexts: escape: '(?={{section_heading}})' function-call: - - match: '(?:\s+)(?:\e\[[\?=]?(?:\d+;?)+[A-Za-z])?([A-Za-z0-9_\-^\e]+\.)?([A-Za-z0-9_\-]+)(?:\e\[[\?=]?(?:\d+;?)+[A-Za-z])?(\()([^)]*)(\))' + - match: '(? "${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. + +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: + + 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: + + 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. + + 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. + +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: + + • 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. + +SEE ALSO + uwsm-plugins(3), systemd-run(1), systemd-cat(1), systemd.special(7) + + 2026-02-14 UWSM(1) diff --git a/tests/syntax-tests/source/Manpage/uwsm-0.26.3.man b/tests/syntax-tests/source/Manpage/uwsm-0.26.3.man new file mode 100644 index 00000000..9e63ec42 --- /dev/null +++ b/tests/syntax-tests/source/Manpage/uwsm-0.26.3.man @@ -0,0 +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. + + 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. + + 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 + + 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 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" + + 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. + + 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 + + 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 + + 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. + + "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 + + 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‘ + + 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) + + 2026-02-14 UWSM(1)