Delphi Visual Studio Code Debugger

Delphi Win64 Debugger

Debug Delphi Win64 applications outside the Embarcadero IDE — a real debugger built on the Windows Debug API, written in Delphi.

The repository contains three programs that share one debugger engine:

| | What it is | Where it lives | |---|---|---| | Debug adapter | A Debug Adapter Protocol (DAP) server. This is the debugger itself: breakpoints, stepping, call stacks, variables, expression evaluation. Any DAP client can drive it. | VisualStudioCodeDelphiDebugger\ | | VS Code extension | The client that makes it usable in the editor: the delphi-win64 debug type, the process picker for attaching, status-bar progress, and an editor for the exception rules. | install\local.delphi-win64-debug\ | | MCP server | The same engine exposed to an AI agent over the Model Context Protocol — 33 tools (set_breakpoint, step_into, get_locals, evaluate_expression, get_call_stack, read_memory, …). It lets an agent run a program, stop it, and read its actual state instead of guessing from the source. | MCPDebugger\ |

The engine is shared: DebuggerCore\ holds the Windows Debug API loop, the symbol readers (.rsm, TD32, .map, .dcp, JCL) and the expression evaluator. The three front ends are thin.

> You will almost certainly also want the Delphi IDE plugin. > It adds an Open in VS Code command to the Delphi IDE that generates the > workspace and the launch configuration for the current project: output paths, > source root, unit search paths, and the package list for a BPL project. A real > Delphi project carries a couple of hundred search paths, and nobody wants to > write that by hand. The debugger works without it if you write launch.json > yourself, but the plugin is what makes it practical — install it first.

> ⚠️ Compile the program you want to debug with full debug information, or > most of this will not work. A debugger can only show what the compiler > emitted. In the Delphi project options, for the Win64 Debug configuration: > > - Compiling → Optimization off, Debug information on, Local symbols on; > - Linking → Debug information on, Include remote debug symbols on > (this is the .rsm), and Map file: Detailed. > > On the command line that is -$O- -V -VN -VR, which is what Debugme.cfg in > this repository uses. Measured on that project: those four flags alone already > emit the .exe with its TD32 section, the .map and the .rsm — -GD > (Map file: Detailed) turned out not to be required for a .map to appear, > though it is what the IDE sets and it does no harm. Keep the .map and .rsm > next to the .exe. > > To step into the RTL and VCL rather than over them, also enable > Compiling → Use debug .dcus. > > What each one buys you: > > | Artefact | Without it | > |---|---| > | TD32 section, .map, or JCL data — any one | no source lines: no breakpoints, no stepping | > | .rsm | breakpoints and stepping still work, but local variables, types and expression evaluation are severely limited | > | optimizations off | breakpoints land on the wrong line and locals read as garbage, because the code no longer matches the source | > > The same applies to every runtime package you want to step into: a BPL > compiled without debug information stays a black box even when the host has > full symbols.

> Status: working and feature-rich. Launch and attach, breakpoints > (line / conditional / hit-count / log-points), stepping (over/into/out) > and set-next-statement, call stack with function names, variable > inspection (locals, registers, globals, nested object / record / > dynamic-array expansion) with type-aware formatting, a full Pascal > expression evaluator for watch/hover/REPL, setVariable (primitives, > strings, enums, sets, var parameters), and a configurable exception > engine (filters + per-exception rules) are all functional. See > [What works](#what-works) for the full list.

---

Prerequisites

| Tool | Purpose | |---|---| | Delphi 10.3 Rio or later (dcc64 in PATH after rsvars.bat) | Compiling the adapter and the debug target | | VS Code | The editor the extension plugs into | | Delphi IDE plugin | Generates the workspace and launch configuration from a Delphi project. Not strictly required, but see the note above | | DelphiLSP extension (embarcaderotechnologies.delphilsp) | Delphi language support in VS Code (syntax, autocomplete). A separate Embarcadero extension; this one only debugs | | JCL sources (optional) | Only for the default JCL debug-info support; build with JCL_DEBUG_OFF to omit it — see [Optional: JCL debug-info support](#optional-jcl-debug-info-support) |

---

Quick start

> Just want to use it? Do not build anything. Grab > delphi-win64-debugger-setup-*.zip from the > latest release, > extract it anywhere and run Setup.exe. The debug adapter, the MCP server and > the VS Code extension are already compiled inside it, so no Delphi toolchain > and no build step are needed on that machine. Windows will warn that the > executables are unsigned — see the notes in the release. > > The rest of this section is for working on the debugger from a source > checkout.

Assumes Delphi (Athens or later) is installed and dcc64 is on PATH after rsvars.bat, plus VS Code.

This is the path for working on the debugger from a source checkout — it installs the extension in development mode, where VS Code launches the adapter straight from the compiler output, so rebuilding is enough to pick up changes (no copy step). To install the debugger only to use it, or to ship it to a machine without the sources, see the alternatives right after.

:: 1. Get the repository
git clone  Win64Debugger
cd Win64Debugger

:: 2. Build the adapter and install the extension in DEVELOPMENT mode. It writes
::    a manifest whose "program" points directly at the build-output exe, so a
::    rebuild is reflected on the next debug session with no copy. Run once.
call install-dev.bat

:: 3. Build the bundled sample so there is something to debug. A fresh clone
::    has no .exe/.map/.rsm (they are gitignored), so build them once.
call rsvars.bat
dcc64 Debugme.dpr

Now open the project and start a session:

1. If VS Code prompts to install the recommended DelphiLSP extension

(embarcaderotechnologies.delphilsp, from .vscode/extensions.json), accept.

1. Open Win64DebuggerProj.code-workspace — open the workspace file, not

the folder; it wires up DelphiLSP and the compiler settings.

1. Reload the window (Ctrl+Shift+P → Developer: Reload Window).
2. In Run and Debug (Ctrl+Shift+D) pick "Debug Debugme (Delphi DAP)"

and press F5. You should hit the entry point and be able to step, set breakpoints, and inspect variables.

After a change to the adapter source, the edit/test loop is just:

1. Stop the running debug session (Shift+F5) — the exe is locked while it runs.
2. call build_dap.bat
3. F5 — VS Code relaunches the freshly built adapter. No re-install, no copy.

To debug your own application instead, compile it with debug info (-V -VN -VR, optimizations off) so it emits .map and .rsm next to the .exe, then add a launch configuration — see [Launch configuration](#launch-configuration).

> Install to use, not develop — to copy the adapter into the extensions > folder (so it no longer depends on the checkout) run build_installer.bat > then install\Install.exe. It is interactive: builds the adapter if needed, > detects VS Code / VS Code Insiders, updates an existing install in place after > confirmation. See [VS Code extension setup](#vs-code-extension-setup).

> Ship to another machine — to install on a machine without the > repository or a Delphi toolchain, build a self-contained zip with > build_setup_zip.bat and ship it — see > [Distributable zip](#distributable-zip-no-repo-no-delphi-on-the-target).

---

Build

One-shot: build everything

call build_debug.bat

This initializes the Delphi compiler environment (rsvars.bat), compiles Debugme.exe (emitting its .map and .rsm), and compiles VisualStudioCodeDelphiDebugger.exe.

Adapter only (faster iteration)

call build_dap.bat

Compiler flags for the debug target

Key flags that must be active when compiling the program you want to debug:

| Flag | Purpose | |---|---| | -$O- | Disable optimizations | | -V -VN -VR | Generate debug info and .map file | | -DDEBUG | Optional conditional define | | -E.\Win64\Debug | Output directory |

For Debugme these are set in Debugme.cfg (one per line, without the leading -).

Optional: JCL debug-info support

The adapter can additionally read JCL (JEDI Code Library) debug data — the MAP-derived symbol table JCL stores either as a linked JCLDEBUG PE section or a sidecar .jdbg file — as an address→location and procedure-name fallback for modules that ship JCL data but no embedded TD32 / no .map. It is implemented in DebuggerCore\JclDebugReader.pas and gated by the JCL_DEBUG conditional.

JCL_DEBUG is ON by default, which requires the JCL sources to be present. The build configurations point at the default install location C:\Athens\jcl\jcl\source (subdirectories windows, common, include); adjust those paths if your JCL lives elsewhere. The affected configs are the adapter VisualStudioCodeDelphiDebugger\VisualStudioCodeDelphiDebugger.cfg, the test runner DebuggerTests\RunTests.cfg, and build_mcp.bat.

To build without JCL (e.g. JCL is not installed): compile with the JCL_DEBUG_OFF conditional defined. This removes the uses JclDebug entirely, so JCL need not be installed and the JCL search paths are ignored (they are harmless when the define is off). Add the define to the relevant .cfg files, e.g.:

-DJCL_DEBUG_OFF

into VisualStudioCodeDelphiDebugger.cfg, DebuggerTests\RunTests.cfg, and pass -DJCL_DEBUG_OFF on the dcc64 command line in build_mcp.bat. With the define off, JclDebugReader compiles to a no-op factory (it never registers a provider); everything else — TD32, .map, .rsm/.dcp symbol resolution — is unaffected.

> If you build the adapter, MCP server, or test runner from the IDE (msbuild > via the .dproj) rather than these command-line scripts, apply the same choice > there: add the JCL search paths (to keep it on) or the JCL_DEBUG_OFF define (to > turn it off) in the project options, since an IDE build regenerates the .cfg > from the .dproj.

Optional: pre-build the symbol-index sidecars

The first time the debugger reads a module's .rsm or .dcp, it scans the whole container to build a lookup index, then caches that index in a .idx sidecar next to it. The scan costs roughly half a second for a 45 MB package; every later session reloads the sidecar in a few milliseconds instead.

The catch is when that scan happens: lazily, at a stop, on the thread the debugger answers requests on. Stopping somewhere that first touches several runtime packages therefore pauses the session while they are indexed.

The RTL and third-party packages never change between your builds, so their sidecars can be built once, offline:

cmd /c "C:\Athens\GitHub\Win64Debugger\DevTools\build_all.bat"

rem the Delphi DCP corpus - a few hundred files, one pass, a few minutes
DevTools\Win64\Debug\PrebuildIdx.exe "C:\Users\Public\Documents\Embarcadero\Studio\23.0\Dcp\Win64" -j 2

Add -force when sidecars already exist but were written by an older build of this project: a change to the index format or to the parser leaves them stale, and a stale sidecar is ignored, so the cold scan is paid again in every session until they are rebuilt.

This does not help your own packages — you recompile those constantly, which invalidates their sidecars by design. If it is worth automating, run the tool over your output directory as a post-build step.

Source is DevTools\PrebuildIdx.dpr; DevTools\README.md documents the full flag list, including -verify, which rebuilds every sidecar and compares it by SHA-256 against the one already on disk (useful after touching a parser).

---

Tests

An automated integration suite lives in DebuggerTests\. It builds a dedicated test target, launches the real DAP adapter against it, and asserts correctness of breakpoints, stepping, locals, and the expression evaluator. Run the full suite after any change to the adapter or the RSM/TD32 parsers.

:: build the target + the runner, then run everything
call DebuggerTests\build_and_run.bat

The scripts use cd /d %~dp0 internally, so they can be called from any working directory. Finer-grained entry points:

| Script | Purpose | |---|---| | DebuggerTests\build_and_run.bat | Build the test target and runner, then run the suite | | DebuggerTests\build_target.bat | Build only the debuggee (TestTarget.exe) | | DebuggerTests\build_runner.bat | Build only the test runner (RunTests.exe) | | DebuggerTests\run_tests.bat | Run the already-built tests |

Separate diagnostic tools (RSM/TD32 inspectors, PE dumpers) live in DevTools\; see DevTools\README.md.

---

VS Code extension setup

The extension lives in a local directory under VS Code's extension folder. It is not published to the marketplace.

Recommended: the installer

After building the adapter (build_dap.bat), run:

call build_installer.bat
install\Install.exe

Install.exe stages the freshly built adapter next to the extension manifest, detects your VS Code installation(s), and copies the extension into %USERPROFILE%\.vscode\extensions\local.delphi-win64-debug\. If a previous version is already installed it updates it in place (after confirmation). Reload VS Code afterwards.

Scripted alternative

:: build the adapter and stage it into install\local.delphi-win64-debug\
call update-install.bat
:: copy the staged folder into your VS Code extensions directory
call install\install.bat

Manual

1. Build the adapter (build_dap.bat).
2. Create the folder

%USERPROFILE%\.vscode\extensions\local.delphi-win64-debug\.

1. Copy install\local.delphi-win64-debug\package.json and the built

VisualStudioCodeDelphiDebugger.exe (VisualStudioCodeDelphiDebugger\Win64\Debug\) into it.

1. Reload VS Code (Ctrl+Shift+P → Developer: Reload Window).

The bundled package.json registers the delphi-win64 debug type and points at the adapter via the relative path ./VisualStudioCodeDelphiDebugger.exe, so no path editing is needed as long as the executable sits beside it.

Where the adapter executable ends up

The build, the staging step and the install each hold a copy:

| Stage | Location | |---|---| | Build output | VisualStudioCodeDelphiDebugger\Win64\Debug\VisualStudioCodeDelphiDebugger.exe | | Staging (gitignored, inside the repo) | install\local.delphi-win64-debug\VisualStudioCodeDelphiDebugger.exe | | Installed (what VS Code launches) | %USERPROFILE%\.vscode\extensions\local.delphi-win64-debug\VisualStudioCodeDelphiDebugger.exe |

Distributable zip (no repo, no Delphi on the target)

To install the debugger on another machine that has neither the repository nor a Delphi toolchain, build a self-contained zip on a development machine:

call build_setup_zip.bat

It builds the adapter, builds the portable installer, and bundles everything into dist\delphi-win64-debugger-setup-v.zip:

Setup.exe                     ← portable installer / updater
local.delphi-win64-debug\     ← the extension (manifest + prebuilt adapter exe)
INSTALL_INSTRUCTIONS.md

On the target machine: extract the zi

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: csm101
• Source: csm101/delphi-visual-studio-code-debugger
• License: MIT

Install and usage instructions live in the source repository linked above.