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.

Firstly, I'll try to debug the ruby project through command line

> rdebug-ide main.rb
Fast Debugger (ruby-debug-ide 0.6.0, debase 0.2.2.beta10, file filtering is supported) listens on 127.0.0.1:1234

You can see that we are running ruby-debug-ide 0.6.0 and the real debugger under the hood is debase 0.2.2.beta10. It's not an interactive shell so we need to communicate with it through sockets.

> telnet 127.0.0.1  1234
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.

Then set a breakpoint, start the debugging session, continue.

> telnet 127.0.0.1  1234
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
break main.rb:2
<breakpointAdded no="1" location="/Users/penlv/code/rubytest/main.rb:2"/>
start
<breakpoint file="/Users/penlv/code/rubytest/main.rb" line="2" threadId="2"/> // breakpoint hit
c
Connection closed by foreign host.

If you can set a breakpoint directly in cmd, then it must be a problem with VSCode-Ruby extension. Otherwise it means either we call the wrong command, or ruby-debug-ide/debase just doesn't support. If it's the latter case, there is nothing we can do in this extension and we need to file bugs/feature requests to upstream, or maybe help them with it.