ruby-debug-ide protocol

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

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.

2. Specification

Terms:

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

2.1 Commands

2.1.1 Adding Breakpoint

Command:

  break <script>:<line_no>

Answer:

  <breakpointAdded no="<id>" location="<script>:<line_no>"/>

Example:

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

2.1.2 Deleting Breakpoint

Command:

  delete <breakpoint_id>

Answer:

  <breakpointDeleted no="<id>"/>

Example:

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

2.1.3 Enabling Breakpoint

Supported since ruby-debug-ide 0.2.0

Command:

  enable <breakpoint_id>

Answer:

  <breakpointEnabled bp_id="<id>"/>

Example:

  C: enable 2
  A: <breakpointEnabled bp_id="2"/>

2.1.4 Disabling Breakpoint

Supported since ruby-debug-ide 0.2.0

Command:

  disable <breakpoint_id>

Answer:

  <breakpointDisabled bp_id="<id>"/>

Example:

  C: disable 2
  A: <breakpointDisabled bp_id="2"/>

2.1.5 Setting Condition on Breakpoint

Supported since ruby-debug-ide 0.2.0

Command:

  condition <script>:<line_no>

Answer:

  <conditionSet bp_id="<id>"/>

Example:

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

2.1.6 Exception Breakpoint

Command:

  catch <exception_class_name>

Answer:

  <catchpointSet exception="<exception_class_name>"/>

Example:

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

2.1.7 Threads Listing

Command:

  thread list

Answer:

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

Example:

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

2.1.8 Frames Listing

Command:

  where

Answer:

  <frames>
    <frame no="<frame_no>" file="<script>" line="<line_no>" current="<boolean>"/>
    <frame no="<frame_no>" file="<script>" line="<line_no>"/>
    ...
  </frames>

Example:

  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" />
     </frames>

2.1.9 Variables Listing

2.1.9.1 Local Variables

Example:

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

2.1.9.2 Instance Variables

Example:

  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"/>
     </variables>

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

2.2 Events

2.2.1 Breakpoint

Event example:

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

2.2.2 Suspension

Event example:

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

2.2.3 Exception

Event example:

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

2.2.4 Message

Event example:

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

3. Changes

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

3.1 Changes between 0.4.5 and 0.4.6

• added Debugger::start_server (ticket #25972)

3.2 Changes between 0.4.4 and 0.4.5

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

3.3 Changes between 0.4.3 and 0.4.4

• bugfix: print out backtrace when debuggee fails

3.4 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.5 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.6 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 <trace> 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.7 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.8 Changes between 0.3.4 and 0.3.5

• bugfix: syntax error with Ruby 1.9

3.9 Changes between 0.3.3 and 0.3.4

• bugfix: print out backtrace when debuggee fails

3.10 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.11 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.12 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.13 Changes between 0.2.1 and 0.3.0

• Exception Breakpoint now answers with <conditionSet> instead of just <message> providing better control at frontend side
• Dependency changed to ruby-debug-base-0.10.2
• Bugfixes (see ChangeLog)

3.14 Changes between 0.2.0 and 0.2.1

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

3.15 Changes between 0.1.10 and 0.2.0

3.15.1 New Features

• Setting Condition on Breakpoint
• Enabling Breakpoint
• Disabling Breakpoint

3.15.2 Uncompatible Changes

• catch off does not work anymore, since ruby-debug-bases support multiple catchpoints since 0.10.1, not just one. Note: however ruby-debug-bases 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-bases 0.10.2 and above.

About This Document

This document was generated by emdot on May, 21 2009 using texi2html 1.78.

The buttons in the navigation panels have the following meaning:

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

• 1. Section One
  • 1.1 Subsection One-One
    • ...
  • 1.2 Subsection One-Two
    • 1.2.1 Subsubsection One-Two-One
    • 1.2.2 Subsubsection One-Two-Two
    • 1.2.3 Subsubsection One-Two-Three     <== Current Position
    • 1.2.4 Subsubsection One-Two-Four
  • 1.3 Subsection One-Three
    • ...
  • 1.4 Subsection One-Four

This document was generated by emdot on May, 21 2009 using texi2html 1.78.