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 bellow.

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

TBD: return valid answer

Command:

  catch <exception_class_name>

Answer:

  <message>Set catchpoint <exception_class_name>.</message>

Example:

  C: catch ZeroDivisionError
  A: <message>Set catchpoint ZeroDivisionError.</message>

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

3. Changes

3.1 Changes between 0.2.0 and 0.2.1

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

3.2 Changes between 0.1.10 and 0.2.0

3.2.1 New Features

• Setting Condition on Breakpoint
• Enabling Breakpoint
• Disabling Breakpoint

3.2.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 Martin Krauskopf on July, 31 2008 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 Martin Krauskopf on July, 31 2008 using texi2html 1.78.