Skip to content

Instantly share code, notes, and snippets.

@simonmichael

simonmichael/SM's Haskell Survival Guide.md

Last active March 5, 2022 03:26
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save simonmichael/15895cedb8b0aaa9b5fbc3f8bfd9b904 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save simonmichael/15895cedb8b0aaa9b5fbc3f8bfd9b904 to your computer and use it in GitHub Desktop.
Download ZIP
SM's Haskell Survival Guide (draft)
Raw
SM's Haskell Survival Guide.md

SM's Haskell Survival Guide

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.

Set up with ghcup

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, ...
    • 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
  • 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.0
      • cabal 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.3
      • stack 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
  • Now you can run commands like: ghc, ghci, haddock, cabal install, stack install, ...

Set up with stack

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.3
    • stack update to update stack's index of available packages
  • Now you can run commands like: stack ghc, stack ghci, stack haddock, stack install, ...

Install VS Code

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.

Install other haskell tools/apps

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.

  • 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 setup
      • stack 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 with stack 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 setup
      • cabal 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 with cabal 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 that ghc-pkg list base shows a version satisfying TOOLPKG's base 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 with ghcup install ghc GHCVERSION --set.
        • Check for a file in $HOME/.ghc/GHCVERSION/environments/ created by previous use of cabal install --lib. Deleting it might fix the problem.
        • Check that you ran cabal update. Sometimes it needs to know about the latest package versions.
    • 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 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 use cabal 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. (Or stack build to just build in place without installing executables.)
    • Otherwise cabal install might work, with all the same caveats as above. (Or cabal build to build in place without installing executables.)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment