slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: split out install guide, some manual cleanups

Browse Source
This commit is contained in:
Simon Michael 2013-03-31 22:16:06 +00:00
parent 853c07bf9e
commit 9070364b35
4 changed files with 262 additions and 249 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

152
INSTALL.md Normal file
View File

@ -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.
#. <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).

345
MANUAL.md
View File

@ -27,52 +27,18 @@ You can use it to, eg:
- track time and report by day/week/month/project - track time and report by day/week/month/project
- get accurate numbers for client billing and tax filing - get accurate numbers for client billing and tax filing
## Installing
hledger works on linux, mac and windows. You can fund ready-to-run hledger works on linux, mac and windows. You can fund ready-to-run
binaries of the latest release - see the [download page](DOWNLOAD.html). binaries of the latest release - see the [download page](DOWNLOAD.html).
Otherwise, fetch and build the latest release from Hackage with cabal-install.
Otherwise, build the latest release from Hackage using cabal-install. Eg:
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 update
$ cabal install hledger $ cabal install hledger [hledger-web]
...
$ hledger --version
hledger 0.19.4
To also install the web interface, do: For more help with this, see the [Installation Guide](INSTALL.html).
$ 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).
<div class="alert">
If you have trouble, see [Troubleshooting](#troubleshooting).
</div>
## Basic Usage ## Basic Usage
@ -110,7 +76,7 @@ enter some transactions. Or, save this
$ hledger reg desc:shop # show postings with shop in the description $ hledger reg desc:shop # show postings with shop in the description
$ hledger activity # show transactions per day as a bar chart $ hledger activity # show transactions per day as a bar chart
## Reading data ## Data formats
### Journal files ### Journal files
@ -605,8 +571,43 @@ and the following kinds of rule can appear in any order:
### Timelog files ### Timelog files
hledger can also read [timelog files](#timelog-reporting), hledger can also read time log files. These are (a subset of) timeclock.el's
interpreting each logged time session as an expenditure of hours. 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 ## 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), in the account tree, down to level N. See the [balance](#balance),
[register](#register) and [chart](#chart) examples. [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 ### Custom output formats
The `--format FMT` option will customize the line format of the balance 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 ## 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).
#. <a name="locale" />**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 ### Compatibility with c++ ledger
hledger mimics a subset of ledger 3.x, and adds some features of its own. 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 prices [REGEXP]... display price history for matching commodities
entry DATE PAYEE AMT output a derived entry, based on the arguments entry DATE PAYEE AMT output a derived entry, based on the arguments
#### Other differences #### Functionality differences
- hledger recognises description and negative patterns by "desc:" - hledger recognises description and negative patterns by "desc:"
and "not:" prefixes, unlike ledger 3's free-form parser 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 - hledger's [include directive](including-other-files) does not support
shell glob patterns (eg `include *.journal` ), which ledger does. 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.
#. <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).
#### 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).
#. <a name="locale" />**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 ### Examples and recipes
- Here's a bash function that will run hledger chart and display - Here's a bash function that will run hledger chart and display

2
README.md
View File

@ -20,7 +20,7 @@ suited to techies. I use it every day to:
- track invoices - track invoices
hledger is first a command-line tool, but also provides a web interface 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 learn more, including
[how we are different from ledger](FAQ.html#how-does-hledger-relate-to-ledger), [how we are different from ledger](FAQ.html#how-does-hledger-relate-to-ledger),
and get started tracking your numbers! and get started tracking your numbers!

10
site/DOCS.md
View File

@ -4,19 +4,21 @@ title: hledger docs
# Docs # Docs
Latest: **Latest:**
[Release Notes](NEWS.html) [Release Notes](NEWS.html)
[Installation Guide](INSTALL.html)
[User Manual](MANUAL.html) [User Manual](MANUAL.html)
[Contributor Guide](DEVELOPMENT.html) [Contributor Guide](DEVELOPMENT.html)
[FAQ](FAQ.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)