Modules

StumpWM Modules

Modules are the canonical way to extend StumpWM using Lisp code.

Being implemented in Lisp, you have all the facilities of a Lisp system in your hands to write your own module.

StumpWM searches for modules in the *data-dir*/modules directory. By default this is ~/.stumpwm.d/modules.

Contrib Repository

Stumpwm Contrib modules are provided in a separated repository.

Get a copy of all modules:

If you have the stumpwm repo, you can get the contrib modules by typing make install-modules in the stumpwm source directory. Or, you can manually get the contrib modules by cloning the stumpwm-contrib repo to ~/.stumpwm.d/modules.

git clone https://github.com/stumpwm/stumpwm-contrib ~/.stumpwm.d/modules

You will only see modules that existed when stumpwm was started, therefore after getting the modules, refresh the list, by either running (with Ctrl-t :) (init-load-path *module-dir*) or (add-to-load-path <path>). Now, you can check if they are available by running list-modules function (with Ctrl-t :) (list-modules).

Once the modules are in the load path, it’s easy to load them, just insert in your StumpWM init file:

(load-module "foo")

A full list of all the modules available are found on StumpWM Contrib README file:

Modules Folder

The default directory is contrib in the stumpwm build directory ${HOME}/.stumpwm.d/contrib, however you can modify this by using set-module-dir.

Community

An ever growing list of modules contributed by the community.

pavol

A simple module to control the volume of one PulseAudio’s sink

wicd

Commands for connecting to wireless networks

stumpwm-cmus

Cmus playback control and browsing integration

power

Suspend and hibernate commands

base16-stumpwm

Basic theming engine for StumpWM

StumpBuffer

An IBuffer inspired tool to control Stumpwm from Emacs

Restructuring Contrib (brainstorming)

A lot of this has been implemented with the current module system, but there is still work, so this is still relevant.

Using Modules

Bob writes a wallpaper setter that uses clx and another image library and has stumpwm commands that make it easy to set the wallpaper, his module is stored on github as stumpwm-wallpaper

Alice hates using feh, and wants to use Bob’s awesome code. Alice isn’t a lisper, but has been using screen and emacs for a long time. Alice types:

$ git clone github/stumpwm-wallpaper ~/quicklisp/local-projects/stumpwm-wallpaper

and then she adds to her init file:

(ql:quickload :stumpwm-wallpaper)
(stumpwm-wallpaper:set-wallpaper "~/Pictures/Kittens.jpg")

Linux Distro distribution

Dawn is an ubuntu user who wants to give stumpwm a try, she installs it with apt-get, and then reads the wiki for configuring her rc file.

Bob’s wallpaper library has been included in the modules that fall under the stumpwm organization on github. Since this is part of the stumpwm experience, it has its own package in ubuntu called stumpwm-goodies which Dawn can install with apt-get, she installs them, and configures them from the wiki without ever knowing that quicklisp exists, or what a lisp-macro is, all she knows is that her init file contains a lot of parentheses.

Creating Modules

Now lets say Carol wants to start writing a module, she opens our wiki and sees instructions that amount walk her through setting up a “Hello world” module that messages “Hello world” after the stumpwm welcome screen.

After that, all Carol has to do to make her module available to others is to add documentation to the wiki and advertise it to stumpwm-devel.

Now lets say after a while Carol’s module becomes wildly popular and really fundamentally changes the stumpwm experience for the better, at this point it make sense to include and support it in the core version shipped with each major release (think emacs and org-mode). User’s who want the bleeding edge of Carol’s work use the above mentioned way, user’s who want a stable experience with no fuss use the version shipped and supported by stumpwm.

Modules Legacy

As in 0.9.8, the contrib/ folder has been removed from the main repo and moved to we’ve also switched to an emacs-style *load-path*.

The other major change is that modules are now full asdf systems. This has some practical implications.

1. In 0.9.8, the *module-dir* is set relative to the asdf system’s location of stumpwm. Normally this is where the stumpwm sources live, but it be different depending on the setup.
2. The *module-dir* is a seed path for building the *load-path*. The *load-path* is a list of paths that contain asd files defining asdf modules.

In 0.9.9, *module-dir* will default to ${HOME}/.stumpwm.d/contrib, there is already a branch available for testing this: load-module-hacks.

Speculating on the future (never a good idea for documentation): in 1.0.0 and later, *module-dir* will probably no longer be supported in favor of *load-path* and friends.