diff --git a/INSTALL.md b/INSTALL.md index 69cc8c6db..9eb8d4bb6 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -40,7 +40,15 @@ 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 currently requires GHC 7.2 or greater, and hledger-web requires GHC 7.4 or greater. +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 @@ -77,7 +85,9 @@ To download and build the latest development version of hledger, ensure you have $ cd hledger $ cabal update $ cabal install ./hledger-lib ./hledger [./hledger-web] - + +The same [notes about C libs etc.](#install-from-hackage-with-cabal) apply. + ## Troubleshooting There are a lot of ways things can go wrong. Here are @@ -92,7 +102,7 @@ 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 ?** +#. **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: @@ -100,30 +110,30 @@ or get help. $ echo 'export PATH=$PATH:~/cabal/bin' >> ~/.bash_profile $ source ~/.bash_profile -#. **Did you cabal update ?** +#. **Did you cabal update ?** If not, `cabal update` and try again. -#. **Do you have a new enough version of GHC ?** +#. **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 ?** +#. **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 ?** +#. **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. + become inconsistent, and you should fix these first. [ghc-pkg-clean](https://gist.github.com/1185421) is an easy way. -#. **cabal can't satisfy the new dependencies due to old installed packages** +#. **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 @@ -135,7 +145,7 @@ or get help. 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 ?** +#. **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 @@ -149,7 +159,7 @@ or get help. [recent commits](http://github.com/simonmichael/hledger/commits) to see if the [latest development version](#installing) might have a fix. -#. **ExitFailure 11** +#. **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 @@ -158,11 +168,11 @@ or get help. 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)** +#. **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** +#. **Undefined iconv symbols on OS X** This kind of error: Linking dist/build/hledger/hledger ... @@ -181,13 +191,12 @@ or get help. $ 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** +#. **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** +#. **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). -