haskell-nix-overlay
===================

status: most packages can be installed easily. If something doesn't work drop
me a message, please

See TODO: eventually design will change

GOAL
====
  make all hackage packages availible to the nix repository manager (-> http://nixos.org).

REQUIREMENTS:
=============
nixpkgs: nix2/marc-next branch which adds arbitrary strings as names patch. It allows
{
  "foo-2.1" = { .. };
}

which is used often.
It also adds overlay features so that you can hook haskell packages into main
nixpkgs easily.

HIGH LEVEL DESIGN OVERVIEW
==========================
What's happening at all?

  1) 00-index.tar -> (hack-nix) -> hackage/hack-nix-db.nix (representation of
    optionally patched .cabal files)
    patches are taken from patches/*

  2) run a nix command (eg nix-build -A hackNix) or hack-nix --build-env in
    project directory containing a .cabal file.
    The package pool (which mostly is made up of hackage/hack-nix-db.nix)
    is used to find a dependency graph satisfying all dependency constraints
    (paying attention to os, flags, library vs executable dependencies ...)

    Because the solver uses brute force 1) only adds latest version and a
    set of manually selected packages to the pool.

    hack-nix --build-env

    Of course the information found in .cabal files is not enough. Eg
    regex-pcre requires the pcre C library. Those additional dependencies
    and flag settings are merged in default.nix.

    If you use hack-nix --build-env you use a .hack-nix-cabal-config setting
      - the ghc version to be used
      - cabal flags
      - adding custom packages to the pool of packages which are used when
        dependencies are resolved

hack-nix also provides some flags which are used by nix-repository-manager to add regions
of code to .nix file which contain cabal representations & source snapshots of dacrs,git,...
versions of packages.

Also see "Alternative designs"

HOWTO
=====

a) optional: update hack-nix-db.nix file
  Get and compile hack-nix. (http://github.com/MarcWeber/hack-nix)
  # create the configuration file
  hack-nix --write-config

  # make target-file point to $THIS_REPO/hackage/hack-nix-db.nix:
  $EDITOR .hack-nix

  # Run hack-nix without any arguments. I recommend symlinking nix-cache so that
  # we can share it. Also hack-nix sometimes looses its contents so make a copy
  # once in a while!
  ln -s hackage/nix-cache ~/.hack-nix/nix-cache
  # remove hackage index so that it'll be refetched:
  grep -i '/000/d' ~/.hack-nix/nix-cache
  hack-nix

  All (new) sources will be fetched to calculate hashes .. Depending no how
  many packages have to be fetched this will take a while.
  The result is hackage/hack-nix-db.nix (which is also shipping with this repo)

b) compile example package:
  nix-build -A darcs -f THIS_REPO/default.nix


HOWTO build a .cabal project
============================

  hack-nix supports building environments.

  cd into a folder containing a cabal project

  # write a config file containing cabal flag assignments:
  hack-nix --write-hack-nix-cabal-config

  # throw away the ways you don't want to test and assign appropriate names
  $EDITOR .hack-nix-cabal-config

  # build an environment based on those flags using one of:
  hack-nix --build-env
  hack-nix --build-env-name $NAME

  # source the bash file exporting PATH and GHC_PACKAGE_PATH
  # in order to run the well known cabal commands:
  source hack-nix-env/$NAME/source-me/haskel-env # ./ will contain shorter symlinks to this complicated path
  ghc --make Setup.hs
  ./Setup configure
  ./Setup build


  You can also add dev versions of packages to the list of available
  packages quite easily:

  Create ~/.nixpkgs/config.nix:

    {pkgs, ... }: {
      hackNix.additionalPackages = [
        (import $PATH_TO_CABAL_REPO/dist/$CABAL_PROJECT_NAME.nix)
        # repeat the line above
      ];
    }

  The $CABAL_PROJECT_NAME.nix file is created by running
    hack-nix --to-nix


Alternative designs
===================
- cabal? Why not use it?
  1) Because you can't nixos-rebuild make use hackage packages then.
  2) Because cabal didn't support gtk in the past and still doesn't support the
      older gtk2hs meta package
  3) because you can't patch .cabal files on the fly. It should not be
     necessary - but it often is. It doesn't pay off to contact maintainers
     asking them to drop a "< X.Y" constraint on a package just because you
     want to install it *now*.
  4) cabal does'nt generate tags
  5) Does cabal create a special directory containing sources of all dependencies
     which you can browse?
  6) atomic updates, per package "environments" and rollbacks are not supported
     by cabal. Thus if an update fails you've got a problem or you can start
     playing back your backups (nogo).
  7) parallel compilation of packages. While cabal runs Setup.hs within the
     same process if possible which is much faster than compiling Setup.hs
     and starting it nix-env will naturally provide -j X features building
     packages in parallel even distributed across systems.

- what about making cabal create .nix files?
  Why a solver in Nix? Why not cabal create-nix-files-for-package XY ?
  Because I don't want to create specific .nix files for each package.
  There are too many combinations. Its much better to define the pool and make
  Nix magically find dependencies.
  Its also a lot faster because create-nix-files-for-package XY has to start
  calculating sha256 hashes for sources etc. AFAIK it doesn't allow patching
  cabals either (which could be fixed)

- doing dependency analysis manually?
  See haskell-packages.nix in nixpkgs. I don't have that much time to spend on
  each update again and again. Do things once and be done.
  I have to automate what can be automated.

FUTURE
======
SAT solvers should be used.

DEBUGGING
=========
Resolving can be debugged by setting debugS to true which is default
for hack-nix --build-env. For exeByName export HACK_NIX_DEBUG=1.

BUGS
====
The code is complicated and close to unmaintainable?
Maybe yes. But it works. I support it. Its not your problem :)
The solution would be adding a type system to Nix, use a sat solver, ...
If you have time to do it :)

Maybe hackage/hack-nix-db.nix should be put into a different repo because the file changes more often than the code .. This was done for nixpkgs-ruby-overlay and nixpkgs-python-overlay ..



TODO
====
* See TODO of hack-nix haskell executable. Eventually design will change

* rewrite so that preparing the package (sorting by name/version) is done once
  only. This would speed up everything *a lot* because resolving deps for
  happy, alex, would be much faster.

*
  honor: condTestSuites is ignored right now. Probably it can be merged with
  executable deps except the buildable and enable flags!

* tidy up code. Optimise for speed !
* think about how packages defined in here can be reused in nixpgks
* maybe create nix channel (rename overlay to channel)