From 9070364b354665c85485383173204a4be416bbc0 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 31 Mar 2013 22:16:06 +0000 Subject: [PATCH] docs: split out install guide, some manual cleanups --- INSTALL.md | 152 ++++++++++++++++++++++ MANUAL.md | 347 +++++++++++++++------------------------------------ README.md | 2 +- site/DOCS.md | 10 +- 4 files changed, 262 insertions(+), 249 deletions(-) create mode 100644 INSTALL.md diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 000000000..4009254aa --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,152 @@ +--- +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. + +#. **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..) + +#. **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). + diff --git a/MANUAL.md b/MANUAL.md index c7de335b8..100f15069 100644 --- a/MANUAL.md +++ b/MANUAL.md @@ -27,52 +27,18 @@ You can use it to, eg: - track time and report by day/week/month/project - get accurate numbers for client billing and tax filing -## Installing - 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: +Otherwise, fetch and build the latest release from Hackage with cabal-install. +Eg: $ 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](#locale). - -
-If you have trouble, see [Troubleshooting](#troubleshooting). -
+ $ cabal install hledger [hledger-web] + ... + $ hledger --version + hledger 0.19.4 + +For more help with this, see the [Installation Guide](INSTALL.html). ## Basic Usage @@ -110,7 +76,7 @@ enter some transactions. Or, save this $ hledger reg desc:shop # show postings with shop in the description $ hledger activity # show transactions per day as a bar chart -## Reading data +## Data formats ### Journal files @@ -605,8 +571,43 @@ and the following kinds of rule can appear in any order: ### Timelog files -hledger can also read [timelog files](#timelog-reporting), -interpreting each logged time session as an expenditure of hours. +hledger can also read time log files. These are (a subset of) timeclock.el's +format, containing clock-in and clock-out entries like so: + + i 2009/03/31 22:21:45 projects:A + o 2009/04/01 02:00:34 + +hledger treats the clock-in description ("projects:A") as an account name, +and creates a virtual transaction (or several - one per day) with the +appropriate amount of hours. From the time log above, hledger print gives: + + 2009/03/31 * 22:21-23:59 + (projects:A) 1.6h + + 2009/04/01 * 00:00-02:00 + (projects:A) 2.0h + +Here is a +[sample.timelog](http://hub.darcs.net/simon/hledger/data/sample.timelog) to +download and some queries to try: + + hledger -f sample.timelog balance # current time balances + hledger -f sample.timelog register -p 2009/3 # sessions in march 2009 + hledger -f sample.timelog register -p weekly --depth 1 --empty # time summary by week + +To generate time logs, ie to clock in and clock out, you could: + +- use emacs and the built-in timeclock.el, or + the extended [timeclock-x.el](http://www.emacswiki.org/emacs/timeclock-x.el) + and perhaps the extras in [ledgerutils.el](http://hub.darcs.net/simon/ledgertools/ledgerutils.el) + +- at the command line, use these bash aliases: + + alias ti="echo i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" + alias to="echo o `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG" + +- or use the old `ti` and `to` scripts in the [c++ ledger 2.x repository](https://github.com/jwiegley/ledger/tree/maint/scripts). + These rely on a "timeclock" executable which I think is just the ledger 2 executable renamed. ## Commands @@ -1034,46 +1035,6 @@ With the `--depth N` option, reports will show only the uppermost accounts in the account tree, down to level N. See the [balance](#balance), [register](#register) and [chart](#chart) examples. -### Timelog reporting - -hledger can also read time log files in (a subset of) timeclock.el's -format, containing clock-in and clock-out entries like so: - - i 2009/03/31 22:21:45 projects:A - o 2009/04/01 02:00:34 - -hledger treats the clock-in description ("projects:A") as an account name, -and creates a virtual transaction (or several - one per day) with the -appropriate amount of hours. From the time log above, hledger print gives: - - 2009/03/31 * 22:21-23:59 - (projects:A) 1.6h - - 2009/04/01 * 00:00-02:00 - (projects:A) 2.0h - -Here is a -[sample.timelog](http://hub.darcs.net/simon/hledger/data/sample.timelog) to -download and some queries to try: - - hledger -f sample.timelog balance # current time balances - hledger -f sample.timelog register -p 2009/3 # sessions in march 2009 - hledger -f sample.timelog register -p weekly --depth 1 --empty # time summary by week - -To generate time logs, ie to clock in and clock out, you could: - -- use emacs and the built-in timeclock.el, or - the extended [timeclock-x.el](http://www.emacswiki.org/emacs/timeclock-x.el) - and perhaps the extras in [ledgerutils.el](http://hub.darcs.net/simon/ledgertools/ledgerutils.el) - -- at the command line, use these bash aliases: - - alias ti="echo i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" - alias to="echo o `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG" - -- or use the old `ti` and `to` scripts in the [c++ ledger 2.x repository](https://github.com/jwiegley/ledger/tree/maint/scripts). - These rely on a "timeclock" executable which I think is just the ledger 2 executable renamed. - ### Custom output formats The `--format FMT` option will customize the line format of the balance @@ -1142,6 +1103,62 @@ The default output format is `%20(total) %2(depth_spacer)%-(account)` ## Appendices +### Troubleshooting + +Here are some issues you might encounter when you run hledger: +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). + +#. **hledger installed, but running hledger says something like No command 'hledger' found** + cabal installs binaries into a special directory, which should be added + to your PATH environment variable. On unix-like systems, it is + ~/.cabal/bin. + +#. **hledger fails to parse some valid ledger files** + See [file format compatibility](#file-format-compatibility). + +#. **hledger gives "Illegal byte sequence" or "Invalid or incomplete multibyte or wide character" errors** + In order to handle non-ascii letters and symbols (like £), hledger needs + an appropriate locale. This is usually configured system-wide; you can + also configure it temporarily. The locale may need to be one that + supports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, + I'm not sure yet). + + Here's an example of setting the locale temporarily, on ubuntu gnu/linux: + + $ file my.journal + my.journal: UTF-8 Unicode text # <- the file is UTF8-encoded + $ locale -a + C + en_US.utf8 # <- a UTF8-aware locale is available + POSIX + $ LANG=en_US.utf8 hledger -f my.journal print # <- use it for this command + + Here's one way to set it permanently, there are probably better ways: + + $ echo "export LANG=en_US.UTF-8" >>~/.bash_profile + $ bash --login + + If we preferred to use eg `fr_FR.utf8`, we might have to install that first: + + $ apt-get install language-pack-fr + $ locale -a + C + en_US.utf8 + fr_BE.utf8 + fr_CA.utf8 + fr_CH.utf8 + fr_FR.utf8 + fr_LU.utf8 + POSIX + $ LANG=fr_FR.utf8 hledger -f my.journal print + + Note some platforms allow variant locale spellings, but not all (ubuntu + accepts `fr_FR.UTF8`, mac osx requires exactly `fr_FR.UTF-8`). + ### Compatibility with c++ ledger hledger mimics a subset of ledger 3.x, and adds some features of its own. @@ -1260,7 +1277,7 @@ entries, and the following c++ ledger options and commands: prices [REGEXP]... display price history for matching commodities entry DATE PAYEE AMT output a derived entry, based on the arguments -#### Other differences +#### Functionality differences - hledger recognises description and negative patterns by "desc:" and "not:" prefixes, unlike ledger 3's free-form parser @@ -1302,164 +1319,6 @@ entries, and the following c++ ledger options and commands: - hledger's [include directive](including-other-files) does not support shell glob patterns (eg `include *.journal` ), which ledger does. -### Troubleshooting - -Sorry you're here! 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). - -#### Installation issues - -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. - -#. **Running hledger says something like No command 'hledger' found** - cabal installs binaries into a special directory, which should be added - to your PATH environment variable. On unix-like systems, it is - ~/.cabal/bin. - -#. **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. - -#. **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..) - -#. **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). - -#### Usage issues - -Here are some issues you might encounter when you run hledger: - -12. **hledger fails to parse some valid ledger files** - See [file format compatibility](#file-format-compatibility). - -#. **hledger gives "Illegal byte sequence" or "Invalid or incomplete multibyte or wide character" errors** - In order to handle non-ascii letters and symbols (like £), hledger needs - an appropriate locale. This is usually configured system-wide; you can - also configure it temporarily. The locale may need to be one that - supports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, - I'm not sure yet). - - Here's an example of setting the locale temporarily, on ubuntu gnu/linux: - - $ file my.journal - my.journal: UTF-8 Unicode text # <- the file is UTF8-encoded - $ locale -a - C - en_US.utf8 # <- a UTF8-aware locale is available - POSIX - $ LANG=en_US.utf8 hledger -f my.journal print # <- use it for this command - - Here's one way to set it permanently, there are probably better ways: - - $ echo "export LANG=en_US.UTF-8" >>~/.bash_profile - $ bash --login - - If we preferred to use eg `fr_FR.utf8`, we might have to install that first: - - $ apt-get install language-pack-fr - $ locale -a - C - en_US.utf8 - fr_BE.utf8 - fr_CA.utf8 - fr_CH.utf8 - fr_FR.utf8 - fr_LU.utf8 - POSIX - $ LANG=fr_FR.utf8 hledger -f my.journal print - - Note some platforms allow variant locale spellings, but not all (ubuntu - accepts `fr_FR.UTF8`, mac osx requires exactly `fr_FR.UTF-8`). - ### Examples and recipes - Here's a bash function that will run hledger chart and display diff --git a/README.md b/README.md index 13aa0c384..e0d4ba6f3 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ suited to techies. I use it every day to: - track invoices hledger is first a command-line tool, but also provides a web interface -(try the [demo](http://demo.hledger.org)). Read the [manual](MANUAL.html) to +(try the [demo](http://demo.hledger.org)). Read the [docs](DOCS.html) to learn more, including [how we are different from ledger](FAQ.html#how-does-hledger-relate-to-ledger), and get started tracking your numbers! diff --git a/site/DOCS.md b/site/DOCS.md index faf38aaed..51f2f5804 100644 --- a/site/DOCS.md +++ b/site/DOCS.md @@ -4,19 +4,21 @@ title: hledger docs # Docs -Latest: +**Latest:** [Release Notes](NEWS.html) +[Installation Guide](INSTALL.html) + [User Manual](MANUAL.html) [Contributor Guide](DEVELOPMENT.html) [FAQ](FAQ.html) -For past releases: +**Past releases:** -[0.19 User Manual](0.19/MANUAL.html) +[0.19.x User Manual](0.19/MANUAL.html) -[0.18 User Manual](0.18/MANUAL.html) +[0.18.x User Manual](0.18/MANUAL.html)