@@ -431,51 +431,71 @@ following snippet in your `~/.nixpkgs/config.nix` file:
431431 };
432432 }
433433
434−## How to override a cabal package version for a specific compiler version
434+## How to override package versions in a compiler-specific package set
435435
436−Say the default version of ghc-events is 0.4.4.0 and does not work with ghc784
437−We can override this by
436+Nixpkgs provides the latest version of
437+[`ghc-events`](http://hackage.haskell.org/package/ghc-events), which is 0.4.4.0
438+at the time of this writing. This is fine for users of GHC 7.10.x, but GHC
439+7.8.4 cannot compile that binary. Now, one way to solve that problem is to
440+register an older version of `ghc-events` in the 7.8.x-specific package set.
441+The first step is to generate Nix build instructions with `cabal2nix`:
438442
439− $ mkdir .nixpkgs/haskell/ && cd .nixpkgs/haskell/
440− $ cabal get ghc-events-0.4.3.0 && cd ghc-events-0.4.3.0 && cabal2nix --no-check ghc-events.cabal > default.nix
443+ $ cabal2nix cabal://ghc-events-0.4.3.0 >~/.nixpkgs/ghc-events-0.4.3.0.nix
441444
442−in the config.nix we then override the packages
445+Then add the override in `~/.nixpkgs/config.nix`:
443446
444− #overrides for every compiler versions
445− myHaskellPackages = hp : hp.override {
446− overrides = self: super: with pkgs.haskell.lib; {
447− ...
447+ {
448+ packageOverrides = super: let self = super.pkgs; in
449+ {
450+ haskell = super.haskell // {
451+ packages = super.haskell.packages // {
452+ ghc784 = super.haskell.packages.ghc784.override {
453+ overrides = self: super: {
454+ ghc-events = self.callPackage ./ghc-events-0.4.3.0.nix {};
455+ };
456+ };
448457 };
458+ };
449459 };
450− myHaskellPackages784 = hp : hp.override {
451− overrides = self: super: with pkgs.haskell.lib; {
452− ...
453− ghc-events = dontCheck (pkgs.haskell.packages.ghc784.callPackage ./haskell/ghc-events-0.4.3.0 {});
454− ...
455− };
460+ }
461+
462+This code is a little crazy, no doubt, but it's necessary because the intuitive
463+version
464+
465+ haskell.packages.ghc784 = super.haskell.packages.ghc784.override {
466+ overrides = self: super: {
467+ ghc-events = self.callPackage ./ghc-events-0.4.3.0.nix {};
456468 };
457− haskellngPackages = myHaskellPackages super.haskellPackages;
458− haskell784Packages = myHaskellPackages784(myHaskellPackages super.haskell.packages.ghc784);
469+ };
459470
460−We can then use those packages to build environments which will pick up the desired version
471+doesn't do what we want it to: that code replaces the `haskell` package set in
472+Nixpkgs with one that contains only one entry,`packages`, which contains only
473+one entry `ghc784`. This override loses the `haskell.compiler` set, and it
474+loses the `haskell.packages.ghcXYZ` sets for all compilers but GHC 7.8.4. To
475+avoid that problem, we have to perform the convoluted little dance from above,
476+iterating over each step in hierarchy.
461477
462− hs784 = haskell784Packages.ghcWithPackages (p: with p;
463− [
464− ghc-events
465− ...
466− ]
467− );
478+Once it's accomplished, however, we can install a variant of `ghc-events`
479+that's compiled with GHC 7.8.4:
468480
469− hs7101 = haskellngPackages.ghcWithPackages (p: with p;
470− [
471− ghc-events
472− ...
473− ]
481+ nix-env -f "<nixpkgs>" -iA haskell.packages.ghc784.ghc-events
474482
475−as can be verified by
483+Unfortunately, it turns out that this build fails again while executing the
484+test suite! Apparently, the release archive on Hackage is missing some data
485+files that the test suite requires, so we cannot run it. We accomplish that by
486+re-generating the Nix expression with the `--no-check` flag:
476487
477− nix-store -qR $(nix-instantiate '<nixpkgs>' -A pkgs.hs784 ) | grep ghc-events
478− nix-store -qR $(nix-instantiate '<nixpkgs>' -A pkgs.hs7101) | grep ghc-events
488+ $ cabal2nix --no-check cabal://ghc-events-0.4.3.0 >~/.nixpkgs/ghc-events-0.4.3.0.nix
489+
490+Now the builds succeeds.
491+
492+Of course, in the concrete example of `ghc-events` this whole exercise is not
493+an ideal solution, because `ghc-events` can analyze the output emitted by any
494+version of GHC later than 6.12 regardless of the compiler version that was used
495+to build the `ghc-events' executable, so strictly speaking there's no reason to
496+prefer one built with GHC 7.8.x in the first place. However, for users who
497+cannot use GHC 7.10.x at all for some reason, the approach of downgrading to an
498+older version might be useful.
479499
480500## How to recover from GHC's infamous non-deterministic library ID bug
481501
@@ -502,3 +522,20 @@ command, i.e. by running:
502522 rm /nix/var/nix/binary-cache-v3.sqlite
503523 rm /nix/var/nix/manifests/*
504524 rm /nix/var/nix/channel-cache/*
525+
526+## Builds on Darwin fail with `math.h` not found
527+
528+Users of GHC on Darwin have occasionally reported that builds fail, because the
529+compiler complains about a missing include file:
530+
531+ fatal error: 'math.h' file not found
532+
533+The issue has been discussed at length in [ticket
534+#6390](https://github.com/NixOS/nixpkgs/issues/6390), and so far no good
535+solution has been proposed. As a work-around, users who run into this problem
536+can configure the environment variables
537+
538+ export NIX_CFLAGS_COMPILE="-idirafter /usr/include"
539+ export NIX_CFLAGS_LINK="-L/usr/lib"
540+
541+in their `~/.bashrc` file to avoid the compiler error.