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 section 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 section 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 COMMON-LISP-USER package. In order to use all the functions and variables defined in the StumpWM manual, you need to explicitly mention the package stumpwm:

stumpwm:*mode-line-border-width*

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

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

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

(stumpwm:set-prefix-key (stumpwm: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 Shawn Betts on August, 4 2009 using texi2html 1.78.