Windows Subsystem for Linux (WSL) Installation Guide

The Windows Subsystem for Linux (WSL) is a type 1 hypervisor¹ developed by Microsoft to allow developers to run Linux environments directly on Windows, without the drawbacks of type 2 hypervisors¹ such as virtual machines, or, the hassles of dual-boot setups.

This guide will show you how to install the Windows Subsystem for Linux (WSL) on Windows and use it to install the required dependencies for the NYU Processor Design Team.

Installing WSL
Using VSCode with WSL
Installing Packages (Ubuntu)
- CMake
- Verilator
- cURL
- Git
Maintaining Packages
Optional: Using Zsh
- Prettifying Zsh
- Changing VSCode’s Default Terminal
Further Reading

Installing WSL

Open a Terminal and run the following command:
```
wsl --install
```
The following command will install the default Linux distribution (Ubuntu), but you can install any of the distributions listed by wsl -l -o
```
wsl --install -d <distribution_name>
```
After a restart, running the command wsl in the terminal or running the wsl command in your start menu will open a virtual linux environment in your pc
Once WSL has been set up you will have to create a username and password for your linux machine
Follow the instructions provided and remember the password you enter as it will be required to run sudo commands
- sudo stands for “Super User Do”

Using VSCode with WSL

Install VSCode in your native Windows environment first.
In VSCode, install the WSL extension using the Extensions tab on the left tool panel
Now, VSCode can be run in the WSL environment by doing one of the following:
1. Clicking on the “Remote Window” button at the bottom left of your VSCode window and clicking “New WSL Window”
2. Pressing F1 or Control+Shift+P to open the command palette and selecting WSL: New WSL Window

Upgrading the Ubuntu Version

By default, WSL only has LTS (Long-term support) versions available. This doesn’t work for us because we want to use more up to date packages that are only available in more recent versions.

If the second sed command fails, you might want to open sources.list and see a line like this deb http://archive.ubuntu.com/ubuntu/ jammy main restricted. If instead of jammy, it says focal or

Before you begin, open sources.list, and find a line like deb http://archive.ubuntu.com/ubuntu/ jammy main restricted. If instead of jammy, you see focal or bionic, switch jammy to focal or bionic in the commands below.

cat /etc/apt/sources.list

The first step is to switch from the LTS branch to the normal Ubuntu branch
```
sudo sed 's/lts/normal/g' /etc/update-manager/release-upgrades
```
Next, the package sources need to be pointed to lunar instead of jammy.
```
sudo sed -i 's/jammy/lunar/g' /etc/apt/sources.list
```
Once the sources are updated, the existing packages must be upgraded to the new version. This can take several minutes to complete.
```
sudo apt update
sudo apt upgrade
sudo apt dist-upgrade
```

Troubleshooting

Installing Packages (Ubuntu)

The installation command for Ubuntu is
```
sudo apt install <package name>
```
- This will search for the specified package in the APT registry and install it in your system.
- You can list multiple package names in one command, for example:
```
sudo apt install verilator clang-format
```

CMake

Unfortunately, APT doesn’t have the latest version of CMake, so we must use this alternative².

Uninstall existing CMake Versions

sudo apt remove --purge --auto-remove cmake

Preparing for Installation

sudo apt update && \
sudo apt install -y software-properties-common lsb-release && \
sudo apt clean all

Obtain a copy of kitware’s signing key

wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | gpg --dearmor - | sudo tee /etc/apt/trusted.gpg.d/kitware.gpg >/dev/null

Add kitware’s reposity to sources list

sudo apt-add-repository "deb https://apt.kitware.com/ubuntu/ $(lsb_release -cs) main"

Optionally, installing kitware-archive keyring package to keep Kitware’s keyring up to date

sudo apt update
sudo apt install kitware-archive-keyring
sudo rm /etc/apt/trusted.gpg.d/kitware.gpg

If running `sudo apt update` gets the following error:

Err:7 https://apt.kitware.com/ubuntu bionic InRelease
The following signatures couldn't be verified because the public key is not available: NO_PUBKEY 6AF7F09730B3F0A4
Fetched 11.0 kB in 1s (7552 B/s)

Copy the public key 6AF7F09730B3F0A4 and run this command:

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 6AF7F09730B3F0A4

Finally, update and install the cmake package
```
sudo apt update
sudo apt install cmake
```

Verilator

sudo apt install verilator

cURL

sudo apt install curl

Git

sudo apt install git

Then follow the Getting Started With Git tutorial to configure git

Maintaining Packages

To update APT and package definitions, run the following
```
sudo apt update
```
- update fetches the latest information of the installed packages
Upgrade everything
```
sudo apt upgrade -y
```
- upgrade will upgrade them if newer versions have been released
- the -y flag simply tells APT that it has permission to upgrade everything and doesn’t have to ask you to say “yes” to each upgrade
Uninstall a packages
```
sudo apt remove <package name>
```

Optional: Using Zsh

Ubuntu’s default shell is the Bourne-again shell (Bash)
Z-shell (Zsh) is a Unix shell built on top of BASH
Zsh includes more features and is the default shell on other popular Linux distros such as Arch Linux
To replace Bash as Ubuntu’s default shell, first install zsh:
```
sudo apt install zsh
```
Change login shell to Zsh
```
chsh -s $(which zsh)
```
- chsh changes your login shell
- The -s flag specifies the login shell
- The $() syntax tells the shell to interpret everything between the parentheses as a command
- which identifies the location for various executables and prints the full path of the executables; in this case, we want the path for zsh
Log out and log back in for the change to take effect

Prettifying Zsh

The default Zsh appearance is, for the lack of better words, hideous, unpleasant, and unsightly
To fix this, many open-source frameworks have been created to create themes for Zsh terminals
Oh My Zsh is the most popular Zsh theme framework
- Sidetrack: Fun story about the ideation of Oh my Zsh, written by the creator, Robby Russel
Not only does it make Zsh much more pleasant to look at, it also provides useful and important information such as your current working directory, git branch, git status, etc.

To install Oh My Zsh, use the following command

sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

To change the theme of your terminal, you can run the command nano ~/.zshrc and change the line ZHS_THEME="robbyrussell" to any of the available themes listed here
- The .zshrc file is a special run-command file that contains configurations for your zsh terminal session
- It exists on your home directory as a hidden file, hence the ~ and . beginning
- It is executed when you log in

Changing VSCode’s Default Terminal

To change VSCode’s default terminal, press F1 or Control+ Shift+P to open up the command palette
Search for Terminal: Select Default Shell and select zsh
Now every time you open a terminal in WSL, VSCode will open a zsh terminal

NYU Processor Design Documentation