Most of this course explains why things work. This page comes first so you can see one working before you read a word of theory: one download, one command, one passing test, and then one deliberate failure. Nothing here needs to make sense yet. You are only checking that your machine can do the job.
A terminal: Terminal on macOS, or the Ubuntu shell on Linux or WSL.
Icarus Verilog, Verilator, Yosys, Make and Git installed. If you are not sure, run iverilog -V and see whether it answers; the commands to install everything are in Installing and Checking Tools.
The unzip command, which macOS has and Ubuntu installs with sudo apt install unzip.
Download start-here-examples.zip into any folder and open a terminal there.
Run the three commands below, one at a time. The last one runs lint, the simulation and the synthesis check.
# captured terminal output
$ unzip -q start-here-examples.zip
$ cd start-here-examples/mini-controller
$ make all
verilator --lint-only -Wall --top-module mini_controller rtl/mini_controller.sv
- V e r i l a t i o n R e p o r t: Verilator 5.048 2026-04-26 rev vUNKNOWN-built20260426
- Verilator: Built from 0.033 MB sources in 2 modules, into 0.008 MB in 3 C++ files needing 0.000 MB
- Verilator: Walltime 0.003 s (elab=0.000, cvt=0.001, bld=0.000); cpu 0.003 s on 1 threads; allocated 9.438 MB
mkdir -p build
iverilog -g2012 -Wall -s tb_mini_controller -o build/sim.vvp rtl/mini_controller.sv tb/tb_mini_controller.sv
set -o pipefail; cd build && vvp sim.vvp | tee sim.log
VCD info: dumpfile mini_controller.vcd opened for output.
PASS: mini_controller
tb/tb_mini_controller.sv:69: $finish called at 2396000 (1ps)
yosys -Q -T -p 'read_verilog -sv rtl/mini_controller.sv; hierarchy -check -top mini_controller; proc; opt; check -assert; stat' > build/synth.log
[exit status 0]You should see the line PASS: mini_controller and, at the very end, [exit status 0]. Your Verilator line shows your own version and time, and your Yosys run prints nothing else because its details go to a log file. If you see those two things, your machine works and you can stop worrying about setup.
Lint (the verilator line) checked the design for suspicious code without running it. It printed only its own report, so nothing was wrong.
Simulation (the iverilog and vvp lines) compiled the design and a testbench, ran the test, and printed PASS: because every check agreed with the expected answer.
Synthesis check (the yosys line) asked whether the design could become real gates. It wrote a log and printed nothing, which here means success.
A passing test only means something if it can fail. Keep a copy of the design, then replace it with a copy that has one planted bug: it adds two where it should add one. Run only the simulation and ask for the exit status.
# captured terminal output
$ cp rtl/mini_controller.sv original.sv
$ cp mutants/counts_by_two.sv rtl/mini_controller.sv
$ make sim > run.txt 2>&1; echo "exit status: $?"
exit status: 2
$ tail -n 4 run.txt
ERROR: count changed before the clock edge (1 -> 2)
FATAL: tb/tb_mini_controller.sv:68: FAIL: 116 mismatches
Time: 2396000 Scope: tb_mini_controller
make: *** [sim] Error 1You should see exit status: 2 and a last line from the testbench that starts with FATAL: and reports many mismatches. The full output has one error line per wrong check; the transcript shows only the last four lines. The exit status is the number your computer, and later your automation, uses to decide that something failed. Make always reports 2 when a step fails, even though the line above it says Error 1: the 1 comes from the simulator, the 2 from Make.
Now put the good design back and prove you are green again:
Run cp original.sv rtl/mini_controller.sv to restore the copy you saved.
Run make all and look for PASS: mini_controller and exit status 0.
command not found for iverilog, verilator, yosys or make: that tool is not installed or not on your path. Go to Installing and Checking Tools.
No such file or directory or No rule to make target: you are in the wrong folder. Run pwd and ls; you should be inside mini-controller and see a file named Makefile.
missing separator from Make: a tab in the Makefile became spaces. Unpack the zip again to get a clean copy.
Anything else: Troubleshooting Table lists the common messages with their fixes.