11 KiB
- toc
Installation Guide
How to install
hledger works on GNU/linux, mac and windows. Here are several ways to install it:
a. With your system package manager
If you have a system package manager that includes hledger, this will be the quickest and easiest way to install, if you don't need the very latest version. These are listed on Download.
b. Download binaries from hledger.org
Ready-to-run binaries for GNU/Linux, Mac OSX, and Microsoft Windows are provided on a donation basis (Download). These are simple compressed executables (not installers), so after downloading you may need to decompress, adjust permissions, and rename the file. Eg:
$ gunzip hledger-web-0.18.2-mac-x86_64.gz
$ chmod +x hledger-web-0.18.2-mac-x86_64
$ mv hledger-web-0.18.2-mac-x86_64 /usr/local/bin/hledger-web
$ /usr/local/bin/hledger-web --version
c. Build released source from Hackage
You can download and build the latest release yourself using cabal, the standard installer for Haskell software. This is the most common way to install hledger, but not always the easiest; use the troubleshooting tips below if needed.
Ensure you have GHC or the Haskell Platform installed. Last time we checked, hledger requires GHC 7.2 or greater, and hledger-web requires GHC 7.4 or greater. But using the current or previous major GHC version will very likely be easiest.
Also note that some Haskell packages depend on C packages, and cabal currently isn't able to install or identify those for you. A common issue is not having all the ncurses C libraries installed. A quick way to ensure you have all required C libs is to install hledger with your system package manager before installing the latest version with cabal.
Then install the hledger command-line tool:
$ cabal update
$ cabal install hledger [--dry-run]
$ hledger --version
You should see the proper version reported. If you get "could not resolve dependencies", "hledger not found", or any other problem, see troubleshooting. Also note, to use non-ascii characters like £ in your data, you might need to configure a suitable locale.
Installing hledger-web
To also install the web interface, in theory just do:
$ cabal install hledger-web
In practice, this is a real beast to keep working, so as of 2014/4/17 it's best to do it this way:
$ cabal sandbox init # start with a clean cabal package db, requires cabal 1.18
$ cabal update
$ cabal install -j alex happy # update to alex 3.1 and happy 1.19
$ cabal install -j hledger-web # don't cabal install hledger first
This installs hledger and hledger-web. hledger-web will appear as the web command in hledger's commands list.
There are other start#add-on-commands, hopefully compatible with the current hledger release and your platform.
d. Build latest source from git
To download and build the latest development version of hledger, ensure you have git installed, then:
$ git clone http://github.com/simonmichael/hledger.git
$ cd hledger
$ cabal update
$ [optional: cabal sandbox init]
$ cabal install ./hledger-lib ./hledger [./hledger-web]
The same notes above about requirements and checking your installation apply. Note this time we mention cabal sandbox, a feature of cabal 1.18+ which can be used to reduce package dependency problems; it can be used when installing from Hackage as well.
Troubleshooting
There are a lot of ways things can go wrong, especially if you are building from source. Here are some known issues and things to try. Please also seek support from the IRC channel, mail list or bug tracker.
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.
hledger not found ?
If cabal install succeeded but you get a message like "hledger not found" when you run hledger, 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
On Ubuntu 14.04:
$ echo 'export PATH=~/.cabal/bin:$PATH' >> ~/.bashrc
$ source ~/.bashrc
Test your PATH-variable with:
$ echo $PATH
hledger --version shows wrong version ?
Perhaps you have multiple versions of hledger in your PATH. Eg you installed with the system package manager (to get C libs) and then with cabal (to get the latest version), but cabal's bin directory appears too late in the PATH. Move it closer to the front.
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
(and on some platforms, 7.2.1+ can be helpful).
Do you have a new enough version of cabal ?
Avoid ancient versions, which are less capable and more confusing.
cabal --version should ideally report at least 1.16 (or if you want to
do sandboxed installs, 1.18). You may be able to upgrade it with:
$ cabal update
$ cabal install cabal-install
haskeline fails to install, requires Cabal >=1.16
Related to the above. haskeline, one of hledger's dependencies, claims to require cabal-install version 1.16+, which is a problem if, say, you are on Debian Wheezy and only have cabal-install version 0.14. You can relax haskeline's version constraint like so:
cabal unpack haskeline
cd haskeline-X.Y
(edit haskeline.cabal, comment out the `Cabal-Version: >=1.16` line)
cabal install
(resume installing hledger)
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 is an easy way.
cabal says "rejecting: system-fileio-0.3.11, 0.3.10 (conflict: blah blah blah.."
system-fileio does not yet allow text 1.x, making cabal sweat.
If your cabal is modern enough, adding --max-backjumps=10000 should help.
(more).
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 cabal sandbox, created with
cabal sandbox init. (virthualenv or cabal-dev also work). -
or (c) (easiest) erase your installed packages with ghc-pkg-reset and try again.
For more detail, see How to cabal install.
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 to see if the latest development version might have a fix.
ExitFailure 11
See
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..)
Can't load .so/.DLL for: ncursesw (/usr/lib/libncursesw.so: file too short)
(or similar): cf GHC bug #5551. Upgrade GHC to 7.2.1, or try your luck with this workaround.
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. 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
"invalid preprocessing directive" on OS X
"I'm trying to cabal install hledger-web on OS X, GHC 7.6, and getting error: invalid preprocessing directive #{mixedAmountAsHtml amt}".
Certain OS X and GHC versions do not work well together (cabal #1496, ghc #7678). There's a fix for this in hledger HEAD as of 2014/2/8 (it's not in 0.22.1). If you find more cases, please report it.
Many warnings about "missing terminating ' character" on OS X
Related to the above problem, can be ignored.
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.
error based on missing ncurses C libs on Ubuntu 14.04 trusty
The following solved my dependency-problem with ncurses (this was required even when I had installed hledger 0.22 via apt-get) sudo apt-get install libghc-hscurses-dev libghc-ncurses-dev