Haskell Setup

Troubleshooting guidance may be found in the Troubleshooting section. Guidance on IDE setup may be found in the IDE-Specific Guidance section.

Quick Start

The purpose of this section is to provide generic, step-by-step instructions for installing Haskell. These instructions are project agnostic. Reference the project developer guide and/or user guide for specific instructions.

Three applications will be installed: GHCup, GHC and Cabal. GHCup is a utility for installing applications in the Haskell toolchain. GHC is a Haskell compiler. Cabal is a system for building and packaging Haskell code.

If you are using a Windows system then you may be queried at various times during or after the installation process as to whether the system’s virus protection application should allow a given application to run. Please select "Allow" for any such queries. Also see Command not found/recognized error message (Windows specific) for troubleshooting problems related to virus protection systems.

If you receive error messages at any point during setup, please consult the Troubleshooting section.

Instructions

  1. Open a terminal and point to your home directory.

  2. GHCup installation

    1. In your terminal, run the command provided to you at the GHCup landing page.

    2. If using Windows OS, when prompted with Where to install to (this should be a short Path, preferably a drive like 'C:\') input the appropriate path (using the suggested default will likely be fine).

    3. If using Windows OS, when prompted with Specify Cabal directory (this is where haskell packages end up) input the appropriate path (using the suggested default will likely be fine).

    4. If using a Unix-like system, when prompted with Do you want ghcup to automatically add the required PATH variable to your shell startup file? select "Yes, prepend".

    5. When prompted with Do you want to install haskell-language-server (HLS)? select "Yes".

    6. When prompted with Do you want to install stack? see the specific setup instructions for your project(s). If the projects you will be working on use Cabal, then Stack is not needed (though there is no harm in installing it).

    7. If using Windows OS, when prompted with Do you want GHCup to install a default MSys2 toolchain? select "Yes" unless you already MSys2 installed.

    8. After installation finishes, restart your terminal.

    9. Check that GHCup installed correctly by typing ghcup --help. If the command is not recognized, check the Troubleshooting section first. If there are still issues, request help in the techsupport Slack channel.

Installing individual toolchain components

You will have likely installed each of the following toolchain components as part of the GHCup installation. However, you may at some point want to install a different version of one of those components. If that is the case then the following are the instructions for installing those components. It is worth noting that even if you have a particular version of a given component installed then there is no harm in asking GHCup to install it again because it will be smart enough to essentially make it a no-operation the second time around.

  1. GHC installation

    1. The version to install is project-specific, but likely 8.10.7. To determine the version of GHC to install for your project consult the cabal.project file (for Cabal projects), or if it’s not specified there then it could be also be mentioned in the .gitlab-ci.yml file in the project repository. If you are working on multiple projects, then you may need to install multiple versions of GHC.

    2. Once the appropriate version has been determined, type ghcup install ghc <VERSION> in the terminal and press Enter.

    3. Verify that ghc has been installed by typing ghc-<VERSION> --help. If the command is not recognized, check the Troubleshooting section first. If there are still issues, contact a member of the stats dev team for help.

  2. Cabal installation

    1. Type ghcup install cabal 3.6.2.0 in the terminal and press Enter.

    2. Verify that cabal has been installed by typing cabal-3.6.2.0 --help. If the command is not recognized, check the Troubleshooting section first. If there are still issues, contact a member of the stats dev team for help.

  3. HLS installation. Usually you will want to install whatever the recommended version of HLS is according to ghcup list.

    1. Type ghc install hls in your terminal and press Enter.

Troubleshooting

LLVM error message (macOS specific)

If you receive the error message below:

<no location info>: error:
    Warning: Couldn't figure out LLVM version!
             Make sure you have installed LLVM between [9 and 13)

then you need to install a different build of LLVM.

If you have Homebrew installed, you can run the code below

brew install llvm

If you are not a Homebrew user, check the LLVM website for alternative installation instructions.

You will also want to add the following line, amended to include the appropriate path, to your shell startup file: ${HOME}/.bashrc, ${HOME}/.zshrc, etc.

export PATH="/opt/homebrew/opt/llvm/bin:$PATH"

After adding the above line (potentially with the appropriate modifications) restart your shell. Also see Ensuring applications are on the search path for more specific instructions regarding regarding shell search paths.

Also see Help wanted for LLVM config for Haskell on Mac on Reddit for some additional discussion.

Command not found/recognized error message (Windows specific)

If you attempt to run <APPLICATION NAME> --help, where the APPLICATION NAME is ghc, cabal, ghci, etc., and you get an error message like the following, it is possible that you are running the command in MinGW or WSL. Please try the command in PowerShell instead.

bash: ghc: command not found

Alternatively, suppose you attempt to run <APPLICATION NAME> --help in PowerShell and get an error message like the following.

ghc : The term 'ghc' is not recognized as the name of a cmdlet, function, script file, or operable program.
Check the spelling of the name, or if a path was included, verify that the path is correct and try again.

First, ensure that you have restarted PowerShell since you performed the installation. Next, check the bin folder in your GHCup installation directory; this will often default to C:\ghcup\bin. This folder should contain files like <APPLICATION NAME>, and <APPLICATION NAME>.shim.

  1. If the GHCup bin folder doesn’t exist or doesn’t contain a collection of files like the ones described above, then there was likely a problem with the application installation and you may want to wipe everything clean and retry the installation.

  2. Next, check that GHCup bin folder is on your search path. Enter $Env:Path into PowerShell and ensure that you see the appropriate GHCup bin folder in the output.

  3. If the GHCup bin folder does exist and is on the search path, then you may need to whitelist the application you are trying to run with your virus protection application. In some cases the virus protection application may even delete the application. In that case you may see that you have <APPLICATION NAME>.shim but no <APPLICATION> file. The process for whitelisting files will depend on your particular system’s virus protection application; Please see the corresponding documentation for details.

Ensuring applications are on the search path

Many of the applications in the Haskell toolchain rely on being on the shell’s search path, which is a list of directories in which applications are looked for. This list is defined by the PATH variable for most commonly-used shells. To ensure that the applications installed by e.g. GHCup are on the search path, the directories in which the applications are installed into are usually added to the PATH variable as part of a so-called startup file which is processed whenever the shell is first invoked.

To check what directories are listed on your search path, run echo $PATH in your shell and you should see a string of colon-separated directories. For example, if you are on a macOS system then you should see entries similar to /Users/username/.cabal/bin, /Users/username/.ghcup/bin, and possibly an entry similar to /opt/homebrew/opt/llvm/bin in the event that you needed to install a different version of LLVM.

If the appropriate directories are not in your current search path, try the following troubleshooting steps.

  1. Try opening a new shell to ensure that your shell has read in the most recent version of the startup files.

  2. Ensure that the required directories are added to the PATH variable in your startup files.

    1. Check which shell you are using by running the command ps -p $$.

    2. Check that the appropriate directories are added to one of the startup files for your shell.

      • If you are a Bash user then check ~/.bashrc (or whichever file you put them in)

      • If you are a Z shell user then check ~/.zshrc (or whichever file you put them in).

      • The entries should be of the form export PATH="/Users/username/.ghcup/bin:$PATH" (the paths will by system and username specific).

  3. Ensure that the SHELL variable corresponds to the shell that you are using.

    1. Run echo $SHELL to display the value of SHELL.

    2. If you are a Bash user and SHELL isn’t appropriately set then run the command chsh -s /bin/bash.

    3. If you are a Z shell user and SHELL isn’t appropriately set then run the command chsh -s /bin/zsh.

  4. Ensure that the application you are using to launch the shell is configured to launch the appropriate shell. Many applications use the value of SHELL to determine which shell to use, but if that isn’t working you can often specify the desired shell. To configure VSCode’s terminal see the Integrated Terminal instructions.

SSL certificate error message

If you receive an error with a message like the following:

curl: (60) SSL certificate problem: self signed certificate in certificate chain

please try the following workarounds:

  • Upgrade the version of curl. If you run curl --version and it lists an old release date, then you may want to install a newer version. You can see when your version of curl was released by viewing the curl - Release web page.

  • Update your OpenSSL certificates. If you installed OpenSSL on macOS through Homebrew, then you can use the command brew postinstall openssl. If you did not use Homebrew, you can install OpenSLL from source.

  • Use wget instead of curl when running GHCup by specifying the option --downloader=wget. So for example, you can use the command ghcup --downloader=wget list

IDE-Specific Guidance

The purpose of this section is to provide IDE-specific instructions for creating the optimal Haskell experience.

At this time, we are only providing guidance on Visual Studio Code. Other IDEs such as Emacs and Vim may be optimal for certain users, but require more configuration. We hope to include guidance on these IDEs in the future.

Visual Studio Code

Visual Studio Code has many extensions to support Haskell development. The recommended extensions are listed below.

Note that haskell-linter requires some additional work.

Every extension can be configured by navigating to Code > Preferences > Settings and selecting "Extensions" from the menu. We recommend the following Settings:

  • Haskell

    • Set "Formatting Provider" to "brittany"