<?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://www.cs.york.ac.uk/fp/darcs/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>