Skip to content

Terminal & VS Code — macOS

One-page survival guide · macOS (Intel & Apple Silicon)

Your Mac already has everything it needs

macOS ships with a real Unix terminal and recognizes the Go Board's USB chip natively. Apple Silicon (M1–M4) runs every course tool natively — no Rosetta.

Open your terminal

  • Cmd-Space (Spotlight) → type "Terminal" → Enter. That's it.
  • Pin it: right-click the Terminal icon in the Dock → Options → Keep in Dock.
  • When you type a password (e.g. 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 (yes, Ctrl, not Cmd).
  • Copy/paste — Cmd-C / Cmd-V work normally in Terminal.

Your daily course workflow

First-time setup: enable the code command

If code . says command not found: open VS Code → Cmd-Shift-P → type "Shell Command: Install 'code' command in PATH" → Enter. Then it works from any terminal.

# 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 (zsh or bash): pick it from the dropdown next to the terminal's +, or run Terminal: Select Default Profile from the command palette (Cmd-Shift-P).

VS Code essentials

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

macOS gotchas

  • GTKWave won't open the first time. macOS blocks unsigned apps. Go to System Settings → Privacy & Security, scroll down, and click Open Anyway. You only do this once.
  • Finding the Go Board: after plugging in, run ls /dev/cu.usbserial* — you should see something like /dev/cu.usbserial-XXXXXXXX. No driver install needed.
  • Xcode tools: if git or code complain on a fresh Mac, run xcode-select --install once and follow the dialog.
  • Cmd vs Ctrl: Mac apps use Cmd, but terminal control keys (Ctrl-C, Ctrl-L, Ctrl-A) always use Ctrl.

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

Discussion

Discussion