Instructions for setting up your computer for the practicals

If you are on Windows, you have to decide whether to do things natively on Windows, or to work in WSL2. (WSL1 will probably fail.) If you have a misbehaving virus scanner (try Windows Defender instead) or other Windows-specific issues, you might try WSL2 instead. If you go the WSL2 route, install WSL2 according to the Installing WSL2 section below, and then follow the Linux instructions inside WSL2 (“Ubuntu”); you may then also prefer to use a Dev container (see Using a Dev container below).

Before we start: if anything in the instructions prints an error message and you’re not quite sure what to do, please show us before trying lots of things. We may well have seen it before and know exactly what to do (and can update these instructions so that other students do not run into your issue too).

If you are using Windows and this guide instructs you to use a “terminal”, read Powershell or cmd. We recommend installing and using Windows Terminal; this is a much nicer terminal than plain cmd and allows seamless logging into the WSL2 Linux environment, if you use that.

First install Haskell by installing GHCup (say: “g.h.c. up”). Make sure to install GHC 9.4.8 (use ghcup tui in a terminal); at the time of writing, this is the version installed by default by GHCup. You do need Cabal (version 3.8 or later), but you will not need Stack. For both GHC and Cabal, if you manually install GHCup to install a different version, you will need to set it as default too. Installing HLS (Haskell Language Server) is recommended if you use an editor supporting the LSP (such as VSCode – not Visual Studio) and would like interactive diagnostics in your editor when editing Haskell code.

Update the cabal package index by running cabal update in a terminal.

For the third practical (Quickhull), you will also need Clang and libffi installed. For Clang, any recent version (e.g. ≥ 15) should work.

We strongly recommend using version control software such as Git, especially when working with someone else (as you will in practicals 2 and 3).

VSCode (“Visual Studio Code”) is by-and-large the editor that makes it easiest to develop Haskell these days. If you do youse VSCode, you probably want these extensions:

  1. Haskell: This extension allows IDE-style support using HLS (if you have installed that with GHCup).
  2. If you use WSL2, then also WSL, to automatically connect to your WSL2 installation. Connect by pressing F1 (or ctrl-P and then >), and then searching for “WSL: Connect to WSL”.

This should be all. Let us know if anything doesn’t work!

Installing WSL2

A lot of software in the broad space of “programming technology” is developed on, and for, Linux-like systems. Usually, MacOS is sufficiently Linux-like that this kind of software works with few issues, but Windows is generally an afterthought. (And less common systems like the various BSD flavours are even more seldomly supported.) Haskell, as well as Accelerate (a framework for parallel computing in Haskell that we use in P3: Quickhull), both fall in this category. Haskell supports Windows quite well since a few years (but still carries a “Linux emulation” environment with it, called MinGW), but native Windows support in Accelerate is very recent (hence the use of an unreleased version in the third practical).

So if you have issues running Haskell or Accelerate on native Windows, you may want to run them in a Linux environment on your Windows machine, which is possible through WSL2 (Windows Subsystem for Linux, version 2). The “2” there is very important: WSL1 uses very different technology and has too many issues that make things unstable in practice.

WSL2 cannot be installed on Windows Home. However, students can upgrade their Windows Home machine to Windows for Education for free, and this version of Windows does support WSL2.

To install WSL2, proceed as follows (assuming that there is no WSL(2) yet on your computer):

Using a Dev container

In previous years, we were using Dev containers exclusively for Windows users; we still have configuration files for that if you want to use them. Get in touch with the teachers if so.

Troubleshooting

When in trouble, perhaps the instructions below might help.

No editor feedback / takes a long time: After (re)building, when first opening a Haskell file in your editor, the VSCode Haskell plugin (if installed) has to compile the package. In VSCode’s notifications (footer bar), there will be an indication that it is still loading. This will resolve in around 10-15 minutes and only has to run the first time you open the project.

To check the status of compilation, head to View > Output and select the Haskell extension.

HLS Server crashed: If the Haskell plugin in VSCode reports The HLS server crashed 5 times in the past 3 minutes, open a terminal and type cabal build. The plugin should run correctly after restarting the editor.

File Error Highlight: ensure that ghcide is compiled with the same GHC: If a file is highlighted with the error Please ensure that ghcide is compiled with the same GHC, running cabal build then closing and opening the file may resolve the issue. Otherwise, restart the editor.

Git Commit Error: unable to start editor ‘editor’: When merging branches locally, if git throws unable to start editor 'editor', it can not find a suitable editor. If this happens to you, try:

git config --global core.editor core.editor code

for VSCode. (Replace code by your own editor if you are using something else.)

Cabal says “No cabal file found” while building dependencies: Try cabal build again. It will likely succeed (or get further, at least) the second time.

Additional Windows specific advice: