diff --git a/Shake.hs b/Shake.hs index a34207144..71d2c6eb2 100755 --- a/Shake.hs +++ b/Shake.hs @@ -421,11 +421,13 @@ main = do -- Render one website page (main or wiki) as html, saved in sites/_site/. -- Wiki pages will have a heading and TOC placeholder prepended. + -- The download page will have a TOC placeholder prepended. -- All pages will have github-style wiki links hyperlinked. "site/_site//*.html" %> \out -> do let filename = takeBaseName out pagename = fileNameToPageName filename iswikipage = filename `elem` wikipagefilenames + isdownloadpage = filename == "download" isoldmanual = "site/_site/doc/" `isPrefixOf` out source | iswikipage = "wiki" filename <.> "md" @@ -433,9 +435,12 @@ main = do | otherwise = "site" filename <.> "md" template = "site/site.tmpl" siteRoot = if "site/_site/doc//*" ?== out then "../.." else "." + maybeAddToc | iswikipage = addHeading pagename . addToc + | isdownloadpage = addToc + | otherwise = id need [source, template] -- read markdown source, link any wikilinks, maybe add a heading and TOC, pipe it to pandoc, write html out - Stdin . wikiLink . (if iswikipage then addHeading pagename . addToc else id) <$> (readFile' source) >>= + Stdin . wikiLink . maybeAddToc <$> (readFile' source) >>= (cmd Shell pandoc "-" fromsrcmd "-t html" "--template" template ("--metadata=siteRoot:" ++ siteRoot) diff --git a/site/download.md b/site/download.md index 5bd4f34b0..ec0a49eea 100644 --- a/site/download.md +++ b/site/download.md @@ -1,15 +1,5 @@ # Download -Here are the ways to install hledger, organised by platform, with the usually most up-to-date methods at the top. - -( -hledger's usual release window is the first day or two of the month. -Please [send updates](index.html#helpfeedback) for -[this page](https://github.com/simonmichael/hledger/blob/master/site/download.md), -and help packagers keep packages up to date. -Click the version badges on the right for package/contact info. -) - -| | | Latest release is 1.14.2
[Release notes](release-notes.html) | +Here are some ways to install hledger - choose one that suits you. +And please do [let us know](index.html#helpfeedback) or +[update this page](https://github.com/simonmichael/hledger/blob/master/site/download.md) +if you have any trouble. + +The current hledger release is **1.14.2**; here are the [release notes](release-notes.html). + +
+
+ +## Binary packages + +These prebuilt binaries will install quickly: + +| | | |-----------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -|
**Multiplatform** |
*The first three (and occasionally the fourth) build from source, which is slower. See [Building from source](#b).* |
*This method installs:* | -| [hledger-install.sh](#b1)
*Linux, Mac, WSL*
*Requires only bash.* | **`curl -sO https://raw.githubusercontent.com/simonmichael/hledger/master/hledger-install/hledger-install.sh`**
**`less hledger-install.sh`**    *# satisfy yourself that the script is safe*
**`bash hledger-install.sh`** | Latest release | -| [cabal]
*Linux, Mac, Windows[*]* | **`cabal v2-update && cabal v2-install hledger-1.14.2 hledger-web-1.14.1 hledger-ui-1.14.2`** | Latest release | -| [stack]
*Linux, Mac, Windows[*]* | **`stack install --resolver=nightly-2019-03-21 hledger hledger-web hledger-ui`** | Latest release | -| [Nix]
*Linux, Mac* | **`nix-env -i -f https://github.com/NixOS/nixpkgs/archive/9c74e2.tar.gz -A hledger hledger-web hledger-ui`** | Latest release | +|
**Multiplatform** | |
*Packaged version:* | +| [Nix]
*Linux, Mac* | **`nix-env -i -f https://github.com/NixOS/nixpkgs/archive/9c74e2.tar.gz -A hledger hledger-web hledger-ui`** | ![](https://img.shields.io/badge/Nix_package-1.14.1-brightgreen.svg) | [Docker]
*Linux, Mac, Windows* | **`docker pull dastapov/hledger`** | [![](https://img.shields.io/badge/Docker_image-1.14.1-brightgreen.svg)](https://hub.docker.com/r/dastapov/hledger)
[more..](https://hub.docker.com/search?q=hledger&type=image&sort=updated_at&order=desc) | -| [Homebrew]
*Linux, Mac, Windows* | **`brew install hledger`** | [![Homebrew](https://repology.org/badge/version-for-repo/homebrew/hledger.svg)](https://formulae.brew.sh/formula/hledger) | -| [Wine]
*Linux, Mac, FreeBSD* | *run the Windows binary below :)* | | +| [Homebrew]
*Linux, Mac, Windows* | **`brew install hledger`** | [![](https://repology.org/badge/version-for-repo/homebrew/hledger.svg)](https://formulae.brew.sh/formula/hledger) | +| [Wine]
*Linux, Mac, FreeBSD* | *Install Wine, run the Windows binary below* | | |
**Windows** | | | -| Windows binaries | **[hledger.zip]** *from Appveyor CI* | [![](https://img.shields.io/badge/Windows_binaries-1.14.1+_20190309-brightgreen.svg)](https://ci.appveyor.com/project/simonmichael/hledger/build/artifacts) | +| Windows binaries | **[hledger.zip]** *from Appveyor CI* | [![](https://img.shields.io/badge/Windows_binaries-1.14.1+_20190309-brightgreen.svg)](https://ci.appveyor.com/project/simonmichael/hledger/build/artifacts) | |
**GNU/Linux** | | | -| Arch | **`pacman -S hledger hledger-ui hledger-web`** | [![Arch](https://repology.org/badge/version-for-repo/arch/hledger.svg)](https://www.archlinux.org/packages/?sort=&q=hledger) | +| Arch | **`pacman -S hledger hledger-ui hledger-web`** | [![](https://repology.org/badge/version-for-repo/arch/hledger.svg)](https://www.archlinux.org/packages/?sort=&q=hledger) | | Gentoo | **`sudo layman -a haskell && sudo emerge hledger hledger-ui hledger-web`** | [![](https://img.shields.io/badge/Gentoo_package-1.14.2-brightgreen.svg)](https://gentoo.zugaina.org/Search?search=hledger) | | Debian | **`sudo apt install hledger hledger-ui hledger-web`** | [![Debian Unstable](https://repology.org/badge/version-for-repo/debian_unstable/hledger.svg)](https://packages.debian.org/unstable/hledger)
[![Debian Testing](https://repology.org/badge/version-for-repo/debian_testing/hledger.svg)](https://packages.debian.org/testing/hledger)
[![Debian Stable](https://repology.org/badge/version-for-repo/debian_stable/hledger.svg)](https://packages.debian.org/stable/hledger)
[![Debian Oldstable](https://repology.org/badge/version-for-repo/debian_oldstable/hledger.svg)](https://packages.debian.org/oldstable/hledger)
[more..](https://packages.debian.org/search?searchon=names&keywords=hledger) | | Ubuntu | **`sudo apt install hledger hledger-ui hledger-web`** | [![Ubuntu 19.04](https://repology.org/badge/version-for-repo/ubuntu_19_04/hledger.svg)](https://packages.ubuntu.com/disco/hledger)
[![Ubuntu 18.10](https://repology.org/badge/version-for-repo/ubuntu_18_10/hledger.svg)](https://packages.ubuntu.com/cosmic/hledger)
[![Ubuntu 18.04](https://repology.org/badge/version-for-repo/ubuntu_18_04/hledger.svg)](https://packages.ubuntu.com/bionic/hledger)
[![Ubuntu 16.04](https://repology.org/badge/version-for-repo/ubuntu_16_04/hledger.svg)](https://packages.ubuntu.com/xenial/hledger)
[![Ubuntu 14.04](https://repology.org/badge/version-for-repo/ubuntu_14_04/hledger.svg)](https://packages.ubuntu.com/trusty/hledger)
[more..](https://packages.ubuntu.com/search?suite=all&searchon=names&keywords=hledger) | @@ -60,7 +61,6 @@ a { white-space:nowrap; } -[*]: #windows-build-issues [Docker]: https://www.docker.com/products/docker-desktop [Homebrew]: https://brew.sh [Linuxbrew]: https://linuxbrew.sh @@ -102,96 +102,50 @@ a { white-space:nowrap; } [repology badges, sometimes out of date]: https://repology.org/project/hledger/badges [custom badges]: https://shields.io +[hledger-install.sh]: https://github.com/simonmichael/hledger/blob/master/hledger-install/hledger-install.sh ## Building from source -Building hledger from source takes a bit longer than using a prebuilt package, -but you can be sure of getting the latest release (or the latest dev version). +You can build hledger wherever the Glasgow Haskell Compiler is supported. +This can take a while, but it's normally a reliable process. +Use one of the methods below to build the current hledger release. +The hledger-install script requires only bash and installs the required tools. +Or, you can install stack or cabal yourself and deal with them directly. -Below are three ways to build hledger. But first, some general tips: +| | | +|--------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| | | +| [hledger-install.sh]
*Linux, Mac, WSL* | **`curl -sO https://raw.githubusercontent.com/simonmichael/hledger/master/hledger-install/hledger-install.sh`**
**`less hledger-install.sh`**    *# satisfy yourself that the script is safe*
**`bash hledger-install.sh`**    *# runs stack or cabal, installing stack if needed* | +| [stack]
*Linux, Mac, Windows* | **`stack install --resolver=nightly-2019-03-21 hledger hledger-web hledger-ui`**    *# installs GHC if needed.* | +| [cabal]
*Linux, Mac, Windows* | **`cabal v2-update && cabal v2-install hledger-1.14.2 hledger-web-1.14.1 hledger-ui-1.14.2`** | -- Building Haskell programs involves downloading and building and - optimising a lot of dependencies. If you haven't built Haskell - software before, your first hledger build could take up to an - hour, 1-2G of free memory, and 1-2G of disk. +On Windows, hledger-ui is not available and should be omitted from the commands above (except, it probably works in WSL). -- Future builds will be much faster. +#### Resource usage -- You can kill a build and restart it later without losing progress. +Building Haskell programs typically involves downloading and compiling and +optimising a lot of Haskell libraries. +If you are doing it for the first time, know that building hledger could take +1-2G of disk, 1-2G of free memory, and up to an hour (though usually it's much less). +It's fine to kill a build and restart it later; +and your later builds will be much faster. -- If you get link errors (eg: "/bin/ld.gold: error: cannot find -ltinfo"), - you might need to install some extra system packages - (C packages provided by your platform - not haskell packages) - and try again. To find the right system package, check the list - below, or do a web search for the error message (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: - - - [windows: hledger-ui is not available](https://github.com/jtdaugherty/vty/pull/1#issuecomment-297143444)\ - [windows: build hangs using GHC 8.6.3](https://github.com/well-typed/generics-sop/issues/93)\ - [windows: cross-environment non-ascii display issues](https://github.com/simonmichael/hledger/issues/961#issuecomment-471229644)\ - [arch: haskell build 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)\ - - -- 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](index.html#helpfeedback). - - - - -### Building with hledger-install.sh - -If you don't already have stack or cabal, or if you are having trouble with them, -[hledger-install.sh](https://github.com/simonmichael/hledger/tree/master/hledger-install) -is an easy and reliable way to get the latest hledger, -on systems which have the bash shell (and are supported by GHC: mac, linux, unix-like environments on windows..). -It automates the installation of stack or cabal and then building the hledger tools, avoiding common pitfalls. -Here's how to run it (or, some folks will prefer to pipe it directly into bash): - - **`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`** - - - -### Building with stack - -[`stack`](http://haskell-lang.org/get-started) is the more reliable of Haskell's two build tools for new users. -You need stack 1.7.1 or newer; the latest release (eg 1.9.3) is the most reliable. -You can often run `stack upgrade` to upgrade it. -64-bit Windows users should choose the 64-bit version of stack. -The following command installs the main hledger packages; - - **`stack install --resolver=nightly-2019-03-21 hledger hledger-web hledger-ui`**\ - - -If needed, you can save some time by omitting the +If needed, you can save time/memory/disk space by omitting the [hledger-web](http://hackage.haskell.org/package/hledger-web) and [hledger-ui](http://hackage.haskell.org/package/hledger-ui) packages -(and hledger-ui's extra dependencies: brick, text-zipper, config-ini etc.) -On Windows, hledger-ui is not available. +from the stack or cabal commands above. To estimate the build time remaining, add `--dry-run`. +#### Using stack + +The latest release of stack (eg 1.9.3) will be the most reliable and is recommended. +If you have an older version, you can probably run `stack upgrade` to upgrade it. +1.7.1 is the oldest that will work. +On Windows, the 64-bit version of stack is recommended. + + - + -### Building with cabal + -[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: +#### C libraries may be required - **`cabal v2-update`**\ - **`cabal v2-install hledger-1.14.2 hledger-ui-1.14.2 hledger-web-1.14.1 hledger-api-1.14 \`**\ -   **`hledger-iadd-1.3.9 hledger-interest-1.5.3`**\ +A few C libraries, like terminfo, are required but not installed by the commands above. +When such C libs are missing, the build will fail at the end with a link error +such as "/bin/ld.gold: error: cannot find -ltinfo". +To solve this, just install the appropriate system package(s) and run the build command again. -### Set up PATH +These package names vary by platform. If you don't see your platform below, +do a web search for the link error message (and send updates for this list): + +| +|-----------------|------------------------------------------------------------------- +| +| Debian, Ubuntu: | **`sudo apt install -y libtinfo-dev`** +| Fedora, RHEL: | **`sudo dnf install -y gmp-devel ncurses-devel`** + + + + +#### Platform-specific build issues + +Here are some known build issues and workarounds on certain platforms: + + +[windows: hledger-ui is not available](https://github.com/jtdaugherty/vty/pull/1#issuecomment-297143444)\ +[windows: build hangs using GHC 8.6.3](https://github.com/well-typed/generics-sop/issues/93)\ +[windows: cross-environment non-ascii display issues](https://github.com/simonmichael/hledger/issues/961#issuecomment-471229644)\ +[arch: haskell build 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)\ + + +#### Setting $PATH may be required After building you may see a message about where the executables were installed. After installation, make sure this install directory is configured in your shell's \$PATH -(preferably near the start of it, to preempt older hledger system packages you may have installed). +(preferably near the start of it, in case you have older hledger binaries lying around). The install directory is: | | on non-Windows systems | on Windows @@ -230,9 +212,10 @@ If you are using bash, this should take care of it: **`echo "export PATH=~/.local/bin:~/.cabal/bin:$PATH" >> ~/.bashrc && source ~/.bashrc`** -### Test the installation +#### Test the installation -You should now be able to run the hledger tools (whichever ones you installed) and see the expected versions: +After a successful build and install, you should be able to run the +hledger tools (whichever ones you installed) and see the expected versions: `$`**`hledger --version`**\ `hledger 1.14.2`\