UWSM-PLUGINS(3)

💖 NAME 💖

UWSM-plugins — Plugins for Universal Wayland Session Manager. This is the UWSM-PLUGINS(3) page from the Library Functions Manual, and bestie, we’re about to make plugins make sense. 🦋

✨ DESCRIPTION ✨

Okay so shell plugins are the little helpers that provide compositor-specific functions during environment preparation. They’re located in ${PREFIX}/share/uwsm/plugins/ and named ${__WM_BIN_ID__}.sh, and they should only contain specifically named functions — like, the guest list is strict, no random functions crashing the party. 😭

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

It’s used as plugin id and suffix in function names. Periodt. 💅

👑 Variables available to plugins 👑

• __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.

🌸 Standard functions 🌸

• 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.d/*, uwsm/env-${desktop}, uwsm/env-${desktop}.d/* 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 auxiliary functions.

🧚 Functions that can be added by plugins 🧚

• quirks__${__WM_BIN_ID__} — called before env loading.

These functions will be called instead of standard functions 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"
}

---

Okay that’s the whole page, bestie — footer energy is 2026-10-15 and UWSM-PLUGINS(3) from the Library Functions Manual. Now go make a plugin and slay 💅✨🫶