153 lines
6.3 KiB
Markdown
153 lines
6.3 KiB
Markdown
---
|
|
title: hledger Installation Guide
|
|
---
|
|
|
|
# Installation Guide
|
|
|
|
hledger works on linux, mac and windows. You can fund ready-to-run
|
|
binaries of the latest release - see the [download page](DOWNLOAD.html).
|
|
|
|
Otherwise, build the latest release from Hackage using cabal-install.
|
|
Ensure you have [GHC](http://hackage.haskell.org/ghc/) 7.0 or greater or
|
|
the [Haskell Platform](http://hackage.haskell.org/platform/) installed,
|
|
then:
|
|
|
|
$ cabal update
|
|
$ cabal install hledger
|
|
|
|
To also install the web interface, do:
|
|
|
|
$ cabal install hledger-web
|
|
|
|
Then try it:
|
|
|
|
$ hledger
|
|
|
|
If you get "hledger not found" or similar, you should add cabal's bin
|
|
directory to your PATH environment variable. Eg on unix-like systems,
|
|
something like:
|
|
|
|
$ echo 'export PATH=$PATH:~/cabal/bin' >> ~/.bash_profile
|
|
$ source ~/.bash_profile
|
|
|
|
To build the latest [development version](DEVELOPMENT.html) do:
|
|
|
|
$ cabal update
|
|
$ darcs get --lazy http://hub.darcs.net/simon/hledger
|
|
$ cd hledger
|
|
$ make install (or do cabal install inside hledger-lib/, hledger/ etc.)
|
|
|
|
Some add-on packages are available on Hackage:
|
|
[hledger-vty](http://hackage.haskell.org/package/hledger-vty),
|
|
[hledger-chart](http://hackage.haskell.org/package/hledger-chart),
|
|
[hledger-interest](http://hackage.haskell.org/package/hledger-interest).
|
|
These are without an active maintainer, and/or platform-specific, so installing them may be harder.
|
|
|
|
Note: to use non-ascii characters like £, you might need to [configure a suitable locale](MANUAL.html#locale).
|
|
|
|
### Troubleshooting
|
|
|
|
There are a lot of ways things can go wrong. Here are
|
|
some known issues and things to try. Please also seek
|
|
[support](DEVELOPMENT.html#support) from the
|
|
[IRC channel](irc://irc.freenode.net/#ledger),
|
|
[mail list](http://list.hledger.org) or
|
|
[bug tracker](http://bugs.hledger.org).
|
|
|
|
Starting from the top, consider whether each of these might apply to
|
|
you. Tip: blindly reinstalling/upgrading everything in sight probably
|
|
won't work, it's better to go in small steps and understand the problem,
|
|
or get help.
|
|
|
|
#. **Did you cabal update ?**
|
|
If not, `cabal update` and try again.
|
|
|
|
#. **Do you have a new enough version of GHC ?**
|
|
Run `ghc --version`. hledger requires GHC 7.0 or greater
|
|
(on [some platforms](#5551), 7.2.1 can be helpful).
|
|
|
|
#. **Do you have a new enough version of cabal ?**
|
|
Avoid ancient versions. `cabal --version` should report at least
|
|
0.10 (and 0.14 is much better). You may be able to upgrade it with:
|
|
|
|
$ cabal update
|
|
$ cabal install cabal-install-0.14
|
|
|
|
#. **Are your installed GHC/cabal packages in good repair ?**
|
|
Run `ghc-pkg check`. If it reports problems, some of your packages have
|
|
become inconsistent, and you should fix these first.
|
|
[ghc-pkg-clean](https://gist.github.com/1185421) is an easy way.
|
|
|
|
#. <a name="cabaldeps" />**cabal can't satisfy the new dependencies due to old installed packages**
|
|
Cabal dependency failures become more likely as you install more
|
|
packages over time. If `cabal install hledger-web --dry` says it can't
|
|
satisfy dependencies, you have this problem. You can:
|
|
|
|
a. try to understand which packages to remove (with `ghc-pkg unregister`)
|
|
or which constraints to add (with `--constraint 'PKG == ...'`) to help cabal
|
|
find a solution
|
|
|
|
b. install into a fresh environment created with
|
|
[virthualenv](http://hackage.haskell.org/package/virthualenv) or
|
|
[cabal-dev](http://hackage.haskell.org/package/cabal-dev)
|
|
|
|
c. or (easiest) erase your installed packages with
|
|
[ghc-pkg-reset](https://gist.github.com/1185421) and try again.
|
|
|
|
#. **Dependency or compilation error in one of the new packages ?**
|
|
If cabal starts downloading and building packages and then terminates
|
|
with an error, look at the output carefully and identify the problem
|
|
package(s). If necessary, add `-v2` or `-v3` for more verbose
|
|
output. You can install the new packages one at a time to troubleshoot,
|
|
but remember cabal is smarter when installing all packages at once.
|
|
|
|
Often the problem is that you need to install a particular C library
|
|
using your platform's package management system. Or the dependencies
|
|
specified on a package may need updating. Or there may be a compilation
|
|
error. If you find an error in a hledger package, check the
|
|
[recent commits](http://hub.darcs.net/simon/hledger/changes) to
|
|
see if the [latest development version](#installing) might have a fix.
|
|
|
|
#. **ExitFailure 11**
|
|
See
|
|
[http://hackage.haskell.org/trac/hackage/ticket/777](http://hackage.haskell.org/trac/hackage/ticket/777).
|
|
This means that a build process has been killed, usually because it grew
|
|
too large. This is common on memory-limited VPS's and with GHC 7.4.1.
|
|
Look for some memory-hogging processes you can kill, increase your RAM,
|
|
or limit GHC's heap size by doing `cabal install ... --ghc-options='+RTS
|
|
-M400m'` (400 megabytes works well on my 1G VPS, adjust up or down..)
|
|
|
|
#. <a name="5551" />**Can't load .so/.DLL for: ncursesw (/usr/lib/libncursesw.so: file too short)**
|
|
(or similar): cf [GHC bug #5551](http://hackage.haskell.org/trac/ghc/ticket/5551).
|
|
Upgrade GHC to 7.2.1, or try your luck with [this workaround](http://eclipsefp.github.com/faq.html).
|
|
|
|
#. <a name="iconv" />**Undefined iconv symbols on OS X**
|
|
This kind of error:
|
|
|
|
Linking dist/build/hledger/hledger ...
|
|
Undefined symbols:
|
|
"_iconv_close", referenced from:
|
|
_hs_iconv_close in libHSbase-4.2.0.2.a(iconv.o)
|
|
"_iconv", referenced from:
|
|
_hs_iconv in libHSbase-4.2.0.2.a(iconv.o)
|
|
"_iconv_open", referenced from:
|
|
_hs_iconv_open in libHSbase-4.2.0.2.a(iconv.o)
|
|
|
|
probably means you are on a mac with macports libraries installed, cf
|
|
[http://hackage.haskell.org/trac/ghc/ticket/4068](http://hackage.haskell.org/trac/ghc/ticket/4068).
|
|
To work around temporarily, add this --extra-lib-dirs flag:
|
|
|
|
$ cabal install hledger --extra-lib-dirs=/usr/lib
|
|
|
|
or permanently, add this to ~/.cabal/config:
|
|
|
|
extra-lib-dirs: /usr/lib
|
|
|
|
#. **hledger-vty requires curses-related libraries**
|
|
On Ubuntu, eg, you'll need the `libncurses5-dev` package. On Windows,
|
|
these are not available (unless perhaps via Cygwin.)
|
|
|
|
#. **hledger-chart requires GTK-related libraries**
|
|
On Ubuntu, eg, install the `libghc6-gtk-dev` package. See also [Gtk2Hs installation notes](http://code.haskell.org/gtk2hs/INSTALL).
|
|
|