mirror of
https://github.com/xmonad/xmonad-contrib.git
synced 2025-05-19 03:20:21 -07:00
151 lines
4.9 KiB
Haskell
151 lines
4.9 KiB
Haskell
-----------------------------------------------------------------------------
|
|
-- |
|
|
-- Module : XMonad.Doc.Configuring
|
|
-- Copyright : (C) 2007 Don Stewart and Andrea Rossato
|
|
-- License : BSD3
|
|
--
|
|
-- Maintainer : andrea.rossato@unibz.it
|
|
-- Stability : unstable
|
|
-- Portability : portable
|
|
--
|
|
-- This is a brief tutorial that will teach you how to create a
|
|
-- basic xmonad configuration.
|
|
--
|
|
-- For more detailed instructions on extending xmonad with the
|
|
-- xmonad-contrib library, see "XMonad.Doc.Extending".
|
|
--
|
|
-----------------------------------------------------------------------------
|
|
|
|
module XMonad.Doc.Configuring
|
|
(
|
|
-- * Configuring xmonad
|
|
-- $configure
|
|
|
|
-- * A simple example
|
|
-- $example
|
|
|
|
-- * Checking whether your xmonad.hs is correct
|
|
-- $check
|
|
|
|
-- * Loading your configuration
|
|
-- $load
|
|
|
|
) where
|
|
|
|
--------------------------------------------------------------------------------
|
|
--
|
|
-- Configuring Xmonad
|
|
--
|
|
--------------------------------------------------------------------------------
|
|
|
|
{- $configure
|
|
#Configuring_xmonad#
|
|
xmonad can be configured by creating and editing the Haskell file:
|
|
|
|
> ~/.xmonad/xmonad.hs
|
|
|
|
If this file does not exist, xmonad will simply use default settings;
|
|
if it does exist, xmonad will use whatever settings you specify. Note
|
|
that this file can contain arbitrary Haskell code, which means that
|
|
you have quite a lot of flexibility in configuring xmonad.
|
|
|
|
NOTE for users of previous versions (< 0.5) of xmonad: this is a major
|
|
change in the way xmonad is configured. Prior to version 0.5,
|
|
configuring xmonad required editing an xmonad source file called
|
|
Config.hs, recompiling xmonad, and then restarting. From version 0.5
|
|
onwards, however, you should NOT edit this file. All you have to do
|
|
is edit xmonad.hs and restart with @mod-q@; xmonad does the
|
|
recompiling itself. The format of the configuration file has also
|
|
changed; it is now simpler and much shorter, only requiring you to
|
|
list those settings which are different from the defaults.
|
|
|
|
-}
|
|
|
|
{- $example
|
|
#A_simple_example#
|
|
|
|
Here is a basic example, which starts with the default xmonad
|
|
configuration and overrides the border width, default terminal, and
|
|
some colours:
|
|
|
|
> --
|
|
> -- An example, simple ~/.xmonad/xmonad.hs file.
|
|
> -- It overrides a few basic settings, reusing all the other defaults.
|
|
> --
|
|
>
|
|
> import XMonad
|
|
>
|
|
> main = xmonad $ defaultConfig
|
|
> { borderWidth = 2
|
|
> , terminal = "urxvt"
|
|
> , normalBorderColor = "#cccccc"
|
|
> , focusedBorderColor = "#cd8b00" }
|
|
|
|
This will run \'xmonad\', the window manager, with your settings
|
|
passed as arguments.
|
|
|
|
Overriding default settings like this (using \"record update
|
|
syntax\"), will yield the shortest config file, as you only have to
|
|
describe values that differ from the defaults.
|
|
|
|
As an alternative, you can copy the template @xmonad.hs@ file (found
|
|
either in the @man@ directory, if you have the xmonad source, or on
|
|
the xmonad wiki at
|
|
@http:\/\/haskell.org\/haskellwiki\/Xmonad\/Config_archive\/Template_Config.hs@)
|
|
into your @~\/.xmonad\/@ directory. This template file contains all
|
|
the default settings spelled out, and you should be able to simply
|
|
change the ones you would like to change.
|
|
|
|
To see what fields can be customized beyond the ones in the example
|
|
above, the definition of the 'XMonad.Core.XConfig' data structure can
|
|
be found in "XMonad.Core".
|
|
|
|
-}
|
|
|
|
{- $check
|
|
#Checking_whether_your_xmonad.hs_is_correct#
|
|
|
|
After changing your configuration, it is a good idea to check that it
|
|
is syntactically and type correct. You can do this easily by loading
|
|
your configuration file in the Haskell interpreter:
|
|
|
|
> $ ghci ~/.xmonad/xmonad.hs
|
|
> GHCi, version 6.8.2: http://www.haskell.org/ghc/ :? for help
|
|
> Loading package base ... linking ... done.
|
|
> Ok, modules loaded: Main.
|
|
>
|
|
> Prelude Main> :t main
|
|
> main :: IO ()
|
|
|
|
Ok, looks good.
|
|
|
|
Note, however, that if you skip this step and try restarting xmonad
|
|
with errors in your xmonad.hs, it's not the end of the world; xmonad
|
|
will simply display a window showing the errors and continue with the
|
|
previous configuration settings.
|
|
|
|
-}
|
|
|
|
{- $load
|
|
#Loading_your_configuration#
|
|
|
|
To get xmonad to use your new settings, type @mod-q@. xmonad will
|
|
attempt to compile this file, and run it. If everything goes well,
|
|
xmonad will seamlessly restart itself with the new settings, keeping
|
|
all your windows, layouts, etc. intact. (If you change anything
|
|
related to your layouts, you may need to hit @mod-shift-space@ after
|
|
restarting to see the changes take effect.) If something goes wrong,
|
|
the previous (default) settings will be used. Note this requires that
|
|
GHC and xmonad are in your @$PATH@. If GHC isn't in your path, you can
|
|
still compile @xmonad.hs@ yourself:
|
|
|
|
> $ cd ~/.xmonad
|
|
> $ /path/to/ghc --make xmonad.hs
|
|
> $ ls
|
|
> xmonad xmonad.hi xmonad.hs xmonad.o
|
|
|
|
When you hit @mod-q@, this newly compiled xmonad will be used.
|
|
|
|
-}
|
|
|