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 

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.