From 0ef8024d23fcb087d94c20a87f6d357de22f8b06 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 7 Oct 2018 06:52:54 -1000 Subject: [PATCH] site: download: more cleanups, add cabal install command [ci skip] --- site/download.md | 200 ++++++++++++++++++++++++++--------------------- 1 file changed, 112 insertions(+), 88 deletions(-) diff --git a/site/download.md b/site/download.md index 47010a6f9..c47fac783 100644 --- a/site/download.md +++ b/site/download.md @@ -48,6 +48,7 @@ Binaries or system packages are quickest to install, but they can be outdated or | Windows | Developer binaries: **[1.10](https://ci.appveyor.com/api/buildjobs/5n63x22wvd4j24ee/artifacts/hledger.zip)**
[no hledger-ui](https://github.com/jtdaugherty/vty/pull/1#issuecomment-297143444),[doesn't work on old windows ?](https://github.com/simonmichael/hledger/issues/774),[many files in PATH causing hangs](https://github.com/simonmichael/hledger/issues/791) | 1.10 |   | | Arch Linux | **`pacman -S hledger`** | 1.11 +| CentOS | ? | | Debian | **`sudo apt install hledger hledger-ui hledger-web`** | 1.0.1 (Stable), 1.5 (Testing), 1.10 (Unstable) | Fedora | **`sudo dnf install hledger`** | 1.2 (27), 1.4 (28), 1.5 (Rawhide) | Gentoo | **`sudo layman -a haskell && sudo emerge hledger hledger-ui hledger-web`** | 1.11 @@ -67,22 +68,43 @@ Binaries or system packages are quickest to install, but they can be outdated or ## b. Build the latest release -Good choice! You'll get the latest features mentioned in the [release notes](release-notes.html). -Below are three ways to build the latest release, in order of preference. +Good choice! You'll get the latest features and fixes mentioned in the [release notes](release-notes.html), +and you'll be in a good position to give feedback and get support. -Note, building all hledger tools for the first time could take as much -as an hour, 1G of free memory, and 1G of disk space. -(We're not bloated; we just sit atop a lot of fine Haskell engineering!) -You can kill and restart it without losing progress, and subsequent builds will be much faster. -Also, here are some known build issues and workarounds:\ - -[arch: advice from Arch wiki](https://wiki.archlinux.org/index.php/Haskell)\ -[arch: No information found for ghc-8.4.2](https://github.com/commercialhaskell/stack/issues/3984)\ - -[freebsd 12: no cabal file found](https://github.com/simonmichael/hledger/issues/709)\ -[openbsd 6: exec permission denied](https://deftly.net/posts/2017-10-12-using-cabal-on-openbsd.html)\ -[openbsd: how to get stack](https://github.com/commercialhaskell/stack/issues/2822#issuecomment-318892816)\ - +Below are three ways to build the latest release, in order of preference. +Here are some tips, just in case you need them: + +- Building all of hledger for the first time could take as much as an + hour, 1-2G of free memory, and 1-2G of disk space. (We make use of + a lot of fine Haskell software.) You can kill and restart the + build without losing progress, and future builds will be much + faster. + +- If building fails with link errors (eg: "/bin/ld.gold: error: cannot find -ltinfo"), + you might need to install some extra system packages and try again. + Check the list below, or do a web search for the error message to find the required package + (and please send updates for this list): + + | + |-----------------|------------------------------------------------------------------- + | CentOS: | **`sudo yum install -y libstdc++-devel ncurses-devel zlib-devel`** + | Debian, Ubuntu: | **`sudo apt install -y libtinfo-dev`** + | Fedora, RHEL: | **`sudo dnf install -y gmp-devel ncurses-devel`** + +- Here are some known build issues and workarounds on certain platforms: + + + [arch: advice from Arch wiki](https://wiki.archlinux.org/index.php/Haskell)\ + [arch: No information found for ghc-8.4.2](https://github.com/commercialhaskell/stack/issues/3984)\ + + [freebsd 12: no cabal file found](https://github.com/simonmichael/hledger/issues/709)\ + [openbsd 6: exec permission denied](https://deftly.net/posts/2017-10-12-using-cabal-on-openbsd.html)\ + [openbsd: how to get stack](https://github.com/commercialhaskell/stack/issues/2822#issuecomment-318892816)\ + [windows: hledger-ui is not available](https://github.com/jtdaugherty/vty/pull/1#issuecomment-297143444)\ + + + +
@@ -92,92 +114,92 @@ On systems with bash installed (mac, linux, unix-like windows..), if you don't already have stack or cabal, or if you are having trouble with them, [hledger-install](https://github.com/simonmichael/hledger/tree/master/hledger-install) is an easy and reliable way to get the latest hledger. -It automates the install process using stack or cabal, avoiding common pitfalls. +It automates the install process using stack or cabal, avoiding common pitfalls: **`curl -s https://raw.githubusercontent.com/simonmichael/hledger/master/hledger-install/hledger-install.sh > hledger-install.sh`**\ **`less hledger-install.sh`** *# satisfy yourself that the script is safe*\ **`bash hledger-install.sh`** -#### Link errors ? - -If you see link errors (like "/bin/ld.gold: error: cannot find -ltinfo"), -you might need to install some extra system packages, such as the below, and try again. -Please do a web search for the error and send corrections for this list: - - | - |-----------------|------------------------------------------------------- - | Centos: | **`sudo yum install -y libstdc++-devel ncurses-devel zlib-devel`** *# [?](https://github.com/simonmichael/hledger/issues/715)* - | Debian, Ubuntu: | **`sudo apt install -y libtinfo-dev`** *# ?* - | Fedora, RHEL: | **`sudo dnf install -y gmp-devel ncurses-devel`** *# ?* - -#### Set up $PATH - -You should -[extend your \$PATH with `~/.local/bin`](https://docs.haskellstack.org/en/stable/install_and_upgrade/#path) (for stack) -and/or `~/.cabal/bin` (for cabal). -Eg, if you use bash: - -**`echo "export PATH=~/.local/bin:~/.cabal/bin:$PATH" >> ~/.bashrc && source ~/.bashrc`** - -#### Test - -Now you should be able to run the hledger tools and see the expected versions. Eg: -```shell -$ hledger --version -hledger 1.11 -$ hledger-ui --version -hledger-ui 1.11 -$ hledger web --version -hledger-web 1.11 -$ hledger iadd --version -This is hledger-iadd version 1.3.6 -``` - -#### Need help ? - -If you are having trouble, please capture a debug log and send it to me via -[paste](http://paste.hledger.org) & [IRC](http://irc.hledger.org), -the [issue tracker](http://bugs.hledger.org), -or [email](docs.html#helpfeedback): - - **`bash -x hledger-install.sh 2>&1 | tee hledger-install.log`** - ### b2. with stack -[`stack`](http://haskell-lang.org/get-started) is the more reliable of the two Haskell build tools for new users. -Here's how to use it directly: +[`stack`](http://haskell-lang.org/get-started) is the more reliable of Haskell's two build tools, for new users. +You must use stack 1.7.1 or newer; the latest release is best. +On Windows, the 64-bit version of stack is [preferred](https://github.com/simonmichael/hledger/issues/275#issuecomment-123834252). +The following command installs the main hledger packages; +you can save some time by omitting hledger-ui, hledger-web and/or hledger-api (optional user interfaces). +On Windows, hledger-ui is not available. +To estimate the build time, add `--dry-run`: -- Use stack 1.7.1 or newer. The latest release is best. - On Windows, the 64-bit version of stack is [preferred](https://github.com/simonmichael/hledger/issues/275#issuecomment-123834252). + **`stack install --resolver=lts-12 cassava-megaparsec-1.0.0 hledger-lib-1.11 hledger-1.11 hledger-ui-1.11 hledger-web-1.11 hledger-api-1.11`**\ + +Other [add-ons](/hledger.html#third-party-add-ons) +like +[hledger-diff](http://hackage.haskell.org/package/hledger-diff), +[hledger-iadd](http://hackage.haskell.org/package/hledger-iadd), +or [hledger-interest](http://hackage.haskell.org/package/hledger-interest) +can be installed similarly: + + **`stack install --resolver=lts-12 cassava-megaparsec-1.0.0 hledger-lib-1.11 hledger-1.11 hledger-ui-1.11 hledger-diff-0.2.0.14 hledger-iadd-1.3.6 hledger-interest-1.5.2`**\ + +If you have trouble, please send me a copy/paste of the output, +including the commands you typed, at least up to the first error, +via +[paste](http://paste.hledger.org) & [IRC](http://irc.hledger.org), +or the [issue tracker](http://bugs.hledger.org), +or [email](docs.html#helpfeedback). -- **`stack install --resolver=lts-12 cassava-megaparsec-1.0.0 hledger-lib-1.11 hledger-1.11 hledger-ui-1.11 hledger-web-1.11 hledger-api-1.11`**\ - This installs the main hledger packages from [Stackage](https://www.stackage.org) and/or [Hackage](http://hackage.haskell.org). - To estimate the build time, add `--dry-run`. - You can save some time by omitting hledger-ui, hledger-web and/or hledger-api. - You can kill and restart this without losing progress. - ([windows: hledger-ui is not available](https://github.com/jtdaugherty/vty/pull/1#issuecomment-297143444)) -- As above: **[If you see link errors..](#link-errors)**, **[Set up \$PATH](#set-up-path)**, and **[Test](#test)** ### b3. with cabal -[cabal](https://www.haskell.org/cabal/) is the other Haskell build tool. If you're a cabal expert, feel free to use it in the usual way, eg: +[cabal](https://www.haskell.org/cabal/) is the other Haskell build tool. If you're a cabal expert, use it in the usual way, eg: -- **`cabal update && cabal install hledger-1.11 [hledger-ui-1.11] [hledger-web-1.11] [hledger-api-1.11]`** + **`cabal update`**\ + **`cabal install hledger-1.11 hledger-ui-1.11 hledger-web-1.11 hledger-api-1.11`**\ -- **[If you see link errors..](#link-errors)**, **[Set up \$PATH](#set-up-path)**, and **[Test](#test)**, as above. +
+ +#### Set up PATH + +After installation, make sure the install directory is in your \$PATH, preferably near the start. +You will probably see a warning or informational message about this. +The install directory is: + +| | on non-Windows systems | on Windows +|--------------------|------------------------|------------------------------------------ +| If stack was used | `$HOME/.local/bin` | `%APPDATA%\local\bin` (eg `C:\Users\Joe\AppData\Roaming\local\bin`) +| If cabal was used | `$HOME/.cabal/bin` | `%APPDATA%\cabal\bin` + +So eg if you use bash, this would take care of it: + + **`echo "export PATH=~/.local/bin:~/.cabal/bin:$PATH" >> ~/.bashrc && source ~/.bashrc`** \ -Additional [add-on commands](/hledger.html#third-party-add-ons) -such as -[hledger-diff](http://hackage.haskell.org/package/hledger-diff), -[hledger-iadd](http://hackage.haskell.org/package/hledger-iadd), -or [hledger-interest](http://hackage.haskell.org/package/hledger-interest) -can be installed similarly using stack or cabal. + +#### Test the installation + +You should now be able to run the hledger tools (whichever ones you installed) and see the expected versions: + + `$`**`hledger --version`**\ + `hledger 1.11`\ + `$`**`hledger-ui --version`**\ + `hledger-ui 1.11`\ + `$`**`hledger web --version`**\ + `hledger-web 1.11`\ + `$`**`hledger iadd --version`**\ + `This is hledger-iadd version 1.3.6`\ + +And you can check that the unit tests pass (just for fun): + + `$`**`hledger test`**\ + `...`\ + `✅ 176 tests passed, no failures! 👍 🎉`\ + + @@ -185,14 +207,16 @@ can be installed similarly using stack or cabal. Also a good choice. Our master branch is stable enough for daily use, and includes the [latest improvements](https://github.com/simonmichael/hledger/commits/master). +You'll need [git](https://en.wikipedia.org/wiki/Git) and +[`stack`](http://haskell-lang.org/get-started) or [cabal](https://www.haskell.org/cabal/). +Eg, this will build and install all of the main hledger tools using stack: -1. **Install [git](https://en.wikipedia.org/wiki/Git) and [`stack`](#b2)** -2. **`git clone https://github.com/simonmichael/hledger`** -3. **`cd hledger`** -4. **`stack install [hledger]`** *# build all (or, just the command line UI)* -5. **[If you see link errors..](#link-errors)** -6. **[Set up \$PATH](#set-up-path)** -7. **[Test](#test)** - (Development versions will have a .99 suffix, 1.10.99 means 1.11-dev) + **`git clone https://github.com/simonmichael/hledger`**\ + **`cd hledger`**\ + **`stack install`**\ cabal users may find the `cabal-install.sh` or `cabal.project` files useful. + +See the troubleshooting, PATH, and test tips [above](#b). +Note development builds will have a .99 suffix (1.11.99 means "1.12-dev"). +