[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 |
Loads the contributed module with the given NAME.
Return a list of the available modules.
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’
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
Recursively builds a list of paths that contain modules. This is called each time StumpWM starts with the argument ‘*module-dir’
nil
16.1 Writing Modules |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by Raimon Grau on May 28, 2019 using texi2html 1.82.