Add INSTALL.md

INSTALL.md

@@ -0,0 +1,180 @@
+# Install XMonad
+
+## Stack
+
+### Preparation
+
+We'll use the [XDG] directory specifications here, meaning our
+configuration will reside within `$XDG_CONFIG_HOME`, which is
+`~/.config` on most systems.  Let's create this directory and move to
+it:
+
+``` shell
+  $ mkdir -p ~/.config/xmonad && cd ~/.config/xmonad
+```
+
+If you already have an `xmonad.hs` configuration, you can copy it over
+now.  If not, you can use the defaults: create a file called `xmonad.hs`
+with the following content:
+
+``` haskell
+  import XMonad
+
+  main :: IO ()
+  main = xmonad def
+```
+
+### Install Stack
+
+The easiest way to get [stack] is probably via your system's package
+manager.  For example, on Debian:
+
+``` shell
+  $ apt install haskell-stack
+```
+
+If your distribution does not package stack, you can also easily install
+it via the following command (this is the recommended way to install
+stack via its [documentation][stack]):
+
+``` shell
+  $ curl -sSL https://get.haskellstack.org/ | sh
+```
+
+Yet another way would be via [ghcup]; this is similar to installers like
+`rustup`, in case you prefer that.
+
+### Create a New Project
+
+Let's create a stack project.  Since we're already in the correct
+directory (`~/.config/xmonad`), we can start by cloning the `xmonad` and
+the `xmonad-contrib` repositories:
+
+``` shell
+  $ git clone https://github.com/xmonad/xmonad
+  $ git clone https://github.com/xmonad/xmonad-contrib
+```
+
+This will give you the latest `$HEAD`; if you want you can also check
+out a tagged release, e.g.:
+
+``` shell
+  $ git clone --branch v0.16 https://github.com/xmonad/xmonad
+  $ git clone --branch v0.17 https://github.com/xmonad/xmonad-contrib
+```
+
+Starting a new stack project is as simple as running `stack init`.
+Stack should now inform you that it will use the relevant `stack` and
+`cabal` files from `xmonad` and `xmonad-contrib` to generate its
+`stack.yaml` file.  At the time of writing, this looks a little bit like
+this:
+
+```
+  $ stack init
+  Looking for .cabal or package.yaml files to use to init the project.
+  Using cabal packages:
+  - xmonad-contrib/
+  - xmonad/
+
+  Selecting the best among 19 snapshots...
+
+  * Matches https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/17/9.yaml
+
+  Selected resolver: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/17/9.yaml
+  Initialising configuration using resolver: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/17/9.yaml
+  Total number of user packages considered: 2
+  Writing configuration to file: stack.yaml
+  All done.
+```
+
+If you look into your current directory now, you should see a freshly
+generated `stack.yaml` file:
+
+```
+  $ ls
+  xmonad  xmonad-contrib  stack.yaml  xmonad.hs
+```
+
+The meat of that file (comments start with `#`, we've omitted them here)
+will look a little bit like
+
+``` yaml
+  resolver:
+    url: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/17/9.yaml
+
+  packages:
+  - xmonad
+  - xmonad-contrib
+```
+
+### Install Everything
+
+Installing things is as easy as typing `stack install`.  This will
+install the correct version of GHC, as well as build all of the required
+packages (`stack build`) and then copy the relevant executables
+(`xmonad`, in our case) to `~/.local/bin`.  Make sure to add that
+directory to your `$PATH`!
+
+If you're getting build failures while building the `X11` package it may
+be that you don't have the required C libraries installed.  Depending on
+your system, this may be `libX11-devel`, or `libxss`.
+
+### Tell XMonad How to Recompile Itself
+
+In order to tell xmonad to invoke `stack build` when we issue `xmonad
+--recompile` (bound to `M-q` by default), we need to create a so-called
+`build` file.  This is quite literally just a shell script called
+`build` in your xmonad directory (which is `~/.config/xmonad` for us)
+that tells xmonad how it should build its executable.
+
+A good starting point (this is essentially [what xmonad would do]
+without a build file, with the exception that we are invoking `stack
+ghc` instead of plain `ghc`) would be
+
+``` shell
+  #!/bin/sh
+
+  exec stack ghc --  \
+    --make xmonad.hs \
+    -i               \
+    -ilib            \
+    -fforce-recomp   \
+    -main-is main    \
+    -v0              \
+    -o "$1"
+```
+
+Don't forget to mark the file as `+x`: `chmod +x build`!
+
+And that's it!  Recompilation should work normally now, though you will
+potentially need to restart your computer, or at least the running X
+session, first.
+
+### Don't Recompile on Every Startup
+
+By default, xmonad always recompiles itself when a build script is used
+(because the build script could contain arbitrary code, so a simple
+check whether the `xmonad.hs` file changed is not enough).  If you find
+that too annoying, then you can use the `xmonad-ARCH` executable that
+`xmonad --recompile` generates instead of `xmonad` in your startup.  For
+example, instead of writing
+
+``` shell
+  exec xmonad
+```
+
+in your `~/.xinitrc`, you would write
+
+``` shell
+  exec $HOME/.local/share/xmonad/xmonad-x86_64-linux
+```
+
+The `~/.local/share` prefix is the `$XDG_DATA_DIR` directory.  Note that
+if your xmonad configuration resides within `~/.xmonad`, then the
+executable will also be within that directory and not in
+`$XDG_DATA_DIR`.
+
+[XDG]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
+[stack]: https://docs.haskellstack.org/en/stable/README/
+[ghcup]: https://www.haskell.org/ghcup/
+[what xmonad would do]: https://github.com/xmonad/xmonad/blob/master/src/XMonad/Core.hs#L657-L665

README.md

@@ -35,6 +35,8 @@ package system (e.g. on Debian or Gentoo). If at all possible, use this
 in preference to a source build, as the dependency resolution will be
 simpler.
 
+For tool-specific guides see [INSTALL.md](./INSTALL.md).
+
 We'll now walk through the complete list of toolchain dependencies.
 
   * GHC: the Glasgow Haskell Compiler