1. Introduction

StumpWM is an X11 window manager written entirely in Common Lisp. Its user interface goals are similar to ratpoison’s but with an emphasis on customizability, completeness, and cushiness.

1.1 Starting StumpWM

There are a number of ways to start StumpWM but the most straight forward method is as follows. This assumes you have a copy of the StumpWM source code and are using the ‘SBCL’ Common Lisp environment.

1. Install sbcl, the portable-clx package, and cl-ppcre. In Debian, portable-clx is the cl-clx-sbcl package. You can also use asdf-install to download and install clx:

   $ sbcl * (require :asdf) * (require :asdf-install) * (asdf-install:install :clx) * (asdf-install:install :cl-ppcre)

   Note that asdf-install requires gnupg.

2. In the ‘stumpwm’ directory, run ./configure.
3. run make. If all goes well, this should create a ‘stumpwm’ executable.
4. In your ‘~/.xinitrc’ file include the line /path/to/stumpwm. Remember to replace ‘/path/to/’ with the actual path.
5. Finally, start X windows with startx. Cross your fingers. You should see a ‘Welcome To the Stump Window Manager’ message pop up in the upper, right corner. At this point, you have successfully started StumpWM.

1.2 Basic Usage

Once you have StumpWM up and running, the first thing you might want to do is start emacs. Type C-t e, or in other words Control + t followed by e. Now perhaps you want an xterm. Type C-t c. Now you have some programs running.

To see a list of windows StumpWM is managing, type C-t w. The highlighted window is the one you’re looking at right now. It’s the focused window.

All of StumpWM’s keys are bound to named commands, which can be executed not only by keys but also from the input bar. Type C-t ; to open a command prompt. Now type time and press return. Note, time can also be called by typing C-t a. Throughout this manual you’ll find definitions for commands, functions, and variables. Any command you see in this manual can be executed from the input bar or bound to a key.

At this point you probably want to switch back from your new xterm to emacs. Type C-t C-t. This runs the other command. Type it again and you’re back to xterm.

Perhaps you’d like to see emacs and xterm side-by-side. Type C-t s. You have now split the screen into 2 frames. For more information see Frames. To switch to the empty frame type C-t TAB. Now let’s pull the xterm window into this empty frame. Type C-t w for a window listing. Find the xterm window. See the number beside it? Type C-t followed by xterm’s window number.

Another common activity is browsing the interwebs. Type C-t !. The input bar pops up again. You can now run a shell command. Let’s start a web browser: type firefox into the input bar and press return.

Unfortunately, firefox probably isn’t wide enough because it’s in one of the frames. Type C-t Q to remove all frames but the current one and resize it to fit the screen.

For a full list of key bindings, see List of Default Keybindings.

1.3 Interacting with the Lisp process

Since StumpWM is a Lisp program, there is a way for you to evaluate Lisp code directly, on the same Lisp process that StumpWM is running on. Type C-t : and an input box will appear. Then type some Lisp expression.

When you call eval this way, you will be in the STUMPWM-USER package, which imports all the exported symbols from the main STUMPWM package.

*mode-line-border-width*

Reads the value of *mode-line-border-width*.

(setf *mode-line-border-width* 3)

Sets the variable *mode-line-border-width* to 3.

(set-prefix-key (kbd "C-M-H-s-z"))

Calls the set-prefix-key function (and sets a new keyboard prefix)

1.4 Contact the StumpWM developers

The StumpWM home page is http://stumpwm.nongnu.org/.

You can reach Shawn Betts at sabetts at vcn.bc.ca.

The StumpWM mailing list is stumpwm-devel@nongnu.org which you can subscribe to at http://mail.nongnu.org/mailman/listinfo/stumpwm-devel. Posting is restricted to subscribers to keep spam out of the archives.

The StumpWM IRC channel can be found on Freenode at #stumpwm.

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