[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

15. Modules

A module is a 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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

15.1 Writing Modules

Make sure to read the Hacking. If you are familiar with writing 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’.

When you’ve finished writing your module, you can distribute it however you see fit. If it becomes very popular, or you would like the StumpWM devs to maintain it (and they agree), you can have your module merged with the stumpwm-contrib repository on github, just open a pull request to start the discussion.

[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by David Bjergaard on November 7, 2014 using texi2html 1.82.