xmonad logo

      xmonad

      building and installation

Introduction

xmonad is a tiling window manager for X11. This document describes how to build and install xmonad. For its features and use, see the guided tour.

Use a pre-built binary

Your operating system distribution may have binary packages for xmonad already, or perhaps, many of their dependencies. If at all possible, use one of these pre-built packages. See the main page for distributions that distribute xmonad binaries.

Building xmonad from source is simple. It requires a basic Haskell toolchain, only. We'll now walk through the complete list of toolchain dependencies.

Install GHC

To build xmonad, you need the GHC Haskell compiler installed. All common operating systems provide prebuilt binaries of GHC in their package systems. For example, in Debian you would install GHC with: 

    $ apt-get install ghc6

If your operating system's package system doesn't provide a binary version of GHC, you can find pre-built binaries at the GHC home page. It shouldn't be necessary to compile GHC from source -- every common system has a pre-build binary version.

We recommend the latest stable release of GHC.

X11 libraries

Since you're building an X application, you'll need the C X11 library headers. On many platforms, these come pre-installed. For others, such as Debian, you can get them from your package manager: 

    $ apt-get install libx11-dev

Typically you need the C libraries: libXinerama libXext libX11

Cabal

xmonad requires a recent version of Cabal, greater than or equal to 1.2.0. If you're using GHC 6.8, then it comes bundled with the right version of Cabal by default. If you're using GHC 6.6.x, you'll need to build and install Cabal from Hackage first, or from your package system.

All Haskell packages build the same way, and Cabal is no exception. Download and unpack the .tar.gz library source, then issue the commands to configure, build and install the library: 

    $ runhaskell Setup.lhs configure --user --prefix=$HOME
    $ runhaskell Setup.lhs build
    $ runhaskell Setup.lhs install --user

Haskell libraries

Once you've either installed GHC and Cabal or built them, you've now got a basic Haskell toolchain. So now check you have the required Haskell libraries installed:

You can check if you have these libraries with the command: 

    $ ghc-pkg list

Which should list mtl, unix and perhaps the X11 library, amongst other things. If these libraries aren't available, you'll need to install them from Hackage, which is very simple, using the instructions provided above.

Build xmonad

xmonad is just another cabal package. Grab the latest release of xmonad from hackage.haskell.org, here, and then build as for other cabal packages: 

    $ runhaskell Setup.lhs configure --user --prefix=$HOME
    $ runhaskell Setup.lhs build
    $ runhaskell Setup.lhs install --user

And that's it. Compiled, and ready to go.

If things go wrong..

From time to time people have build problems. Almost always this is due to missing dependencies. Sometimes it is due to problems with the tool chain. The most common problems building xmonad are documented in the FAQ:

If this doesn't help, try asking on the IRC channel, #xmonad @ freenode.org, or on the mailing list.

Building the extension library

xmonad 0.5 and later provide a library of extensions as a normal Haskell library. Download it from Hackage, using the links from the front page, build it as a for other Haskell libraries and install. You may then import modules from the extension library into your xmonad.hs configuration file.

More information about extension and configuration...

Grab dmenu and dzen

Extra programs that make life with xmonad more exciting: dmenu and dzen. dmenu provides a simple popup menu for launching programs, dzen provides customisable status bars. You can get them here:

Starting xmonad

The simplest way to start xmonad is to modify your .xsession or .xinitrc and add the line: 

    $HOME/bin/xmonad

as the last line of your file, commenting out any previous window manager. Now, when you log in to X, xmonad will start, (by default in tall tiling mode, with no status bar), and you'll be presented with an empty screen:

no windows open

From here, and assuming you can find the mod1 modifier key (usually 'alt'), you can launch clients and access the rest of the window manager's features. The basic key bindings are:

mod-shift-return launch xterm
mod-p launch dmenu
mod-space cycle through available layout algorithms
mod-c kill a client window
mod-j move focus to the next window on the screen (also mod-tab)
mod-k move focus to the previous window
mod-return swap current window, with window in master pane
mod-shift-j swap current window with its next neighbour
mod-shift-k swap current window with its previous neighbour
mod-h shrink the size of the master pane
mod-l grow the size of the master pane
mod-comma move clients into the master pane
mod-period move clients out of the master pane
mod-q dynamically reload xmonad, with a new configuration
mod-shift-q quit xmonad
mod-1 .. 9 move to workspace ("virtual desktop"/"window group") number 'n'
mod-shift- 1 .. 9 move current client to workspace number 'n'
mod- w,e,r move to Xinerama screens 1, 2 or 3.

To learn more about how to use these bindings to achieve your desired workspace configuration, see The Guided Tour. An example of a fully set up workspace, with status bars:

after tweaking

xmonad natively supports Xinerama, allowing several physical screens to show separate workspaces. You may run different status bars, and different layouts on each screen, and jump between them dynamically. For more on this, see the guided tour section on workspaces.

Building xmonad with cabal-install

Recent versions of Cabal provide a tool, cabal-install, which automates the building of Haskell libraries, including gathering all dependencies. Here's how to build xmonad automatically, using cabal-install:

  • Upgrade to the latest Cabal (currently 1.3 is only avaliable via darcs):
    • darcs get --partial http://darcs.haskell.org/cabal
  • Download and build cabal-install's dependencies listed here. Many of these should already be installed.
  • Download and build cabal-install.

Once you have a working cabal-install, you can then simply install any Haskell package you find on hackage.haskell.org, such as xmonad: 

    $ cabal install xmonad