mirror of
https://github.com/xmonad/xmonad-contrib.git
synced 2025-05-19 11:30:22 -07:00
152 lines
5.3 KiB
Haskell
152 lines
5.3 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.
|
|
|
|
HISTORICAL NOTE regarding upgrading from versions (< 0.5) of xmonad
|
|
or using old documentation:
|
|
|
|
xmonad-0.5 delivered a major change in the way xmonad is configured. Prior
|
|
to version 0.5, configuring xmonad required editing a source file called
|
|
Config.hs, manually recompiling xmonad, and then restarting. From
|
|
version 0.5 onwards, however, you should NOT edit this file or manually
|
|
compile with ghc --make. 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 also changed with version 0.5; enabling simpler and
|
|
much shorter xmonad.hs files that only require listing those settings which
|
|
are different from the defaults.
|
|
|
|
While the complicated template.hs (man/xmonad.hs) files listing all default
|
|
settings are still provided for reference, once you wish to make substantial
|
|
changes to your configuration, the template.hs style configuration is not
|
|
recommended. It is fine to use top-level definitions to organize your
|
|
xmonad.hs, but wherever possible it is better to leave out settings that
|
|
simply duplicate 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 $ def
|
|
> { 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 config archive at
|
|
<http://haskell.org/haskellwiki/Xmonad/Config_archive>)
|
|
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 using an xmonad
|
|
flag:
|
|
|
|
> $ xmonad --recompile
|
|
> $
|
|
|
|
If there is no output, your xmonad.hs has no errors. If there are errors, they
|
|
will be printed to the console. Patch them up and try again.
|
|
|
|
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. (This assumes that you have the
|
|
\'xmessage\' utility installed; you probably do.)
|
|
|
|
-}
|
|
|
|
{- $load
|
|
#Loading_your_configuration#
|
|
|
|
To get xmonad to use your new settings, type @mod-q@. (Remember, the
|
|
mod key is \'alt\' by default, but you can configure it to be
|
|
something else, such as your Windows key if you have one.) 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 the @$PATH@ in the environment from which xmonad
|
|
is started.
|
|
|
|
-}
|
|
|