VS Code tutorial

Twelve chapters, in the order you would actually hit them: get the project compiled so the debugger has something to read, get a session running, then work outward through breakpoints, exceptions, state inspection, and the things that only show up on bigger targets.

Before you start

Two prerequisites, both covered elsewhere:

The debugger installed and the delphi-win64 debug type available in your editor — see Getting started.
The program you want to debug compiled with full debug information. This is the one that catches people out: without it there are no source lines, and without source lines there are no breakpoints and no stepping. Chapter 1 is entirely about getting this right.

The tutorial assumes you already know how to use a debugger. It explains what this one does, where it differs from what you expect, and where it deliberately refuses to guess.

It does not assume you know Visual Studio Code. If twenty years of Delphi is what you are bringing, read chapter 0 first: it is a translation table, not an editor tutorial, and it takes five minutes.

The chapters

Setting up

0. VS Code for Delphi developers — start here if VS Code is new to you. Which key does what now (two of them are swapped), where the debug windows went, and the settings a Delphi codebase needs before the editor behaves.
1. Preparing your project — the compiler and linker settings the debugger needs, what each debug-info artefact buys you, and the launch.json configuration.

Running and stopping

2. Your first session — the Run and Debug view, starting and stopping, and what each stepping command actually does.
3. Breakpoints — all of them: conditional, hit count, logpoints, address breakpoints, hardware watchpoints, Set Next Statement.
4. Exception handling — the four filters, and the rule engine you need once the codebase raises handled exceptions in a loop.

Reading the state

5. Inspecting variables — locals, objects, generic collections, closures, writing values back, and one real hazard to know about.
6. Threads and the call stack — per-thread inspection, and the fallback for stacks the unwinder cannot walk.
7. Registers, memory and disassembly — for when the source-level view has run out.
8. Expression evaluation — the Pascal grammar available in Watch, hover and the Debug Console, and where the output goes.

Real projects

9. Multi-BPL applications and modules — a host EXE plus runtime packages, which is what this debugger was built for.
10. Attach to a running process — attaching, the process picker, and the one mistake that leaves a mess behind.

Reference

11. Known limitations — what it does not do, stated plainly.
12. Settings and commands reference — every launch property, command and setting in one place.

Not in this tutorial

Driving the debugger from an AI coding agent is its own section — MCP & AI agents. How the engine is built, for anyone reading or extending the source, is in Architecture.