<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<!-- Generated by HsColour, http://code.haskell.org/~malcolm/hscolour/ -->
<title>XMonad/Doc/Configuring.hs</title>
<link type='text/css' rel='stylesheet' href='hscolour.css' />
</head>
<body>
<pre><a name="line-1"></a><span class='hs-comment'>-----------------------------------------------------------------------------</span>
<a name="line-2"></a><span class='hs-comment'>-- |</span>
<a name="line-3"></a><span class='hs-comment'>-- Module : XMonad.Doc.Configuring</span>
<a name="line-4"></a><span class='hs-comment'>-- Copyright : (C) 2007 Don Stewart and Andrea Rossato</span>
<a name="line-5"></a><span class='hs-comment'>-- License : BSD3</span>
<a name="line-6"></a><span class='hs-comment'>--</span>
<a name="line-7"></a><span class='hs-comment'>-- Maintainer : andrea.rossato@unibz.it</span>
<a name="line-8"></a><span class='hs-comment'>-- Stability : unstable</span>
<a name="line-9"></a><span class='hs-comment'>-- Portability : portable</span>
<a name="line-10"></a><span class='hs-comment'>--</span>
<a name="line-11"></a><span class='hs-comment'>-- This is a brief tutorial that will teach you how to create a</span>
<a name="line-12"></a><span class='hs-comment'>-- basic xmonad configuration.</span>
<a name="line-13"></a><span class='hs-comment'>--</span>
<a name="line-14"></a><span class='hs-comment'>-- For more detailed instructions on extending xmonad with the</span>
<a name="line-15"></a><span class='hs-comment'>-- xmonad-contrib library, see "XMonad.Doc.Extending".</span>
<a name="line-16"></a><span class='hs-comment'>--</span>
<a name="line-17"></a><span class='hs-comment'>-----------------------------------------------------------------------------</span>
<a name="line-18"></a>
<a name="line-19"></a><span class='hs-keyword'>module</span> <span class='hs-conid'>XMonad</span><span class='hs-varop'>.</span><span class='hs-conid'>Doc</span><span class='hs-varop'>.</span><span class='hs-conid'>Configuring</span>
<a name="line-20"></a> <span class='hs-layout'>(</span>
<a name="line-21"></a> <span class='hs-comment'>-- * Configuring xmonad</span>
<a name="line-22"></a> <span class='hs-comment'>-- $configure</span>
<a name="line-23"></a>
<a name="line-24"></a> <span class='hs-comment'>-- * A simple example</span>
<a name="line-25"></a> <span class='hs-comment'>-- $example</span>
<a name="line-26"></a>
<a name="line-27"></a> <span class='hs-comment'>-- * Checking whether your xmonad.hs is correct</span>
<a name="line-28"></a> <span class='hs-comment'>-- $check</span>
<a name="line-29"></a>
<a name="line-30"></a> <span class='hs-comment'>-- * Loading your configuration</span>
<a name="line-31"></a> <span class='hs-comment'>-- $load</span>
<a name="line-32"></a>
<a name="line-33"></a> <span class='hs-layout'>)</span> <span class='hs-keyword'>where</span>
<a name="line-34"></a>
<a name="line-35"></a><span class='hs-comment'>--------------------------------------------------------------------------------</span>
<a name="line-36"></a><span class='hs-comment'>--</span>
<a name="line-37"></a><span class='hs-comment'>-- Configuring Xmonad</span>
<a name="line-38"></a><span class='hs-comment'>--</span>
<a name="line-39"></a><span class='hs-comment'>--------------------------------------------------------------------------------</span>
<a name="line-40"></a>
<a name="line-41"></a><span class='hs-comment'>{- $configure
<a name="line-42"></a>#Configuring_xmonad#
<a name="line-43"></a>xmonad can be configured by creating and editing the Haskell file:
<a name="line-44"></a>
<a name="line-45"></a>> ~/.xmonad/xmonad.hs
<a name="line-46"></a>
<a name="line-47"></a>If this file does not exist, xmonad will simply use default settings;
<a name="line-48"></a>if it does exist, xmonad will use whatever settings you specify. Note
<a name="line-49"></a>that this file can contain arbitrary Haskell code, which means that
<a name="line-50"></a>you have quite a lot of flexibility in configuring xmonad.
<a name="line-51"></a>
<a name="line-52"></a>HISTORICAL NOTE regarding upgrading from versions (< 0.5) of xmonad
<a name="line-53"></a>or using old documentation:
<a name="line-54"></a>
<a name="line-55"></a>xmonad-0.5 delivered a major change in the way xmonad is configured. Prior
<a name="line-56"></a>to version 0.5, configuring xmonad required editing a source file called
<a name="line-57"></a>Config.hs, manually recompiling xmonad, and then restarting. From
<a name="line-58"></a>version 0.5 onwards, however, you should NOT edit this file or manually
<a name="line-59"></a>compile with ghc --make. All you have to do is edit xmonad.hs and restart
<a name="line-60"></a>with @mod-q@; xmonad does the recompiling itself. The format of the
<a name="line-61"></a>configuration file also changed with version 0.5; enabling simpler and
<a name="line-62"></a>much shorter xmonad.hs files that only require listing those settings which
<a name="line-63"></a>are different from the defaults.
<a name="line-64"></a>
<a name="line-65"></a>While the complicated template.hs (man/xmonad.hs) files listing all default
<a name="line-66"></a>settings are still provided for reference, once you wish to make substantial
<a name="line-67"></a>changes to your configuration, the template.hs style configuration is not
<a name="line-68"></a>recommended. It is fine to use top-level definitions to organize your
<a name="line-69"></a>xmonad.hs, but wherever possible it is better to leave out settings that
<a name="line-70"></a>simply duplicate defaults.
<a name="line-71"></a>-}</span>
<a name="line-72"></a>
<a name="line-73"></a><span class='hs-comment'>{- $example
<a name="line-74"></a>#A_simple_example#
<a name="line-75"></a>
<a name="line-76"></a>Here is a basic example, which starts with the default xmonad
<a name="line-77"></a>configuration and overrides the border width, default terminal, and
<a name="line-78"></a>some colours:
<a name="line-79"></a>
<a name="line-80"></a>> --
<a name="line-81"></a>> -- An example, simple ~/.xmonad/xmonad.hs file.
<a name="line-82"></a>> -- It overrides a few basic settings, reusing all the other defaults.
<a name="line-83"></a>> --
<a name="line-84"></a>>
<a name="line-85"></a>> import XMonad
<a name="line-86"></a>>
<a name="line-87"></a>> main = xmonad $ defaultConfig
<a name="line-88"></a>> { borderWidth = 2
<a name="line-89"></a>> , terminal = "urxvt"
<a name="line-90"></a>> , normalBorderColor = "#cccccc"
<a name="line-91"></a>> , focusedBorderColor = "#cd8b00" }
<a name="line-92"></a>
<a name="line-93"></a>This will run \'xmonad\', the window manager, with your settings
<a name="line-94"></a>passed as arguments.
<a name="line-95"></a>
<a name="line-96"></a>Overriding default settings like this (using \"record update
<a name="line-97"></a>syntax\"), will yield the shortest config file, as you only have to
<a name="line-98"></a>describe values that differ from the defaults.
<a name="line-99"></a>
<a name="line-100"></a>As an alternative, you can copy the template @xmonad.hs@ file (found
<a name="line-101"></a>either in the @man@ directory, if you have the xmonad source, or on
<a name="line-102"></a>the xmonad wiki config archive at
<a name="line-103"></a><<a href="http://haskell.org/haskellwiki/Xmonad/Config_archive">http://haskell.org/haskellwiki/Xmonad/Config_archive</a>>)
<a name="line-104"></a>into your @~\/.xmonad\/@ directory. This template file contains all
<a name="line-105"></a>the default settings spelled out, and you should be able to simply
<a name="line-106"></a>change the ones you would like to change.
<a name="line-107"></a>
<a name="line-108"></a>To see what fields can be customized beyond the ones in the example
<a name="line-109"></a>above, the definition of the 'XMonad.Core.XConfig' data structure can
<a name="line-110"></a>be found in "XMonad.Core".
<a name="line-111"></a>
<a name="line-112"></a>-}</span>
<a name="line-113"></a>
<a name="line-114"></a><span class='hs-comment'>{- $check
<a name="line-115"></a>#Checking_whether_your_xmonad.hs_is_correct#
<a name="line-116"></a>
<a name="line-117"></a>After changing your configuration, it is a good idea to check that it
<a name="line-118"></a>is syntactically and type correct. You can do this easily by using an xmonad
<a name="line-119"></a>flag:
<a name="line-120"></a>
<a name="line-121"></a>> $ xmonad --recompile
<a name="line-122"></a>> $
<a name="line-123"></a>
<a name="line-124"></a>If there is no output, your xmonad.hs has no errors. If there are errors, they
<a name="line-125"></a>will be printed to the console. Patch them up and try again.
<a name="line-126"></a>
<a name="line-127"></a>Note, however, that if you skip this step and try restarting xmonad
<a name="line-128"></a>with errors in your xmonad.hs, it's not the end of the world; xmonad
<a name="line-129"></a>will simply display a window showing the errors and continue with the
<a name="line-130"></a>previous configuration settings. (This assumes that you have the
<a name="line-131"></a>\'xmessage\' utility installed; you probably do.)
<a name="line-132"></a>
<a name="line-133"></a>-}</span>
<a name="line-134"></a>
<a name="line-135"></a><span class='hs-comment'>{- $load
<a name="line-136"></a>#Loading_your_configuration#
<a name="line-137"></a>
<a name="line-138"></a>To get xmonad to use your new settings, type @mod-q@. (Remember, the
<a name="line-139"></a>mod key is \'alt\' by default, but you can configure it to be
<a name="line-140"></a>something else, such as your Windows key if you have one.) xmonad will
<a name="line-141"></a>attempt to compile this file, and run it. If everything goes well,
<a name="line-142"></a>xmonad will seamlessly restart itself with the new settings, keeping
<a name="line-143"></a>all your windows, layouts, etc. intact. (If you change anything
<a name="line-144"></a>related to your layouts, you may need to hit @mod-shift-space@ after
<a name="line-145"></a>restarting to see the changes take effect.) If something goes wrong,
<a name="line-146"></a>the previous (default) settings will be used. Note this requires that
<a name="line-147"></a>GHC and xmonad are in the @$PATH@ in the environment from which xmonad
<a name="line-148"></a>is started.
<a name="line-149"></a>
<a name="line-150"></a>-}</span>
<a name="line-151"></a>
</pre></body>
</html>
