17.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’.

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.

This document was generated on January 28, 2024 using texi2html 1.82.