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.

Open a new terminal window (to pick up the new system path settings), then update the cabal package index by running cabal update in a terminal.

For the third practical (Quickhull), you will also need git, 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 use 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.

Installing the VS Build Tools

The kernel functions that Accelerate creates from your data-parallel code are compiled using Clang, and Clang needs some system libraries to be able to compile native code for Windows. On Windows, these system libraries come from Visual Studio, or the Visual Studio Build Tools.

  1. If you already have the Visual Studio Installer on your system, open it and check if you already have Visual Studio (Community) installed. Note that this is completely unrelated to VS Code.
    • If you already have VS (Community): inside the Visual Studio Installer, click on “Modify” in the VS (Community) box. This should get you a screen with “workloads” you can select.
    • If you do not yet have VS (Community), install the VS Build Tools: go to https://visualstudio.microsoft.com/downloads, scroll down to “All Downloads”, open “Tools for Visual Studio”, and select “Build Tools for Visual Studio”. If you run the installer, you should get a screen with “workloads” you can select.
  2. Under the Workloads tab, choose the “Desktop development with C++” workload. If you want to save a bit of disk space (not much), keep only the following two options selected:
    • “MSVC v143 - VE 2022 C++ x64/x86 build tools (Latest)”
    • “Windows 11 SDK (…)” (choose the latest option) The attentive reader may note that the wizard also offers Clang; we use a separate Clang install because the one from VS somehow doesn’t seem to work properly with Accelerate.
  3. Install that. This takes a while.

It turns out that having both Visual Studio and the Build Tools installed results in Clang getting confused between the two (it appears that Visual Studio is 64-bit (x64) and the Build Tools are 32-bit (x86)). If Clang complains about the bit-ness of your system libraries, double-check that you haven’t installed both simultaneously.

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 "code --wait"

(or possibly git config --global --replace-all core.editor "code --wait") for VSCode. (Replace code --wait 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: