UWSM-PLUGINS(3) Library Functions Manual UWSM-PLUGINS(3)

UWSM-plugins - Plugins for Universal Wayland Session Manager.

Shell plugins provide compositor-specific functions during environment preparation.

Located in ${PREFIX}/share/uwsm/plugins/ and named ${__WM_BIN_ID__}.sh, they should only contain specifically named functions.

${__WM_BIN_ID__} is derived from the item 0 of compositor command line by applying s/(^[^a-zA-Z]|[^a-zA-Z0-9_])+/_/ and converting to lower case.

It is used as plugin id and suffix in function names.

__WM_ID__

compositor ID, effective first argument of start.
__WM_ID_UNIT_STRING__
compositor ID escaped for systemd unit name.
__WM_BIN_ID__
processed first item of compositor argv.
__WM_DESKTOP_NAMES__
:-separated desktop names from DesktopNames= of entry and -D CLI argument.
__WM_FIRST_DESKTOP_NAME__
first of the above.
__WM_DESKTOP_NAMES_LOWERCASE__
same as __WM_DESKTOP_NAMES__, but in lower case.
__WM_FIRST_DESKTOP_NAME_LOWERCASE__
first of the above.
__WM_DESKTOP_NAMES_EXCLUSIVE__
(true|false) indicates that __WM_DESKTOP_NAMES__ came from CLI argument and are marked as exclusive.
__OIFS__
contains shell default field separator (space, tab, newline) for convenient restoring.

load_wm_env

standard function for loading env files
process_config_dirs
iterates over XDG Config hierarchy and system part of XDG Data hierarchy (decreasing priority)
process_config_dirs_reversed
(called by load_wm_env), same as process_config_dirs but in reverse (increasing priority)
in_each_config_dir_reversed
called by process_config_dirs_reversed for each config dir as $1, loads uwsm/env, uwsm/env-${desktop} files
in_each_config_dir
called by process_config_dirs for each config dir as $1, does nothing ATM
source_file
sources $1 file if exists, providing messages for log.

See code inside uwsm/main.py for more auxillary funcions.

quirks__${__WM_BIN_ID__}
called before env loading.

These functions will be called instead of standard funcions if defined:

load_wm_env__${__WM_BIN_ID__}
process_config_dirs_reversed__${__WM_BIN_ID__}
in_each_config_dir_reversed__${__WM_BIN_ID__}
process_config_dirs__${__WM_BIN_ID__}
in_each_config_dir__${__WM_BIN_ID__}

Original functions are still available for calling explicitly if combined effect is needed.

Example:

#!/bin/false
# function to make arbitrary actions before loading environment
quirks__my_cool_wm() {
  # here additional vars can be set or unset
  export I_WANT_THIS_IN_SESSION=yes
  unset I_DO_NOT_WANT_THAT
  # or prepare a config for compositor
  # or set a var to modify what sourcing uwsm/env, uwsm/env-${__WM_ID__}
  # in the next stage will do
  ...
}
in_each_config_dir_reversed__my_cool_wm() {
  # custom mechanism for loading of env files (or a stub)
  # replaces standard function, but we want it also
  # so call it explicitly
  in_each_config_dir_reversed "$1"
  # and additionally source our file
  source_file "${1}/${__WM_ID__}/env"
}
2025-01-30