Skip to content
Branch: master
Find file Copy path
Find file Copy path
1 contributor

Users who have contributed to this file

406 lines (234 sloc) 10.4 KB

ruby-debug-ide protocol

Next: Summary, Previous: (dir), Up: (dir)

ruby-debug-ide protocol

This file contains specification of the protocol used by ruby-debug-ide.

Next: Specification, Previous: Top, Up: Top

1 Summary

This document describes protocol used by ruby-debug-ide for communication between debugger engine and a frontend. It is a work in progress and might, and very likely will, change in the future. If you have any comments or questions please send me an email.

The communication has two parts/sides. First ones are commands sent from a frontend to the debugger engine and the second is the opposite way, answers and events sent from the debugger engine to the frontend.

commands are almost the same as the ones used by CLI ruby-debug. So you might want to contact the ruby-debug-ide document.

answers and events are sent in XML format described in the specification below.

Specification is far from complete. Will be completed as time permits. In the meantime, source code is always the best spec.

Next: Changes, Previous: Summary, Up: Top

2 Specification


  • Command is what frontend sends to the debugger engine
  • Answer is what debugger engine sends back to the frontend
  • Example shows simple example

Next: Events, Up: Specification

2.1 Commands

Next: Deleting Breakpoint, Up: Commands

2.1.1 Adding Breakpoint


   break <script>:<line\_no>


   <breakpointAdded no="<id>" location="<script>:<line\_no>"/>


   C: break test.rb:2
   A: <breakpointAdded no="1" location="test.rb:2"/>

Next: Enabling Breakpoint, Previous: Adding Breakpoint, Up: Commands

2.1.2 Deleting Breakpoint


   delete <breakpoint\_id>


   <breakpointDeleted no="<id>"/>


   C: delete 2
   A: <breakpointDeleted no="2"/>

Next: Disabling Breakpoint, Previous: Deleting Breakpoint, Up: Commands

2.1.3 Enabling Breakpoint

Supported since ruby-debug-ide 0.2.0


   enable <breakpoint\_id>


   <breakpointEnabled bp\_id="<id>"/>


   C: enable 2
   A: <breakpointEnabled bp\_id="2"/>

Next: Condition, Previous: Enabling Breakpoint, Up: Commands

2.1.4 Disabling Breakpoint

Supported since ruby-debug-ide 0.2.0


   disable <breakpoint\_id>


   <breakpointDisabled bp\_id="<id>"/>


   C: disable 2
   A: <breakpointDisabled bp\_id="2"/>

Next: Catchpoint, Previous: Disabling Breakpoint, Up: Commands

2.1.5 Setting Condition on Breakpoint

Supported since ruby-debug-ide 0.2.0


   condition <script>:<line\_no>


   <conditionSet bp\_id="<id>"/>


   C: condition 1 x>5   # Stop on breakpoint 1 only if x>5 is true.
   A: <conditionSet bp\_id="1"/>

Next: Threads, Previous: Condition, Up: Commands

2.1.6 Exception Breakpoint


   catch <exception\_class\_name>


   <catchpointSet exception="<exception\_class\_name>"/>


   C: catch ZeroDivisionError
   A: <catchpointSet exception="ZeroDivisionError"/>

Next: Frames, Previous: Catchpoint, Up: Commands

2.1.7 Threads Listing


   thread list


     <thread id="<id>" status="<status>"/>


   C: thread list
   A: <threads>
        <thread id="1" status="run"/>
        <thread id="2" status="sleep"/>

Next: Variables, Previous: Threads, Up: Commands

2.1.8 Frames Listing




     <frame no="<frame\_no>" file="<script>" line="<line\_no>" current="<boolean>"/>
     <frame no="<frame\_no>" file="<script>" line="<line\_no>"/>


   C: where
   A: <frames>
        <frame no="1" file="/path/to/test2.rb" line="3" current="true" />
        <frame no="2" file="/path/to/test.rb" line="3" />

Previous: Frames, Up: Commands

2.1.9 Variables Listing Local Variables


   C: var local
   A: <variables>
        <variable name="array" kind="local" value="Array (2 element(s))" type="Array" hasChildren="true" objectId="-0x2418a904"/>
      </variables> Instance Variables


   C: var instance some\_array
   A: <variables>
        <variable name="\[0\]" kind="instance" value="1" type="Fixnum" hasChildren="false" objectId="+0x3"/>
        <variable name="\[1\]" kind="instance" value="2" type="Fixnum" hasChildren="false" objectId="+0x5"/>

   C: var instance some\_object
   A: <variables>
        <variable name="@y" kind="instance" value="5" type="Fixnum" hasChildren="false" objectId="+0xb"/>

Previous: Commands, Up: Specification

2.2 Events

Next: Suspension, Up: Events

2.2.1 Breakpoint

Event example:

   <breakpoint file="test.rb" line="1" threadId="1"/>

Next: Exception, Previous: Breakpoint, Up: Events

2.2.2 Suspension

Event example:

   <suspended file="/path/to/test.rb" line="2" threadId="1" frames="1"/>

Next: Message, Previous: Suspension, Up: Events

2.2.3 Exception

Event example:

   <exception file="/path/to/test.rb" line="2" type="ZeroDivisionError" message="divided by 0" threadId="1"/>

Previous: Exception, Up: Events

2.2.4 Message

Event example:

   <message>some text</message>
   <message debug='true'>some debug text</message>

Previous: Specification, Up: Top

3 Changes

Mentions also related changes in the ruby-debug-ide gem implementation.

3.1 Changes between 0.4.9 and 0.4.10

  • Fixes possible NoSuchMethodException

3.2 Changes between 0.4.5 and 0.4.6

  • added Debugger::start_server (ticket #25972)

3.3 Changes between 0.4.4 and 0.4.5

  • possibility to remove catchpoints
  • bugfix: syntax error with Ruby 1.9

3.4 Changes between 0.4.3 and 0.4.4

  • bugfix: print out backtrace when debuggee fails

3.5 Changes between 0.4.2 and 0.4.3

  • depends on the "~> 0.10.3.x", rather then on 0.10.3 exactly to be compatible with future ruby-debug-base 0.10.3.x releases

3.6 Changes between 0.4.1 and 0.4.2

  • Dependency changed to ruby-debug-base-0.10.3 which fixes various bugs and contains bunch of RFEs

3.7 Changes between 0.4.0 and 0.4.1

  • '–stop' switch: stop at the first line when the script is loaded. Utilized by remote debugging
  • Making '-x' switch actually work. Commenting out sending of elements to the debugger. To be decided. There are large amount of such events. For now serves rather for ruby-debug-ide developers.
  • ensure 'file' attribute contains absolute path
  • fixing CLI verbose when -d is used. Some unused code

3.8 Changes between 0.3.1 and 0.4.0

  • Support for debug attribute in message element. Emitted by backend when –xml-debug (new since 0.4.0) option is used.
  • More robust failures handling in DebugThread

3.9 Changes between 0.3.4 and 0.3.5

  • bugfix: syntax error with Ruby 1.9

3.10 Changes between 0.3.3 and 0.3.4

  • bugfix: print out backtrace when debuggee fails

3.11 Changes between 0.3.2 and 0.3.3

  • depends on the "~> 0.10.3.x", rather then on 0.10.3 exactly to be compatible with future ruby-debug-base 0.10.3.x releases

3.12 Changes between 0.3.1 and 0.3.2

  • Dependency changed to ruby-debug-base-0.10.3 which fixes various bugs and contains bunch of RFEs

3.13 Changes between 0.3.0 and 0.3.1

  • Support for –load-mode option. Hotfix, likely workaround, for GlassFish debugging. Experimental, might be removed in the future. If option is used, it calls Debugger#debug_load with increment_start=true

3.14 Changes between 0.2.1 and 0.3.0

  • Catchpoint now answers with instead of just providing better control at frontend side
  • Dependency changed to ruby-debug-base-0.10.2
  • Bugfixes (see ChangeLog)

3.15 Changes between 0.2.0 and 0.2.1

  • Hotfixing/workarounding problem with connection on some Mac OSes, see Debugger timing out thread.

3.16 Changes between 0.1.10 and 0.2.0

3.16.1 New Features

3.16.2 Uncompatible Changes

  • catch off does not work anymore, since _ruby-debug-base_s support multiple catchpoints since 0.10.1, not just one. Note: however _ruby-debug-base_s in version 0.10.1 suffers with bug that it is not possible to remove catchpoints. So catchpoints removing must be workarounded in higher layers. The bug is fixed in _ruby-debug-base_s 0.10.2 and above.
You can’t perform that action at this time.