Saturday, August 4, 2007

How to Install Xmonad on Gentoo

Please Note:
This post is presumably severely dated. I no longer use Xmonad (viva la Stumpwm), so I have not tried to keep this updated. Should you wish to install Xmonad on Gentoo, this is probably not the tutorial to follow. Still, though, you might glean something useful from it.

So, you've heard good things about Xmonad, the minimalistic, tiling window manager for X, and you'd like to give it a try on your Gentoo box. Here's how to do it, and get a respectable Haskell development environment in the process.

Note: This tutorial assumes you want to do things the Gentoo way, i.e. by using Portage. Another option is to build the Haskell compiler, required libraries, and Xmonad from source, and if you'd rather follow this method, the Xmonad site has the details. This tutorial also assumes that you know your way around Gentoo, and know what you're doing, or you are good at pretending you do. Since you're installing things, you will probably need to be root for this.

Step 0: Important!
Since I wrote this, changes to the Haskell overlay, etc., may have occurred. I highly advise you to read the post's comments so that you can "interpret" anything you read here in light of them.

Step 1: Install the Haskell Overlay
First, you need to install the Haskell Portage overlay, which contains newer Haskell-related packages than those found in Portage. If layman, the overlay manager, is not installed, you should first emerge it and update its overlay list.

# emerge layman
# layman --fetch

Once layman is installed, your next task is to enable Darcs-based overlays, which, not surprisingly, require the Darcs distributed source code management system to be present. Here a chicken-and-egg problem arises, as Darcs is written in Haskell and thus requires GHC and the core Haskell libraries. However, you want to avoid installing Haskell until after the overlay is installed, in order to avoid having to upgrade Haskell and friends later. My solution is to use a statically-linked Linux binary provided by the Darcs project.

# wget
# gunzip darcs-1.0.7-i386-linux.gz
# mv darcs-1.0.7-i386-linux /usr/bin/darcs
# chmod +x /usr/bin/darcs

You now have a working darcs command, which layman will use to pull in the Haskell overlay, after which you may remove the darcs binary.

# layman -a haskell
# rm /usr/bin/darcs

If this is the first overlay you have installed (in other words, if you emerged layman above), you will need to add a line to your /etc/make.conf. This is necessary to keep Portage happy.

# echo "source /usr/portage/local/layman/make.conf" >> /etc/make.conf

Step 2: Install GHC and Friends
Your next task is installing GHC, the Glorious Glasgow Haskell Compilation System, and its partners in crime. The following lines need to be added to your /etc/portage/package.keywords file to ensure that GHC and friends build from the Haskell overlay:


An addition to /etc/portage/package.use is also necessary to pull in the binary GHC package, as opposed to bootstrapping it.

# echo "dev-lang/ghc binary" >> /etc/portage/package.use

You're now ready to emerge GHC!

# emerge dev-lang/ghc

Step 3: Install Darcs
In view of the possible future in which you become a Haskell fanboy or fangirl, and decide that Darcs is the perfect tool to manage your projects, you need to install Darcs. It's also necessary because you are going to pull the very newest Xmonad sources from a Darcs tree in Step 4. This time you'll build Darcs from source. Add the following to /etc/portage/package.keywords:


Then, emerge darcs. I got an error when I did this.

!!! Digest verification failed:
!!! /usr/portage/distfiles/darcs-1.1.0pre1.tar.gz
!!! Reason: Filesize does not match recorded size
!!! Got: 1116180
!!! Expected: 1112362

Because Portage pulled the distfile directly from the Darcs site, I assumed it was safe, and used the ebuild command to update the Manifest file for Darcs, and emerged the package again:

# cd /usr/portage/local/layman/haskell/dev-util/darcs
# ebuild darcs-1.1.0_pre1.ebuild digest

# emerge darcs

Step 4: Install Xmonad
Now that everything is in place, it's time to install Xmonad! First, add the following lines to your /etc/portage/package.keywords:


Next, you'll need to add a line to /etc/portage/package.use in order to instruct Portage to build Xmonad with the "extensions" USE keyword, which will enable a variety of layout algorithms and other nifty things you may want at some point.

# echo "x11-wm/xmonad-darcs extensions" >> /etc/portage/package.use

It's now time to emerge xmonad-darcs. After doing so, you need to specify xmonad-darcs as your window manager, using whatever mechanism you currently use. For me, that meant updating my .xinitrc with an "exec xmonad-darcs" line.

Step 5: Install dmenu and dzen (optional)
Xmonad has two pals it gets along well with: dmenu, a lightweight program launcher, and dzen, a status bar program. You don't have to install them, but they're useful, and you won't be inducted into the Church of Xmonad unless you do.

dmenu installation is as simple as running emerge dmenu. After adding a line to /etc/portage/package.keywords, dzen installation is just as simple.

# echo "x11-misc/dzen" >> /etc/portage/package.keywords

If you have followed this tutorial, and assuming I didn't goof up horribly, you should have a functional Xmonad system. Head over to the Xmonad overview to find out more about what you can do with Xmonad.


Jordan Wilberding said...

I followed your tutorial and it worked well. I only ran into a few problems because I had a previously installed some Haskell components which I had to reinstall after installing darcs and ghc in the beginning.

Thanks a bunch for this.

Joseph said...


Yeah, the same thing happened to me the first time I tried to install Xmonad. Glad you found the tutorial helpful.

Anonymous said...

Thanks for this! An update: it looks like the Haskell overlay is not currently self-consistent, due to packages not having caught up with the newer GHC and Cabal. I had to use the following version restrictions in package.keywords in order to get everything to build:


Jason Dusek said...

How does configuration work with XMonad? Just modifying


and reloading does not actually work. Is
there a way to distinguish between 'user' and 'system' configuration?

comrad said...


For me even with this specification it can not be installed. It's a pity, cause I wanted to try this. :(

Anonymous said...

for installing ghc and cabal,
try first =dev-haskel/mtl
it follows as depends

and successfully inst...

entropie said...

Your post is not really up2date but helpfull anyways. Used it the second time to get xmonad from the haskell overlay working.
Thanks alot for your afford.