Stumpwm

Related articles
Window manager
Ratpoison
Cagebreak
StumpWM is a manually tiling, keyboard driven X11 window manager written entirely in Common Lisp.
The spiritual successor to the cult classic
Ratpoison
, StumpWM adds all the flexibility and hackability of
Common Lisp
, allowing the user to make modifications to the source of the window manager even while it is running. It is also known as "the emacs of WMs."
From
StumpWM's homepage
:
StumpWM attempts to be customizable yet visually minimal. There are no window decorations, no icons, and no buttons. It does have various hooks to attach your personal customizations, and variables to tweak.
Hack the good hack
Debug your good hack
Customize your window manager
While it's running That's right. With a 100% Common Lisp window manager there is no stopping the hacks. Just re-eval and GO!
Want to see it in action? A StumpWM user created a
video
.
Installation
A runnable StumpWM installation consists of 3 parts:
Common Lisp REPL
StumpWM Lisp package and its dependencies
Executable file as entry point
Install via Package Manager
Install
stumpwm
or
stumpwm-git
AUR
.
If you are installing without an AUR helper, you should install these packages in the following order:
sbcl
cl-alexandria-git
AUR
clx-git
AUR
cl-ppcre
stumpwm
or
stumpwm-git
AUR
After installing put
exec stumpwm
in your
~/.xinitrc
and run
startx
.
To quit, with the default configuration press
C-t ;
then type quit and press enter.
Both packages will install an xsession entry in
/usr/share/xsessions
so if you use a display manager that checks that directory, you should be good to go.
For a list of commonly used key-bindings, press
C-t ?
.
Install via Roswell
It is highly recommended to use
roswell
to manage your Lisp REPL.
This method makes it easy to upgrade StumpWM together with other Lisp packages using
ql:update-all-dists
.
to start REPL in
roswell
run
ros run
in terminal, to install stumpwm run
(ql:quickload :stumpwm)
inside REPL
in order to launch it through login manager or
~/.xinitrc
, an executable file must be created. create new project using
roswell
:
ros init stumpwm
Create
stumpwm.ros
:
stumpwm.ros
#!/bin/sh
#|-*- mode:lisp -*-|#
#|
exec ros -Q -- $0 "$@"
|#

(progn 
  #+quicklisp (ql:quickload '(stumpwm) :silent t))

(defpackage :ros.script.stumpwm.3749863733
  (:use :cl))
(in-package :ros.script.stumpwm.3749863733)

(defun main (&rest argv)
  (declare (ignorable argv))
  (stumpwm:stumpwm))
Then place
stumpwm.ros
file to wherever you like and make it the entry point of this awesome WM.
To add stumpwm to the Login Manager, create
stumpwm.desktop
in
/usr/share/xsessions/
:
stumpwm.desktop
[Desktop Entry]
Encoding=UTF-8
Name=StumpWM
Comment=Login using StumpWM
Exec=/path/to/stumpwm.ros
Type=XSession
or you can just start using
~/.xinitrc
exec /path/to/stumpwm.ros
Documentation and support
There is a TeXInfo manual included in the AUR packages, the source, and
online
.
There is also a
wiki
, an IRC channel
#stumpwm
on Libera Chat, and a
mailing list
. For more information, see
the project's website
.
Configuration
StumpWM stores its configuration in
~/.stumpwmrc
or you can use
~/.config/stumpwm/config
Change cursor from default X shape
By default StumpWM leaves the cursor as XOrg's standard X shape with the hotspot in the centre. You can have the more usual left-facing pointer by running
$ xsetroot -cursor_name left_ptr
You can also put this in your configuration file
(run-shell-command "xsetroot -cursor_name left_ptr")
Change window focus on mouse click
Clicking on another window will send the click event to that window, but it will not get focus meaning any keyboard input will go to whichever window has focus. The following line makes focus change to any window that is clicked on.
(setf *mouse-focus-policy* :click)
Enable modeline
This sets up a basic modeline with the group name followed by window names on the left and the date and time on the right.
First set the window name format and overall modeline format
(setf *window-format* "%m%n%s%c")
(setf *screen-mode-line-format* (list "[^B%n^b] %W^>%d"))
The date format is constructed using the same format specifiers as
strftime(3)
e.g.
(setf *time-modeline-string* "%a %b %e %k:%M")
Optionally change how often the modeline updates on its own, in seconds (it also updates whenever you do something with StumpWM like switch window).
(setf *mode-line-timeout* 2)
Finally enable the modeline (this must come
after
you have set the options you wanted)
(enable-mode-line (current-screen) (current-head) t)
Set font for messages and modeline
StumpWM uses the default XOrg font which is probably small and pixelated. You can set font by calling, for example,
(set-font "-xos4-terminus-medium-r-normal-*-20-*-*-*-*-*-*-*")
where the string is generated by
xorg-xfontsel
.
There are 2 external modules which allow you to use TTF fonts:
ttf-fonts
and
sdl-fonts
.
sdl-fonts
is a very thin wrapper of SDL2_ttf while
ttf-fonts
delegates to another Lisp module –
clx-truetype
– which uses Lisp-native TTF parser and renderer. Initial tests show
sdl-fonts
performing better and being more stable overall.
To use
sdl-fonts
you need to install SDL2_ttf on your system. The following code demonstrates how to load a font
(load-module "sdl-fonts")
(defparameter *the-font* (sdl-fonts:load-font "/usr/share/fonts/TTF/DroidSansMono.ttf" 14))
(set-font *the-font)
For
ttf-fonts
, you will need to install
clx-truetype
which is not in the QuickLisp distribution any more. Get a copy of it
here
or from a backed up repository, put it under your
~/quicklisp/local-projects/
, and run
(ql:quickload "clx-truetype")
(load-module "ttf-fonts")
(xft:cache-fonts) ;; Tell clx-truetype about the fonts you have installed. You really only need to do this once, but putting it here means you will not forget in the future.
(set-font (make-instance 'xft:font :family "DejaVu Sans Mono" :subfamily "Book" :size 11))
Tip
You need to install the
quicklisp
package for it to work.
You need to install the
ttf-fonts
and
sdl-fonts
modules from
stumpwm-contrib
(see
#Tweaking
).
Note
Currently, the
clx-truetype
package needed by this module has been removed from newest versions of quicklisp. If you want to use this module, make sure to rollback to older versions or manually add them to quicklisp. See the
discussion
and the
issue
.
Tweaking
See the wiki for a variety of useful tweaks for your .stumpwmrc.
Additionally, the
stumpwm-contrib
repository contains many useful utilities, and can be installed via
stumpwm-contrib-git
AUR
. For example, if you are an emacs user, you will find an emacs minor mode for editing
StumpWM files (and interfacing with the program
stumpish
, but
more on that below).
stumpish
is the STUMP window manager Interactive SHell. It is
a program that allows the user to interact with StumpWM while it is
running, from the comfort of a terminal (or using the emacs mode). It
is installed with StumpWM in
/usr/bin/
.
Troubleshooting
If you have problems configuring multiple monitors, maybe you need to install 'xorg-xdpyinfo' package.
If you cannot start stumpwm and get
debugger invoked on a SB-INT:SIMPLE-PARSE-ERROR in thread
       #:
       no non-whitespace characters in string "".
       Type HELP for debugger help, or (SB-EXT:QUIT) to exit from SBCL.
       (no restarts: If you did not do this on purpose, please report it as a bug.)
       (PARSE-INTEGER "" :START 0 :END NIL :RADIX 10 :JUNK-ALLOWED NIL)
in the REPL, it can be solved by deleting
~/.Xauthority
. See
this issue on github
If you have an issue with the SBCL_HOME being set to NIL, you may need to set it manually
Tip
You can find the path using
find / | grep sbcl.core
$ export SBCL_HOME=/usr/lib/sbcl/
Then you may reinstall stumpwm
If you cannot use the mousewheel to scroll in some programs, try adding
(setf (getenv "GDK_CORE_DEVICE_EVENTS") "1")
to your
.stumpwmrc
(source:
[1]
)
Quicklisp will not work in StumpWM if you installed it after installing StumpWM - in that case uninstall and reinstall StumpWM
See also
StumpWM Web Site
StumpWM Community Wiki
Awesome StumpWM: A list of high-quality docs/modules/configs for StumpWM
github.com/stumpwm/mahogany
A very experimental/WIP clone of StumpWM for
Wayland