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>