Somewhat-repeatable recipes for getting a reliable haskell build toolchain installed as of 2022Q1. You might need to make adjustments, eg on Windows, but hopefully not too many.
Current most popular method. Best way to get native arm tools on mac m1. You can use it to install the compiler ghc
, build tools cabal
and/or stack
, and IDE/editor language server hls
(under $HOME/.ghcup
). Actively maintained.
- install latest ghcup (manages haskell core tools)
- from https://www.haskell.org/ghcup
- on unix/mac, remember to do the shell setup dance:
echo 'source ~/.ghcup/env' >> $HOME/.YOURSHELLrc; source $HOME/.YOURSHELLrc # YOURSHELL is bash, zsh, ...
- on unix/mac, remember to do the shell setup dance:
- or from your OS's package system, then run
ghcup upgrade
ghcup --version
should now show the expected up-to-date ghcup version, eg v0.1.17.5
- from https://www.haskell.org/ghcup
- install haskell build tools; the displayed versions should be what you expect
- GHC (compiler and a few other core tools like haddock)
ghcup install ghc
ghc --version
should show an expected up-to-date version, eg 8.10.7
- cabal (basic/standard build tool)
ghcup install cabal
cabal --version
should show an expected up-to-date version, eg 3.6.2.0cabal update
to update cabal's index of available packages
- stack (alternate build tool emphasising repeatable builds)
ghcup install stack
stack --version
should show an expected up-to-date version, eg 2.7.3stack update
to update stack's index of available packages- constrain stack to use only ghcup's GHC, if you want (saves disk space):
mkdir -p $HOME/.stack
printf "system-ghc: true\ninstall-ghc: false\n" >>$HOME/.stack/config.yaml
- hls (enables haskell-aware IDEs/editors)
ghcup install hls
- GHC (compiler and a few other core tools like haddock)
- Now you can run commands like:
ghc
,ghci
,haddock
,cabal install
,stack install
, ...
Simplest and most cross-platform toolchain. stack
auto-installs appropriate GHC versions for you (under $HOME/.stack
) as you work on projects. Compared to cabal
, it makes reliable building easier and it has better UX for common needs. Currently receiving only essential maintenance.
- install latest stack
- from https://www.fpcomplete.com/haskell/get-started
- or from your OS's package system, then run
stack upgrade
stack --version
should show an expected up-to-date version, eg 2.7.3stack update
to update stack's index of available packages
- Now you can run commands like:
stack ghc
,stack ghci
,stack haddock
,stack install
, ...
The best and easiest haskell-aware IDE setup.
ghcup install hls
as above. (Optional - the VS Code Haskell extension will auto-install it - but avoids problems on mac m1.)- install https://code.visualstudio.com and run it
- View > Extensions > install "Haskell" (AKA "Haskell for Visual Studio Code")
- open a small, simple single-package haskell project and let the Haskell extension do its setup. For troubleshooting, watch the status bar and carefully study the log in View > Appearance > Show Panel > Output > Haskell.
- Now you can (in projects where HLS starts successfully) see red squiggly lines for errors in your haskell files, click to navigate to definitions and references, etc.
To install other haskell tools (like hlint) or apps (like pandoc):
-
First, some notes:
- Think about your preferred install method (when there's a choice):
- system packages ? quick, easy, low risk, probably out of date
- developer-provided binaries ? quick, easy, higher risk, more up to date
- building from source ? slow and disk/ram-hungry, often difficult for non-experts, most up to date.
- Why is building from source often difficult ?
- Haskell's build tools are complex and evolving.
- Haskell software packages are numerous and highly varied in age and maintainedness.
- So, there are many ways for a non-expert to fail when building random haskell software. These notes aim to give you a start, but can't cover all failure modes.
- Think about your preferred install method (when there's a choice):
-
When the tool/app is in your OS's package system, and not too out of date, you could use that package (minimises build time, disk space, and risk). Eg:
sudo apt install pandoc
(or pacman, brew, nix, ...)
-
When the tool's website provides a sufficiently trustworthy/signed/fresh binary that runs on your system, you could download and use that.
-
When you need or want to build (a released version of) the tool and install its executable(s), without keeping a copy of the source on your system, use stack/cabal's install command:
- when it is packaged in stackage (https://stackage.org), you can install it with stack:
cd
to avoid interference from a haskell project's setupstack update
to ensure it knows about the latest versions- make sure that stack's install directory (
$HOME/.local/bin
) is in your $PATH, and near enough to the front that the newly installed executable won't be shadowed by an already-installed version. stack install TOOLPKG
You can check the install plan with--dry
, or request a specific version withstack install TOOLPKG-VERSION
- or if that fails to start,
stack install TOOLPKG --resolver RESOLVER
where RESOLVER is one of the snapshots on stackage.org that contains TOOLPKG
- when it is packaged on hackage (https://hackage.haskell.org), you can install it with stack as above, or with cabal:
cd
to avoid interference from a haskell project's setupcabal update
to ensure it knows about the latest versions- make sure that cabal's install directory (
$HOME/.cabal/bin
) is in your $PATH, and near enough to the front that the newly installed executable won't be shadowed by an already-installed version. cabal install TOOLPKG
You can check the install plan with--dry-run
, or request a specific version withcabal install TOOLPKG-VERSION
cabal install
can fail to start, perhaps with pages of error output, for many reasons (see above). Here are some common ones:- Check that
ghc --version
is a version that TOOLPKG will build with (or check thatghc-pkg list base
shows a version satisfying TOOLPKG'sbase
bounds on Hackage). You can select a different installed GHC version by adding-w ghc-VERSION
to the install command, or install/select a new default version withghcup install ghc GHCVERSION --set
. - Check for a file in
$HOME/.ghc/GHCVERSION/environments/
created by previous use ofcabal install --lib
. Deleting it might fix the problem. - Check that you ran
cabal update
. Sometimes it needs to know about the latest package versions.
- Check that
- If you hit trouble, what to do ? People will gladly help, but try to conserve everyone's time:
- First check the project's own issue tracker / chat room / maintainer / mail list.
- Then try the general #haskell chat rooms, or stack overflow. General haskell mail lists and reddits also exist but are usually not the best place for support requests, unless you're trying to publish the topic widely.
- If you are on Arch Linux, you will have special problems that other Haskellers don't have. If so, please either
- Use one of the setups above, which are consistent on all platforms.
- Or go the Haskell page in the Arch wiki, learn about the issues specific to your Arch setup, and seek help from the maintainers of the Arch haskell packages.
- That ideally should be the end of the matter.. but if you decide to seek Arch help in the general Haskell chat rooms, make it clear from the start that you're on Arch.
- Now
TOOL --version
should show the expected up-to-date version, if it supports --version. Here TOOL is the executable name - usually the same as the package name but not always; some packages provide differently-named executables, multiple executables, or no executables.
- when it is packaged in stackage (https://stackage.org), you can install it with stack:
-
When you want to build from a local copy of the tool's source (eg to modify it, or to build an unreleased version):
- Download its source, usually with a version control tool like
git
, or you can usecabal get [-s] PKG
,stack unpack PKG
, or download a tarball from Hackage. cd REPODIR
- Follow the build instructions in the project's README.
- If there are none, but the project has a
stack.yaml
file,stack install
is most likely to work. (Orstack build
to just build in place without installing executables.) - Otherwise
cabal install
might work, with all the same caveats as above. (Orcabal build
to build in place without installing executables.)
- Download its source, usually with a version control tool like