Skip to content

Terminal & VS Code — Linux

One-page survival guide · Linux (Ubuntu / Debian / Fedora)

You're on the native platform

The course toolchain is built for Linux first. Everything runs directly — no WSL, no compatibility layers. The one setup step that matters is USB permissions for the Go Board (the udev rule below).

Open your terminal

  • Ctrl-Alt-T opens a terminal on most desktops (GNOME, KDE, XFCE).
  • Or open your app launcher and search "Terminal" / "Konsole".
  • When you type a password for sudo, the characters stay invisible — that's normal, just type and press Enter.

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 trash — 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).

Your daily course workflow

First-time setup: enable the code command

Install VS Code from code.visualstudio.com (the .deb/.rpm adds code to your PATH). If it's missing: open VS Code → Ctrl-Shift-P → "Shell Command: Install 'code' command in PATH".

# 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 (GTKWave)
make prog                # synthesize + flash the Go Board

# 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 opens already in that folder, no cd needed. Make sure that terminal uses the same shell you've been using (usually bash): pick it from the dropdown next to the terminal's +, or run Terminal: Select Default Profile from the command palette (Ctrl-Shift-P).

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

Linux gotchas

  • iceprog: Permission denied? Your user needs USB access to the board. Install the udev rule once: 
    sudo tee /etc/udev/rules.d/99-fpga-boards.rules > /dev/null << 'EOF'
ACTION=="add", ATTR{idVendor}=="0403", ATTR{idProduct}=="6010", MODE="0666"
EOF
sudo udevadm control --reload-rules && sudo udevadm trigger
    Then unplug/replug the board. sudo iceprog is a temporary workaround.
  • Finding the Go Board: lsusb | grep -i ftdi should list the FTDI device; it appears as /dev/ttyUSB0.
  • Use sudo sparingly. Only commands that change the system (installing packages, udev rules) need it. Never run nix develop or make with sudo.

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

Discussion

Discussion