16. Modules

A module is an ASDF system that adds additional functionality to StumpWM. StumpWM searches for modules in the *data-dir*‘/modules’ directory. By default this is ‘~/.stumpwm.d/modules’.

Officially supported modules exist in a separate repository within the StumpWM organization on github. You can install the latest copy by issuing make install-modules from StumpWM’s root source directory. This will run:

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

Command: load-module name: Loads the contributed module with the given NAME.

Function: list-modules: Return a list of the available modules.

Variable: *load-path*: A list of paths in which modules can be found, by default it is populated by any asdf systems found in ‘*module-dir*’ set from the configure script when StumpWM was built, or later by the user using ‘add-to-load-path’

Command: add-to-load-path path: If ‘PATH’ is not in ‘*LOAD-PATH*’ add it, check if ‘PATH’ contains an asdf system, and if so add it to the central registry

Function: init-load-path path: Recursively builds a list of paths that contain modules. This is called each time StumpWM starts with the argument ‘*module-dir’

Function: find-module name: nil

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

16.1 Writing Modules

Make sure to read Hacking. If you are familiar with writing lisp packages for ASDF then you can jump in and get started. In either case, quicklisp ships a quickproject package that makes setting up a new module very easy. After installing quicklisp (see the README.md for a link):

We’re going to put our new module in the ‘modules/’ directory of *data-dir* so that it will be immediately loadable by StumpWM.

First make the directory ‘new-module’, then from a REPL issue:

(ql:quickload "quickproject")
(quickproject:make-project #p"~/.stumpwm.d/modules/new-module" :depends-on '(stumpwm) :name "new-module")

This will create:

  -rw-rw-r--  1 dave dave   68 Apr  6 19:38 package.lisp
  -rw-rw-r--  1 dave dave   53 Mar 16  2014 README.txt
  -rw-rw-r--  1 dave dave  271 Mar 16  2014 new-module.asd
  -rw-rw-r--  1 dave dave 1.8K Apr  6 17:51 new-module.lisp

The file ‘new-module.lisp’ will contain the actual implementation of your module. ASDF requires two other files in order to understand how to load and compile your module. They are ‘new-module.asd’ and ‘package.lisp’. In our example, ‘new-module.asd’ should contain:

(asdf:defsystem #:new-module
  :serial t
  :description "Describe new-module here"
  :author "Anne N. O'Nymous"
  :license "GPLv3"
  :depends-on (#:stumpwm)
  :components ((:file "package")
               (:file "new-module"))) ; any other files you make go here

The ‘package.lisp’ will contain:

(defpackage #:new-module
  (:use #:cl :stumpwm))

With these two files defined, and the implementation written in ‘new-module.lisp’, you should be able to load your module.

Before we load it, we have to add the path to our *load-path*. This can be accomplished by running the following from a REPL:

(stumpwm:add-to-load-path "~/.stumpwm.d/modules/new-module")

You can also run this interactively with C-t ;, which is bound to the colon command.

Because we’ve put our module in a sub-directory of the default *module-dir*, it will automatically get added to the *load-path* the next time StumpWM starts. If you choose to develop your module somewhere else (e.g. ‘~/quicklisp/local-projects’), then you’ll have add

(add-to-load-path "~/quicklisp/local-projects/new-module")

to your ‘.stumpwmrc’.