From 4ed6ce3442b291ea149e25e073b442ec7c8e48f9 Mon Sep 17 00:00:00 2001
From: Simon Michael <simon@joyful.com>
Date: Sat, 16 May 2015 07:23:30 -0700
Subject: [PATCH] doc: developer guide: update the setup docs

---
 doc/developer-guide.md | 67 ++++++++++++++++++++++++++++--------------
 1 file changed, 45 insertions(+), 22 deletions(-)

diff --git a/doc/developer-guide.md b/doc/developer-guide.md
index 1d1dff6a9..f98d68f07 100644
--- a/doc/developer-guide.md
+++ b/doc/developer-guide.md
@@ -344,39 +344,62 @@ and the default view given by [bugs.hledger.org](http://bugs.hledger.org) exclud
 
 ### Set up for development
 
-1. get an up-to-date [ghc](http://haskell.org/ghc), at least 7.0 and preferably 7.6
-2. there's probably no need to install the [haskell platform](http://haskell.org/platform) now, but you could
-3. it's probably worth getting the latest and best cabal: `cabal update; cabal install cabal-install`
-4. ensure you have [git](http://git-scm.com) installed
-5. the hledger Makefile assumes GNU Make, so on some platforms you may need to spell "make" as "gmake"
-6. get the hledger repo:
+1. Get [GHC](https://www.haskell.org/ghc/) and [cabal-install](http://hackage.haskell.org/package/cabal-install) installed.
+   I recommend the [stackage.org install guide](http://www.stackage.org/install).
+   You can see which GHC versions are officially supported in the `tested-with` field in
+   [hledger.cabal](http://hackage.haskell.org/package/hledger/hledger.cabal)
+   and
+   [hledger-web.cabal](http://hackage.haskell.org/package/hledger-web/hledger-web.cabal).
+   Older versions may also work.
+2. Get [git](http://git-scm.com) installed.
+3. Get [GNU Make](http://www.gnu.org/software/make) installed (unless you don't care about the Makefile's conveniences).
+   On some platforms the command will be eg `gmake` instead of `make`.
+4. Get the hledger repo:
 
         git clone https://github.com/simonmichael/hledger.git
-        cd hledger
 
-7. install packages required to build hledger and add-ons, or as many of them as possible:
+5. You might want to install or upgrade some of these haskell developer tools.
+   If you're not sure, skip this step and return to it as needed.
+   Be sure the cabal bin directory where these are installed (eg ~/.cabal/bin) is in your PATH.
 
         cabal update
-        make install
+        cabal install alex happy       # if you get alex/happy-related errors when building hledger
+        cabal install haddock          # needed to build hledger API docs
+        cabal install shelltestrunner  # needed to run hledger functional tests (may need latest git version)
+        cabal install hoogle hlint     # maybe useful for searching API docs and checking code
 
-    This will also try to cabal install development builds of the hledger
-    executables, so ghc-pkg unregister those afterwards if you don't want
-    that.
+    You'll also want a comfortable code editor, preferably with Haskell support.
+    (I use emacs + [haskell-mode](https://github.com/haskell/haskell-mode),
+    or occasionally [IntelliJ IDEA](https://www.jetbrains.com/idea/download) + one of the [plugins](https://www.google.com/search?hl=en&q=intellij+plugins+haskell)).
 
-8. try building with make:
+6. Install haskell libs required by hledger:
+
+        cabal update
+        cd hledger
+        cabal sandbox init   # optional
+        make installdeps     # or cabal install --only-dep ./hledger-lib ./hledger [./hledger-web]
+
+    This will install the required dependencies from Hackage.
+    If you're new to cabal, you can expect problems at this stage.
+    The usual remedy is to ensure you start with a clean package db, eg by doing `cabal sandbox init`.
+    You can simplify and speed up this step a lot by commenting out
+    hledger-web in the `PACKAGES` list in the [Makefile](https://github.com/simonmichael/hledger/blob/master/Makefile#L41).
+
+7. Build with cabal:
+
+        make cabalbuild
+
+    (Tip: `make cabalCMD` runs `cabal CMD` in each of the hledger packages).
+
+8. Build with GHC:
 
         make bin/hledgerdev
 
-    This is usually quicker and simpler than fiddling with multiple cabal packages during development.
-    Note this executable will not be as optimised as the normal cabal build, and has the "dev" suffix
-    as a reminder of this.
+    This builds hledger (and hledger-lib) with GHC directly, without using cabal,
+    and as quickly as possible, without optimizations (the "dev" suffix is a reminder of this).
+    I use and recommend this method for development, as it crosses package boundaries and ensures you are building the latest code.
+    However it needs some files generated by cabal build, which is why we did that first.
 
-<!-- 9. try auto-building with sp: -->
-
-<!--         make auto   # or autoweb -->
-
-<!--     You'll need to follow the instructions to install `sp`. -->
-<!--     This is how I do most hledger development. It will recompile whenever you save changes to source files. -->
 
 ### Get your changes accepted