slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: developer guide: update the setup docs

Browse Source
This commit is contained in:
Simon Michael 2015-05-16 07:23:30 -07:00
parent 9728206f4a
commit 4ed6ce3442
1 changed files with 45 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
doc/developer-guide.md
View File

@ -344,39 +344,62 @@ and the default view given by [bugs.hledger.org](http://bugs.hledger.org) exclud
### Set up for development ### Set up for development
1. get an up-to-date [ghc](http://haskell.org/ghc), at least 7.0 and preferably 7.6 1. Get [GHC](https://www.haskell.org/ghc/) and [cabal-install](http://hackage.haskell.org/package/cabal-install) installed.
2. there's probably no need to install the [haskell platform](http://haskell.org/platform) now, but you could I recommend the [stackage.org install guide](http://www.stackage.org/install).
3. it's probably worth getting the latest and best cabal: `cabal update; cabal install cabal-install` You can see which GHC versions are officially supported in the `tested-with` field in
4. ensure you have [git](http://git-scm.com) installed [hledger.cabal](http://hackage.haskell.org/package/hledger/hledger.cabal)
5. the hledger Makefile assumes GNU Make, so on some platforms you may need to spell "make" as "gmake" and
6. get the hledger repo: [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 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 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 You'll also want a comfortable code editor, preferably with Haskell support.
executables, so ghc-pkg unregister those afterwards if you don't want (I use emacs + [haskell-mode](https://github.com/haskell/haskell-mode),
that. 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 make bin/hledgerdev
This is usually quicker and simpler than fiddling with multiple cabal packages during development. This builds hledger (and hledger-lib) with GHC directly, without using cabal,
Note this executable will not be as optimised as the normal cabal build, and has the "dev" suffix and as quickly as possible, without optimizations (the "dev" suffix is a reminder of this).
as 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 ### Get your changes accepted