Windows WSL for Programming C++

There are a number of ways to run VS Code with C++ under Windows. This guide discusses installing VS Code inside either the Windows Subsystem for Linux (WSL), or through a Virtual Machine.

Instead of using this WSL approach, is it easier to use a Dev Container instead.

VS Code in WSL

Windows has a "Windows Subsystem for Linux" (WSL) which allows you to run Linux, and Linux programs within Windows in a somewhat controlled way. The WSL is nice because you are running the compiler under Linux which is how we will test your assignments, and it is often faster than installing a full virtual machine. Using WSL gives you a smooth development environment, easy debugging, and strong assurances that your code will compile OK for marking.

There are two versions of WSL (1, and 2). WSL2 is much less likely to cause problems.

This video shows you an overview of VS Code for WSL; follow these steps to use VS Code in WSL:

Install WSL 2

Follow steps below, taken from WSL guide from Microsoft.

1. Run PowerShell as Administrator
   To do this, go to Start Menu, type PowerShell, select Run as Administrator.
2. Install WSL (may take a few minutes):
   wsl --install
   • If asked to create a user, enter your first name (all lower case)
   • If asked to create a password, enter a simple to remember password. When typing a password in, it will not show you anything as you type each key!
3. Install the Ubuntu Windows App
   From the Start menu, go to the Windows Store, and install the Ubuntu app.
4. Confirm correct version of WSL and Ubuntu are installed. Run PowerShell as Administrator and run wsl --list -v
   • The output should look like:
     PS C:\WINDOWS\system32> wsl --list -v
NAME STATE VERSION
* Ubuntu Running 2

Troubleshooting

• If WSL is Version 1 (WSL1), the run:
  wsl --set-version Ubuntu 2
  • Rerun the wsl --list -v command to ensure it's now version 2.
• If WSL won't install, then you may need to enable some Windows features to allow WSL and virtual machines (because WSL2 is basically a built-in virtual machine):
  1. Open Start Menu, run Turn Windows Features On Or Off
  2. Ensure there are checkmarks beside:
     • Virtual Machine Platform
     • Windows Subsystem for Linux
• If WSL still won't install, ensure that your computer's BIOS (what runs at the very start of when the computer is turned on) allows virtual machines:
  1. Turn off your computer.
  2. Turn on your computer and enter BIOS. You likely need to press and hold F2 as soon as your computer turns on; but you may also need to press Delete or ESC, F1 or F4 depending on the system.
  3. Find and enable the setting for VT-x, AMD-V, SVM, or Vanderpool.
     • See this brief guide for more.
• If WSL still won't install, try reopening the Turn Windows Features On or Off and enable Windows Hypervisor Platform

Install Tools in WSL

1. Open the Ubuntu app (type Ubuntu in the Windows Start menu search box) which opens another command line interface. The prompt may look similar to: brian@BrianPC-5900:~$
2. In the Ubuntu terminal (not PowerShell) run the command to update the package manager:
   sudo apt update
   (Enter you password as needed; it won't show anything as you type.)
3. Install C++ compiler and debugger:
   sudo apt install g++ gdb
   Select yes if asked to confirm.
4. Verify tools installed with the following commands in the Ubuntu terminal:
   g++ --version
gdb --version
5. Create a CMPT130 directory for your work:
   mkdir cmpt130

Install VS Code

Follow these steps to configure VS Code to use WSL, taken from this Microsoft guide.

1. Into Windows, download and install VS Code.
2. Open VS Code, and on the very left select the Extension tab, install the extension named WSL.
3. Click the "><" icon in the very bottom left and select Connect To WSL
4. File > Open Folder; select cmpt130 from the list, click OK.

Compile and Run

Now, each time you want to work on CMPT 130 C++ code, open VS Code. It should re-open your cmpt130 folder in WSL for you.

1. Create a new folder for your work, using the Explorer view (left side). Name the folder something like lab1.
2. Create a .cpp file inside the lab1 folder. Name it something like myprogram.cpp. The .cpp extension is critical!
3. If asked, install the C++ IntelliSense and other C++ extensions.
4. Build the current file:
   Select Terminal > Run Build Task
   Select C/C++: g++ build active file (note it's g++!!) (Click the cog icon on this option if it's available)
5. Run the current file: Run > Start without debugging
   You should see some output in the Debugger tab, plus your program's output and input will be in the Terminal tab.
6. You should see a play button to the top right of your .cpp file. You can now click this to run your program.

Troubleshooting

• Ensure you have your .cpp file open and are clicked into it before trying to build or run the file. For example, trying to build and run a .json file will fail.
• Try deleting the .vscode folder and repeating the Compile and Run steps. Ensure you are selecting the g++ options, instead of the gcc options!
• If you don't see the play button to run your code:
  • Ensure you have C++ IntelliSense addon installed in VS Code under WSL
  • Ensure you have your .cpp file open.
  • Ensure your file's name ends with .cpp.
  • Ensure you are running WSL2
  • Ensure you have installed g++ and gdb into WSL
  • If you still don't see the play button, try installing the "Code Runner" extension. It has worked for some students.

Submitting Code from WSL

Your C++ files are saved on your local computer, but in a special area for access inside WSL. With the above steps, we created the cmpt130 folder inside of WSL on your computer. This is in a different place than your normal Documents. To easily access this folder, do the following:

1. Run Window's "File Explorer".
2. In the bar at the top, type \\wsl$
   • Or, from the start menu, type \\wsl$ and press Enter.
3. Double click on your Ubuntu folder
4. Double click on home.
5. Double click on the folder named after you.
6. Right-click the cmpt130 folder and drag-and-drop it onto your desktop.
7. Select "Create shortcut here"
   • If you see a warning like "These files might be harmful to your computer", select OK.

Now, when you want to access your .cpp files, just use this shortcut on your desktop. You can use a normal web browser to browse to these files when you submit your work.

Alternative to WSL: VS Code in a Linux VM

A virtual machine (VM) is a program you run on your computer, much like any other program, which is basically a fake (virtual) computer. Into a VM you can install a different operating system and any programs you like. The VM runs inside Windows (in this case), so it will not interfere with anything you normally do on your computer (no need to reformat your computer, etc!). You can run all your normal programs (web browser, music app) at the same time as you run the VM.

If you got the WSL working above, then you don't need to install a VM. Only install a VM if you want to manage an additional Linux installed system. This is not the recommended way to work with VS Code in this course.

1. First install a Virtual Machine program in Windows, and then create a virtual machine for Ubuntu Linux
   • Installing VMWare Player and Ubuntu VM. Alternatively, you could install VirtualBox.
   • Configuring a VMWare Player's virtual machine. You'll need to download Ubuntu (select the desktop "LTS" version).
2. Next follow the directions for installing VS Code in Linux
3. When you want to close your VM, you can click the X button and then select to save the VM state for next time (otherwise it's like pulling the plug on the virtual machine computer, which is not good for the system)

To get files onto or off of your Linux VM, you could use a web-browser to submit your assignments directly from the VM. Or, you can often drag-and-drop files between your VM (Linux) and your host OS (Windows); however, this is often buggy.

Here is another guide to installing Ubuntu (Linux) into a VM under Windows.

Notes

• It is possible to install the MinGW C++ compiler into Windows. This way is not very good because it is not possible to use the debugger for programs that read from the keyboard. Therefore, it is not recommended.
• These instructions are an abbreviated version of what appears on this Microsoft help page. For more details see the link in the previous sentence.