flake.nix:

* Support comp.nix.
  * Re-order overlays and modules dependency-last for sanity.
  * Re-export `xmonad.modernise`.
NIX.md:
  * Document comp.nix.
  * Simplify example system flake, removing direct dependency on the
    xmonad flake.
  * Advise sane module ordering.
  * Include and document `modernise` workaround.
  * Clarify user-substituted `<foo>` values.
.gitignore:
  * Include nix 'result' symlink.

.gitignore

@@ -27,4 +27,6 @@ tags
 
 stack.yaml.lock
 
+# nix artifacts
+result
 flake.lock

NIX.md

@@ -16,6 +16,24 @@ pkgs: devInputs: devInputs // {
 }
 ```
 
+## Selecting a Compiler
+
+A `comp.nix` file can be used to set the compiler used for `nix build` etc. E.g.
+
+```nix
+{ compiler = "ghc924"; }
+```
+
+Note that you must `git add comp.nix`, or it will be invisible to the flake.
+
+There is also a `prefix` option (see documentation below) but it doesn't really
+work in this context, since the xmonad flakes don't see the effects of your
+system overlays. Instead try the `--override-input` flag, e.g.
+
+```sh
+$ nix develop . --override-input nixpkgs 'github:NixOS/nixpkgs/nixos-unstable'
+```
+
 ## NixOS Modules
 
 The core and contrib flakes provide NixOS configuration modules.
@@ -25,24 +43,42 @@ You can bring them into your system flake like so:
 {
   inputs = {
     nixpkgs.url = github:NixOS/nixpkgs/nixos-<version>;
-    xmonad.url = github:xmonad/xmonad;
+    # The xmonad-contrib flake depends upon and re-exports from the xmonad
+    # flake. As such, you don't need to use the latter directly. If you wish to
+    # use /only/ the xmonad flake, you should beware that the version of
+    # contrib you get from nixpkgs might not build against it.
     xmonad-contrib.url = github:xmonad/xmonad-contrib;
   };
 
-  outputs = { self, nixpkgs, xmonad, xmonad-contrib }: {
+  outputs = { self, nixpkgs, xmonad-contrib }: {
     nixosConfigurations.<hostname> = nixpkgs.lib.nixosSystem rec {
-      system = <arch>;
+      system = <system>;
+      # NixOS module composition is /not/ commutative; order matters.
+      # To avoid issues, add `xmonad-contrib.nixosModules` after your standard
+      # configuration, but before `modernise` or any module overlaying in a
+      # "prefix".
       modules = [
         ./configuration.nix
-        xmonad.nixosModule
-        xmonad-contrib.nixosModule
+        ./hardware-configuration.nix
+        <myMiscConfigModule>
+      ] ++ xmonad-contrib.nixosModules ++ [
+        # `modernise` replaces the standard xmonad module and wrapper script
+        # with those from unstable. This is currently a necessary workaround to
+        # make Mod-q recompilation work.
+        xmonad-contrib.modernise.${system}
+        <myPrefixModule>
       ];
     };
   };
 }
 ```
 
-Then you can set the provided options in your `configuration.nix` under `flake`:
+Note that `<thing>` should be replaced with a user-supplied `thing`.
+`<version>`, `<hostname>` and `<system>` are necessary, while
+` <myMiscConfigModule>` and `<myPrefixModule>` are entirely optional.
+
+Having brought in `xmonad-contrib.nixosModules`, you can then set the provided
+options in your `configuration.nix` under `flake`:
 
 ```nix
   services.xserver.windowManager.xmonad = {
@@ -59,9 +95,9 @@ Then you can set the provided options in your `configuration.nix` under `flake`:
 This will use core and contrib from git for your system xmonad, building your
 config with the compiler of your choice.
 
-With the flake enabled, the `xmonad.haskellPackages` option is not used directly,
-and is instead set by the `flake.compiler` option. When `compiler` is unset,
-the default `pkgs.haskellPackages` is used.
+With the flake enabled, the `xmonad.haskellPackages` option is not used
+directly, and is instead set by the `flake.compiler` option. When `compiler` is
+unset, the default `pkgs.haskellPackages` is used.
 
 The `prefix` option is used if you wish to select your haskell packages from
 within, e.g., unstable overlaid into `pkgs` as `pkgs.unstable`.

flake.nix

@@ -13,8 +13,11 @@
       xmonad-contrib = hself.callCabal2nix "xmonad-contrib"
         (git-ignore-nix.lib.gitignoreSource ./.) { };
     };
-    overlay = fromHOL hoverlay { };
-    overlays = xmonad.overlays ++ [ overlay ];
+    defComp = if builtins.pathExists ./comp.nix
+      then import ./comp.nix
+      else { };
+    overlay = fromHOL hoverlay defComp;
+    overlays = [ overlay (fromHOL xmonad.hoverlay defComp) ];
     nixosModule = { config, lib, ... }: with lib;
       let
         cfg = config.services.xserver.windowManager.xmonad;
@@ -24,20 +27,22 @@
           nixpkgs.overlays = [ (fromHOL hoverlay comp) ];
         };
       };
-    nixosModules = xmonad.nixosModules ++ [ nixosModule ];
+    nixosModules = [ nixosModule ] ++ xmonad.nixosModules;
   in flake-utils.lib.eachDefaultSystem (system:
   let
     pkgs = import nixpkgs { inherit system overlays; };
+    hpkg = pkgs.lib.attrsets.getAttrFromPath (hpath defComp) pkgs;
     modifyDevShell =
       if builtins.pathExists ./develop.nix
       then import ./develop.nix
       else _: x: x;
   in
   rec {
-    devShell = pkgs.haskellPackages.shellFor (modifyDevShell pkgs {
+    devShell = hpkg.shellFor (modifyDevShell pkgs {
       packages = p: [ p.xmonad-contrib ];
       nativeBuildInputs = [ pkgs.cabal-install ];
     });
-    defaultPackage = pkgs.haskellPackages.xmonad-contrib;
+    defaultPackage = hpkg.xmonad-contrib;
+    modernise = xmonad.modernise.${system};
   }) // { inherit hoverlay overlay overlays nixosModule nixosModules; } ;
 }