agardiner / rubinius-debug-base

This is the README for the Rubinius implementation of ruby-debug-base.
This provides the base level debugging functionality that can then be
used by ruby-debug to debug Ruby scripts on Rubinius.
 
Although Rubinius provides a built-in debugger, there are advantages
in providing support for an existing Ruby debugger such as ruby-debug:
 - ruby-debug is a mature Ruby debugger, with substantially more functionality
   than the Rubinius debugger (at least at this point)
 - ruby-debug is the standard debugging framework used by Ruby IDEs such
   as NetBeans and Aptana/RadRails. By allowing ruby-debug to run on Rubinius,
   we gain the ability to debug Ruby scripts on Rubinius via these IDEs.
 
== Installation
 
To install ruby-debug on Rubinius, use the following steps:
1. Build the Rubinius ruby-debug-base gem:
	rake gem
 
2. Install ruby-debug under Rubinius:
	# from your Rubinius install directory
	shotgun/rubinius gem install ruby-debug --ignore-dependencies
	shotgun/rubinius gem install columnize
 
3. Install the Rubinius ruby-debug-base gem:
	shotgun/rubinius gem install <path to Rubinius ruby-debug-base gem>
 
== Ruby-debug patches
 
At present, there are a couple of issues in ruby-debug that must be patched 
in order to get ruby-debug to work on Rubinius. One of these appears to be a
minor syntax issue, and the other is an issue that is pending resolution in
Rubinius.
 
1. At line 74 of cli/ruby-debug/command.rb, replace the definition of 
settings_map with the following code (to work around a Rubinius issue related to 
metaclasses and class variables):
 
      def settings_map
        unless class_variable_defined? :@@settings_map
          @@settings_map = {}
        end
        @@settings_map
      end
 
2. At line 32 of cli/ruby-debug/commands/list.rb, add a space between the - and 1,
i.e. change the line so that it reads as follows:
 
        e = b + listsize - 1
 
The Rubinius parser regards the existing code as a unary minus, which leads it to
interpret this code as a syntax error.
 
== Running ruby-debug on Rubinius
 
To run ruby-debug on rubinius, you can use the following:
 
	shotgun/rubinius bin/rdebug <path to file to debug>