Windows Subsystem for Linux, abbreviated WSL, is a tool for Windows 10 that lets you run a Linux shell on your Windows machine. It’s a great environment for doing labs for CS 233, but it requires a bit of setup. WSL is relevant to you only if you have Windows 10 installed.
There are two versions of WSL available: WSL 1 (originally just called WSL), and WSL 2.
When we say WSL, we refer to WSL 1 and WSL 2 interchangeably. Beyond initial setup, they work the same for our purposes.
WSL 2 is a new implementation of WSL. It is not just an update for WSL 1; it works in a very different way behind the scenes.
WSL 2 is faster and more flexible than WSL 1, but you do not need the extra speed or features for this course. On the other hand, WSL 1 is much easier to set up.
In general, if you do not know for a fact that you need WSL 2, you’ll be fine with WSL 1. This guide will only tell you how to install WSL 1 for this reason. If, however, you are inclined to figure out how to install WSL 2, this guide will still help you do the rest.
Don’t assume you have a certain version of WSL. Open Windows Command Prompt and run this command to check for sure:
wsl -l -v
The output you see will tell you if you have WSL fully set up, partially set up, or not installed at all.
If you see something like this, you don’t have WSL installed at all.
'wsl' is not recognized as an internal or external command,
operable program or batch file.
You will need to enable WSL as a feature on your machine and then install some version of Linux. To do so, follow this guide from the beginning. When you’re done, restart your computer and run wsl -l -v again to check if it worked.
If you see something like this, you’ve got WSL enabled, but you don’t have any particular version of Linux installed.
Windows Subsystem for Linux has no installed distributions.
Distributions can be installed by visiting the Microsoft Store:
https://aka.ms/wslstore
To fix this, follow this guide starting at the Installing Linux distros using Microsoft Store step. When you’re done, run wsl -l -v again to check if it worked.
If you see something like this, you have WSL installed and ready to run! Unfortunately, though, you’re not done yet.
NAME STATE VERSION
* Ubuntu Running 1
The number under VERSION tells us whether you have WSL 1 or WSL 2. In this case, Ubuntu is installed for WSL 1. Keep in mind which version of WSL you have installed, as you will need to set up X-Forwarding differently depending on which one you have. Before you worry about X-Forwarding though, you should follow the steps below to install all the software required for CS 233.
This part of the setup process will get you ready to complete the first few assignments, but you won’t be able to use graphical applications - anything that isn’t just on the command line.
First, launch WSL by searching for Ubuntu in the Windows Start menu, or by navigating to the distro you installed from the Microsoft Store and clicking Launch.
If you see Installing, this may take a few minutes... wait until Ubuntu finishes installing, then follow the prompts to make a new account. Your username can be anything you want.
You should now see a bash prompt that looks something like this:
user@machine:~$
Now you need to run a slew of commands to install all the software required for CS 233.
Run each of these commands one by one, making sure each one runs successfully. When asked if you want to install each of these programs and you see [Y/n], press y on your keyboard. If you see an error message, try copy-pasting it into Google to find solutions, or ask for help on campuswire if you get stuck.
Run the following command before trying to install software.
sudo apt-get update && sudo apt-get upgrade
You’ll be using git to download and turn in assignments.
sudo apt-get install git
You’ll use make to compile and run code.
sudo apt-get install make
You’ll use verilog to simulate the circuits you write, and gtkwave to examine the simulation results. You won’t be able to run gtkwave until you finish the appropriate X-Forwarding setup guide.
sudo apt-get install iverilog gtkwave
All your C and C++ code will be compiled with clang.
Note that this is not the same version of clang installed on EWS, because that version is no longer available on Ubuntu. Be sure to test your code on EWS before deadlines.
sudo apt-get install clang
You’ll need to install this before you can run QtSpim and QtSpimbot.
sudo apt install qt5-default
You’ll use spim-vasm to run MIPS code on your machine.
git clone https://github-dev.cs.illinois.edu/cs233-sp21/_shared.git
sudo cp _shared/Linux64/spim-vasm /usr/local/bin/
sudo chmod +x /usr/local/bin/spim-vasm
If you see the following error, you will need to delete the _shared directory and try again.
fatal: destination path '_shared' already exists and is not an empty directory.
You’ll use QtSpim to run MIPS code and trace its execution. QtSpim won’t work until you finish the appropriate X-Forwarding guide for your WSL installation.
git clone https://github-dev.cs.illinois.edu/cs233-sp21/_shared.git
sudo cp _shared/Linux64/QtSpim /usr/local/bin/
sudo chmod +x /usr/local/bin/QtSpim
If you see the following error, you will need to delete the _shared directory and try again.
fatal: destination path '_shared' already exists and is not an empty directory.
If QtSpim fails to launch and you see an error like the following…
QtSpim: error while loading shared libraries: libQt5Core.so.5: cannot open shared object file
try running the command below.
sudo strip --remove-section=.note.ABI-tag /usr/lib/x86_64-linux-gnu/libQt5Core.so.5
You’ll use QtSpimbot for Lab 9 and the final project. Look out for updates to this binary on campuswire. QtSpimbot won’t work until you finish the appropriate X-Forwarding guide for your WSL installation.
git clone https://github-dev.cs.illinois.edu/cs233-sp21/_shared.git
sudo cp _shared/Linux64/QtSpimbot /usr/local/bin/
sudo chmod +x /usr/local/bin/QtSpimbot
If you see the following error, you will need to delete the _shared directory and try again.
fatal: destination path '_shared' already exists and is not an empty directory.
If QtSpimbot fails to launch and you see an error like the following…
QtSpimbot: error while loading shared libraries: libQt5Core.so.5: cannot open shared object file
try running the command below.
sudo strip --remove-section=.note.ABI-tag /usr/lib/x86_64-linux-gnu/libQt5Core.so.5
If you know for sure you have WSL 1 installed, follow this guide on how to set up X-Forwarding.
If you know for sure you have WSL 2 installed, follow this guide on how to set up X-Forwarding.
To access your Windows files from within WSL, use the following command, replacing YOUR-USERNAME-HERE with your Windows username:
cd /mnt/c/Users/YOUR-USERNAME-HERE
You can also create a shortcut to your Windows home folder like so:
ln -s /mnt/c/Users/your-username-here ~/windows-home
Now, you’ll be able to find your Windows files in ~/windows-home (so, you could run cd windows-home to end up here).