212 lines
9.4 KiB
Markdown
212 lines
9.4 KiB
Markdown
# Installation Guide
|
|
|
|
hledger works on GNU/linux, mac and windows.
|
|
Here are several ways to install it.
|
|
|
|
## Install 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.
|
|
|
|
Debian, Ubuntu: `apt-get install hledger [hledger-web]`
|
|
|
|
Red Hat, Fedora: `yum install hledger`
|
|
|
|
|
|
## Install binaries from hledger.org
|
|
|
|
[Ready-to-run binaries](DOWNLOAD.html) for GNU/Linux, Mac OSX, and Microsoft Windows can be downloaded from this site.
|
|
They are out of date, but you can fund new ones with a donation of any size (see the page for more).
|
|
This is probably the easiest way to install hledger on windows and mac.
|
|
|
|
The binaries do not currently include installers, so after downloading
|
|
you may need to decompress, make executable, and/or 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
|
|
|
|
## Install from hackage with cabal
|
|
|
|
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](http://hackage.haskell.org/ghc/) or
|
|
the [Haskell Platform](http://hackage.haskell.org/platform/) installed.
|
|
hledger requires GHC 7.2 or greater, and hledger-web requires GHC 7.4 or greater.
|
|
|
|
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 once with your system package manager](#install-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](#troubleshooting).
|
|
Also note, to use non-ascii characters like £ in your data, you might need to [configure a suitable locale](MANUAL.html#locale).
|
|
|
|
To also install the web interface (slightly harder), do:
|
|
|
|
$ cabal install hledger-web [--dry-run]
|
|
$ hledger-web --version
|
|
|
|
This also installs hledger if not already installed, and the hledger-web command
|
|
will also be available as hledger's `web` subcommand.
|
|
|
|
Other add-on packages are available on Hackage, although some of these are
|
|
unmaintained or work only on certain platforms:
|
|
|
|
- [hledger-chart](http://hackage.haskell.org/package/hledger-chart)
|
|
- [hledger-interest](http://hackage.haskell.org/package/hledger-interest)
|
|
- [hledger-irr](http://hackage.haskell.org/package/hledger-irr)
|
|
- [hledger-vty](http://hackage.haskell.org/package/hledger-vty)
|
|
|
|
## Install the latest development version
|
|
|
|
To download and build the latest development version of hledger, ensure you have
|
|
[git](http://git-scm.com) installed, then:
|
|
|
|
$ git clone http://github.com/simonmichael/hledger.git
|
|
$ cd hledger
|
|
$ cabal update
|
|
$ cabal install ./hledger-lib ./hledger [./hledger-web]
|
|
|
|
The same [notes above](#install-from-hackage-with-cabal) about requirements and checking your installation apply.
|
|
|
|
## 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://hledger.org/list) or
|
|
[bug tracker](http://hledger.org/bugs).
|
|
|
|
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
|
|
|
|
#. **hledger --version shows unexpected 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](#5551), 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 probably report at least 1.16 (and for sandboxed
|
|
installs, 1.18+). You may be able to upgrade it with:
|
|
|
|
$ cabal update
|
|
$ cabal install cabal-install
|
|
|
|
#. **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.
|
|
|
|
#. **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](https://groups.google.com/d/topic/hledger/FdWGTSAVzYU/discussion)).
|
|
|
|
#. **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](http://hackage.haskell.org/package/virthualenv) or
|
|
[cabal-dev](http://hackage.haskell.org/package/cabal-dev) also work).
|
|
|
|
c. or (easiest) erase your installed packages with
|
|
[ghc-pkg-reset](https://gist.github.com/1185421) and try again.
|
|
|
|
For more detail, see [How to cabal install](https://www.fpcomplete.com/user/simonmichael/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](http://github.com/simonmichael/hledger/commits) 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..)
|
|
|
|
#. **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).
|
|
|
|
#. **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).
|