Next: Summary, Previous: (dir), Up: (dir)
This file contains specification of the protocol used by ruby-debug-ide.
Next: Specification, Previous: Top, Up: Top
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
Terms:
- 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
- Adding Breakpoint
- Deleting Breakpoint
- Enabling Breakpoint
- Disabling Breakpoint
- Condition
- Catchpoint
- Threads
- Frames
- Variables
Next: Deleting Breakpoint, Up: Commands
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"/>
Next: Enabling Breakpoint, Previous: Adding Breakpoint, Up: Commands
Command:
delete <breakpoint\_id>
Answer:
<breakpointDeleted no="<id>"/>
Example:
C: delete 2
A: <breakpointDeleted no="2"/>
Next: Disabling Breakpoint, Previous: Deleting Breakpoint, Up: Commands
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"/>
Next: Condition, Previous: Enabling Breakpoint, Up: Commands
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"/>
Next: Catchpoint, Previous: Disabling Breakpoint, Up: Commands
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"/>
Next: Threads, Previous: Condition, Up: Commands
Command:
catch <exception\_class\_name>
Answer:
<catchpointSet exception="<exception\_class\_name>"/>
Example:
C: catch ZeroDivisionError
A: <catchpointSet exception="ZeroDivisionError"/>
Next: Frames, Previous: Catchpoint, Up: Commands
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>
Next: Variables, Previous: Threads, Up: Commands
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>
Previous: Frames, Up: Commands
Example:
C: var local
A: <variables>
<variable name="array" kind="local" value="Array (2 element(s))" type="Array" hasChildren="true" objectId="-0x2418a904"/>
</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>
Previous: Commands, Up: Specification
Next: Suspension, Up: Events
Event example:
<breakpoint file="test.rb" line="1" threadId="1"/>
Next: Exception, Previous: Breakpoint, Up: Events
Event example:
<suspended file="/path/to/test.rb" line="2" threadId="1" frames="1"/>
Next: Message, Previous: Suspension, Up: Events
Event example:
<exception file="/path/to/test.rb" line="2" type="ZeroDivisionError" message="divided by 0" threadId="1"/>
Previous: Exception, Up: Events
Event example:
<message>some text</message>
<message debug='true'>some debug text</message>
Previous: Specification, Up: Top
Mentions also related changes in the ruby-debug-ide gem implementation.
- Fixes possible NoSuchMethodException
- added Debugger::start_server (ticket #25972)
- possibility to remove catchpoints
- bugfix: syntax error with Ruby 1.9
- bugfix: print out backtrace when debuggee fails
- 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
- Dependency changed to ruby-debug-base-0.10.3 which fixes various bugs and contains bunch of RFEs
- '–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
- 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
- bugfix: syntax error with Ruby 1.9
- bugfix: print out backtrace when debuggee fails
- 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
- Dependency changed to ruby-debug-base-0.10.3 which fixes various bugs and contains bunch of RFEs
- 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
- 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)
- Hotfixing/workarounding problem with connection on some Mac OSes, see Debugger timing out thread.
- 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.