Debugger

Introduction

VS Code implements a generic debug UI and provide a generic debug protocol for debuggers to talk to. There are already a lot of debuggers written in the most suitable language out there, so what we need to do is just creating a debug adapter which stands for the bridge between VS Code and real debuggers. For more detailed information, you may want to read VS Code's documentation about debug adapters.

VSCode-Ruby is just a debug adapter. It talks to a real ruby debugger (ruby-debug-base or debase) through Sockets. I didn't re-invent the wheel and directly leverage a well-known ruby-debug-ide, which glues ruby-debug to IDEs like Eclipse (RDT), NetBeans and RubyMine. It's created by JetBrains guys and it makes the communication real easy: send commands as plain text string, receive responses in XML format, through Sockets.

The workflow of setting a breakpoint is like

[VS Code] Create breakpoint
          |
          |
          |
[VSCode-Ruby] Send `break main.rb:3` through sockets
          |
          |
          |
[ruby-debug-ide] Wrap the command and send it to the real debugger
          |
          |
          |
[real debugger] ...
          |
          |
          |
[ruby-debug-ide] Wrap the results and send it to debug adapter
          |
          |
          |
[VSCode-Ruby] Receive `<breakpoint no="1" ... />`, parse it and send the success response to VS Code

Troubleshoot

As you can see from above diagram, the workflow involves 4 components so if we run into any trouble, the first thing we should do is figuring out where it breaks.

A common issue we see often is setting breakpoints doesn't work balablabala, the first thing we should check is ruby-debug-ide does work reasonably in this case.