Skip to content

Terminal & VS Code — Windows

One-page survival guide · Windows (WSL2 + Ubuntu)

On Windows, everything happens inside WSL2 — not PowerShell

The course tools run in Ubuntu under WSL2. Open Ubuntu (not PowerShell or CMD) for all course work. PowerShell is only used once, for USB setup. If your prompt ends in $ and shows your Ubuntu username, you're in the right place.

Open your terminal

  • Start menu → type "Ubuntu" → Enter. That's your everyday terminal.
  • First launch ever: it asks you to create a UNIX username + password. The password is invisible as you type — that's normal.
  • Prefer tabs? Install Windows Terminal from the Microsoft Store and pick Ubuntu from its dropdown.

The commands you'll actually use

Command What it does
pwd Print working directory — where am I?
ls List files here · ls -la shows hidden files + details
cd foldername Go into a folder
cd .. Go up one folder
cd ~ Jump to your home folder
mkdir name Make a new folder
cp a b Copy file a to b
mv a b Move/rename a to b
rm file Delete a file (no recycle bin — it's gone)
cat file Print a file to the screen
clear Wipe the screen (or press Ctrl-L)

Survival keys

  • Tab — auto-completes file/folder names. Use it constantly; it prevents typos.
  • ↑ / ↓ — scroll through previous commands. Don't retype, re-run.
  • Ctrl-C — stop/cancel whatever is running.
  • Copy/paste — Ctrl-Shift-C / Ctrl-Shift-V in the terminal (note the Shift). In Windows Terminal, plain Ctrl-C may just copy — use Ctrl-Shift.

Your daily course workflow

First-time setup: enable the code command

Install VS Code on the Windows side, plus the Remote – WSL extension. Then run code . from your Ubuntu terminal — VS Code reconnects into Linux so it sees the course tools. The HDL extensions install on the Linux side automatically.

# 1. Go to the course folder and enter the toolchain
cd hdl-for-dsd
git pull                 # grab the latest course updates
nix develop              # enters the shell with all tools (slow first time only)

# 2. Open the project in VS Code
code .                   # the space-dot means "this folder"

# 3. In a lab folder: simulate, then program the board
make sim                 # compile + run the testbench (prints PASS/FAIL)
make wave                # open the waveform viewer
make prog                # synthesize + flash the Go Board
                         #   ↳ first plug-in this session? attach USB first (see gotchas)

# 4. When you're done
exit                     # leaves the nix shell

Getting a terminal inside a lab folder (VS Code)

Step 3 assumes your terminal is already sitting in the lab folder. The easy way: right-click the lab folder in the Explorer sidebar → Open in Integrated Terminal — it drops you straight in, no cd needed. First make sure that terminal uses the same shell you've been using — on Windows that's Ubuntu (WSL), not PowerShell. Check the dropdown next to the terminal's +, or run Terminal: Select Default Profile from the command palette (Ctrl-Shift-P) and pick Ubuntu (WSL).

VS Code essentials

Action How
Open this folder code . from the terminal
Built-in terminal Ctrl-` (the key above Tab)
Command palette Ctrl-Shift-P — search any command by name
Save file Ctrl-S
Format file Shift-Alt-F
Quick-open a file Ctrl-P then type the name

Windows gotchas

  • Programming the Go Board needs a USB hand-off. WSL2 can't see USB on its own. Once per session (and after each replug), open a separate PowerShell window as Administrator — not nix, not the VS Code terminal — and run: 
    usbipd list                              # find the FTDI device's BUSID
usbipd attach --wsl --busid <BUSID>      # forward it to Ubuntu
    Then back in Ubuntu, ls /dev/ttyUSB* should show /dev/ttyUSB0.
  • Where do my files live? Keep course files inside WSL (your Ubuntu home, ~), not in C:\Users\.... Working across the Windows/Linux boundary is slow and causes weird errors.
  • Don't paste Windows paths (C:\Users\you) into the Ubuntu terminal — use Linux paths (/home/you or ~).

Stuck? See the full Toolchain Setup Guide for installation and troubleshooting.

Discussion

Discussion