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"
    }