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

NAME
       UWSM-plugins - Plugins for Universal Wayland Session Manager.

DESCRIPTION
       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.

   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-${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.

   Functions that can be added by plugins
       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                   UWSM-PLUGINS(3)