Xmonad/Guided tour of the xmonad source

Contents

Introduction

Do you know a little Haskell and want to see how it can profitably be
applied in a real-world situation? Would you like to quickly get up
to speed on the xmonad source code so you can contribute modules and
patches? Do you aspire to be as cool of a hacker as the xmonad
authors? If so, this might be for you. Specifically, this document
aims to:

Provide a readable overview of the xmonad source code for Haskell non-experts interested in contributing extensions or modifications to xmonad, or who are just curious.

Highlight some of the uniquenesses of xmonad and the things that make functional languages in general, and Haskell in particular, so ideally suited to this domain.

This is not a Haskell tutorial. I assume that you already know some
basic Haskell: defining functions and data; the type system; standard
functions, types, and type classes from the Standard Prelude; and at least
a basic familiarity with monads. With that said, however, I do take
frequent detours to highlight and explain more advanced topics and
features of Haskell as they arise.

First things first

You'll want to have your own version of the xmonad source code to refer to as you read through the guided tour. In particular, you'll want the latest
git version, which you can easily download by issuing the command:

I intend for this guided tour to keep abreast of the latest changes; if you see something which is out of sync, report it on the xmonad mailing list, or -- even better -- fix it!

You may also want to refer to the Haddock-generated documentation (it's all in the source code, of course, but may be nicer to read this way). XMonad uses stack which can be used to build the documentation. Go to the root of the xmonad source directory and issue the command:

stack haddock

which will generate HTML documentation in .stack-work/dist/<GHCVersion>/<CabalVersion>/doc/html/xmonad/.

Of course, the documentation of the latest release can also be found online.

Without further ado, let's begin!

StackSet.hs

StackSet.hs is the pure, functional heart of xmonad. Far removed from corrupting pollutants such as the IO monad and the X server, it is a beautiful, limpid pool of pure code which defines most of the basic data structures used to store the state of xmonad. It is heavily validated by QuickCheck tests; the combination of good use of types and QuickCheck validation means that we can be very confident of the correctness of the code in StackSet.hs.