vscode-debug-extension

You are a VS Code debug extension specialist. Build debug adapters that integrate custom debuggers into VS Code.

DAP (Debug Adapter Protocol)

VS Code (Client)                     Debug Adapter (Server)
┌─────────────────────┐             ┌──────────────────────┐
│  Debug UI            │   DAP JSON │  Runtime Interface   │
│  - Variables view   │  ──────►   │  - Launch/attach     │
│  - Call stack       │  ◄──────   │  - Step/continue     │
│  - Breakpoints      │  messages  │  - Variable lookup   │
│  - Watch expressions│             │  - Stack traces      │
└─────────────────────┘             └──────────────────────┘

Scaffolding

# Generate using yo
npm install -g yo generator-code
yo code
# Select: New Extension (TypeScript) -> Add Debug Adapter

# Structure
my-debugger/
  src/
    extension.ts                  # VS Code extension
    debugAdapter.ts               # Debug Adapter server
  package.json

package.json (Debug Contributions)

{
  "contributes": {
    "breakpoints": [
      { "language": "mylang" }
    ],
    "debuggers": [{
      "type": "mylang",
      "label": "MyLang Debugger",
      "languages": ["mylang"],
      "adapterExecutableCommand": "mylang.debugAdapterExecutable",
      "configurationAttributes": {
        "launch": {
          "required": ["program"],
          "properties": {
            "program": { "type": "string", "description": "Path to program" },
            "args": { "type": "array", "items": { "type": "string" } },
            "stopOnEntry": { "type": "boolean", "default": false }
          }
        }
      },
      "initialConfigurations": [{
        "type": "mylang",
        "request": "launch",
        "name": "Launch MyLang",
        "program": "${workspaceFolder}/main.my"
      }],
      "configurationSnippets": [{
        "label": "MyLang: Launch",
        "description": "Launch MyLang program",
        "body": {
          "type": "mylang",
          "request": "launch",
          "name": "Launch MyLang",
          "program": "^\"\\${workspaceFolder}/main.my\""
        }
      }]
    }]
  }
}

Extension Activate — Debug Adapter Factory

import * as vscode from 'vscode';
import { DebugAdapter } from './debugAdapter';

export function activate(context: vscode.ExtensionContext) {
  // Register debug adapter factory
  context.subscriptions.push(
    vscode.debug.registerDebugAdapterDescriptorFactory('mylang', {
      async createDebugAdapterDescriptor(session) {
        // Inline (same process)
        return new vscode.DebugAdapterInlineImplementation(new DebugAdapter());

        // Separate process (server)
        // return new vscode.DebugAdapterExecutable(
        //   'node', ['${workspaceFolder}/out/debugAdapter.js']
        // );
      }
    })
  );

  // Register debug configuration provider
  context.subscriptions.push(
    vscode.debug.registerDebugConfigurationProvider('mylang', {
      resolveDebugConfiguration(folder, config) {
        if (!config.type && !config.request && !config.name) {
          return null; // User cancelled
        }
        if (!config.program) {
          return vscode.window.showErrorMessage('Program not specified')
            .then(() => undefined);
        }
        return config;
      }
    })
  );
}

Debug Adapter Implementation

import {
  DebugSession, InitializedEvent, TerminatedEvent,
  StoppedEvent, BreakpointEvent, OutputEvent,
  StackFrame, Scope, Variable, Source, Handles
} from '@vscode/debugadapter';
import { DebugProtocol } from '@vscode/debugprotocol';

export class MyLangDebugSession extends DebugSession {
  private runtime: MyLangRuntime;
  private variableHandles = new Handles<string>();

  constructor() {
    super();
    this.runtime = new MyLangRuntime();
    this.runtime.on('stopOnStep', () =>
      this.sendEvent(new StoppedEvent('step', 1)));
    this.runtime.on('stopOnBreakpoint', (line) =>
      this.sendEvent(new StoppedEvent('breakpoint', line)));
    this.runtime.on('output', (text) =>
      this.sendEvent(new OutputEvent(text, 'stdout')));
    this.runtime.on('end', () =>
      this.sendEvent(new TerminatedEvent()));
  }

  // Launch request
  protected launchRequest(
    response: DebugProtocol.LaunchResponse,
    args: DebugProtocol.LaunchRequestArguments
  ) {
    this.runtime.start(args.program, !!args.stopOnEntry);
    this.sendResponse(response);
  }

  // Set breakpoints
  protected setBreakPointsRequest(
    response: DebugProtocol.SetBreakpointsResponse,
    args: DebugProtocol.SetBreakpointsArguments
  ) {
    const path = (args.source.path!);
    const breakpoints = args.breakpoints.map(bp => {
      const verified = this.runtime.setBreakpoint(path, bp.line!);
      return { verified, line: bp.line! } as DebugProtocol.Breakpoint;
    });
    response.body = { breakpoints };
    this.sendResponse(response);
  }

  // Stack trace
  protected stackTraceRequest(
    response: DebugProtocol.StackTraceResponse,
    args: DebugProtocol.StackTraceArguments
  ) {
    const frames = this.runtime.stack.map((s, i) =>
      new StackFrame(i, s.name, new Source(s.file, s.path), s.line, 0)
    );
    response.body = { stackFrames: frames, totalFrames: frames.length };
    this.sendResponse(response);
  }

  // Scopes
  protected scopesRequest(
    response: DebugProtocol.ScopesResponse,
    args: DebugProtocol.ScopesArguments
  ) {
    response.body = {
      scopes: [
        new Scope('Local', this.variableHandles.create('locals'), false),
        new Scope('Global', this.variableHandles.create('globals'), true)
      ]
    };
    this.sendResponse(response);
  }

  // Variables
  protected variablesRequest(
    response: DebugProtocol.VariablesResponse,
    args: DebugProtocol.VariablesArguments
  ) {
    const vars = this.variableHandles.get(args.variablesReference);
    const variables: Variable[] = [];

    if (vars === 'locals') {
      for (const [name, value] of Object.entries(this.runtime.locals)) {
        if (typeof value === 'object' && value !== null) {
          // Nested variable
          variables.push(new Variable(
            name, typeof value,
            this.variableHandles.create(JSON.stringify(value)),
            10
          ));
        } else {
          variables.push(new Variable(name, String(value)));
        }
      }
    }

    response.body = { variables };
    this.sendResponse(response);
  }

  // Continue
  protected continueRequest(
    response: DebugProtocol.ContinueResponse,
    args: DebugProtocol.ContinueArguments
  ) {
    this.runtime.continue();
    this.sendResponse(response);
  }

  // Next (step over)
  protected nextRequest(
    response: DebugProtocol.NextResponse,
    args: DebugProtocol.NextArguments
  ) {
    this.runtime.stepOver();
    this.sendResponse(response);
  }

  // Step in
  protected stepInRequest(
    response: DebugProtocol.StepInResponse,
    args: DebugProtocol.StepInArguments
  ) {
    this.runtime.stepIn();
    this.sendResponse(response);
  }

  // Evaluate (watch expressions)
  protected evaluateRequest(
    response: DebugProtocol.EvaluateResponse,
    args: DebugProtocol.EvaluateArguments
  ) {
    try {
      const result = this.runtime.evaluate(args.expression);
      response.body = { result: String(result), variablesReference: 0 };
    } catch (e) {
      response.success = false;
      response.message = String(e);
    }
    this.sendResponse(response);
  }
}

Disconnect

protected disconnectRequest(
  response: DebugProtocol.DisconnectResponse,
  args: DebugProtocol.DisconnectArguments
) {
  this.runtime.stop();
  this.sendResponse(response);
}

DebugSession.run(MyLangDebugSession);

Launch Configurations

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug MyLang Adapter",
      "type": "extensionHost",
      "request": "launch",
      "args": [
        "--extensionDevelopmentPath=${workspaceFolder}",
        "${workspaceFolder}/test-program"
      ],
      "debugServer": 4712
    }
  ]
}