rgdb 0.0.1.245

data/ChangeLog

@@ -0,0 +1,5 @@
+= Revision history for rgdb
+
+== 0.0.1 [2008-06-19]
+
+* Birthday :-)

data/README

@@ -0,0 +1,43 @@
+= rgdb - GDB inside IRB
+
+== VERSION
+
+This documentation refers to rgdb version 0.0.1
+
+
+== DESCRIPTION
+
+Runs Jamis Buck's GDB wrapper inside an IRB session. Inspired by Jonathan
+Leighton's rgdb. But contrary to his solution, this one runs the IRB session
+in the context of the GDB::Ruby object.
+
+See
+* http://weblog.jamisbuck.org/2006/9/25/gdb-wrapper-for-ruby
+* http://dev.turnipspatch.com:9013/trac/browser/rgdb/trunk?rev=31
+
+
+== AUTHORS
+
+* Jens Wille <mailto:jens.wille@uni-koeln.de>
+
+
+== LICENSE AND COPYRIGHT
+
+Copyright (C) 2008 University of Cologne,
+Albertus-Magnus-Platz, 50932 Cologne, Germany
+
+rgdb is free software: you can redistribute it and/or modify it under the terms
+of the GNU General Public License as published by the Free Software Foundation,
+either version 3 of the License, or (at your option) any later version.
+
+rgdb is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with
+rgdb. If not, see <http://www.gnu.org/licenses/>.
+
+=== GDB
+
+The GDB library is copyright (C) 2006 Jamis Buck <mailto:jamis@37signals.com>,
+released in the public domain.

data/Rakefile

@@ -0,0 +1,24 @@
+require %q{lib/rgdb/version}
+
+begin
+  require 'hen'
+
+  Hen.lay! {{
+    :rubyforge => {
+      :project => %q{prometheus},
+      :package => %q{rgdb}
+    },
+
+    :gem => {
+      :version      => RGDB::VERSION,
+      :summary      => %q{GDB inside IRB},
+      :files        => FileList['lib/**/*.rb', 'bin/*'].to_a,
+      :extra_files  => FileList['[A-Z]*'].to_a,
+      :dependencies => %w[]
+    }
+  }}
+rescue LoadError
+  abort "Please install the 'hen' gem first."
+end
+
+### Place your custom Rake tasks here.

data/bin/rgdb

@@ -0,0 +1,46 @@
+#! /usr/bin/ruby
+
+#--
+###############################################################################
+#                                                                             #
+# rgdb -- GDB inside IRB                                                      #
+#                                                                             #
+# Copyright (C) 2008 University of Cologne,                                   #
+#                    Albertus-Magnus-Platz,                                   #
+#                    50932 Cologne, Germany                                   #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@uni-koeln.de>                                    #
+#                                                                             #
+# rgdb is free software; you can redistribute it and/or modify it under the   #
+# terms of the GNU General Public License as published by the Free Software   #
+# Foundation; either version 3 of the License, or (at your option) any later  #
+# version.                                                                    #
+#                                                                             #
+# rgdb is distributed in the hope that it will be useful, but WITHOUT ANY     #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS   #
+# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more       #
+# details.                                                                    #
+#                                                                             #
+# You should have received a copy of the GNU General Public License along     #
+# with rgdb. If not, see <http://www.gnu.org/licenses/>.                      #
+#                                                                             #
+###############################################################################
+#++
+
+$: << File.join(File.dirname(__FILE__), '..', 'lib')
+
+require 'rgdb'
+
+USAGE = "Usage: #{$0} [-h|--help] <pid>"
+
+case arg = ARGV.shift
+  when '-h', '--help'
+    puts USAGE
+  when '--version'
+    puts "rgdb v#{RGDB::VERSION}"
+  when /\A\d+\z/
+    RGDB.start(arg, __FILE__)
+  else
+    abort USAGE
+end

data/lib/gdb.rb

@@ -0,0 +1,413 @@
+# gdb.rb -- a simple wrapper around the GDB console to make inspecting
+# ruby processes less painful.
+# 
+# Author: Jamis Buck <jamis@37signals.com>
+#
+# This library is in the public domain. You are free to use it, modify
+# it, redistribute it, or ignore it, as you wish, with absolutely no
+# restrictions.
+#
+# CAVEATS:
+# * The current incarnation is not very error tolerant. If you run
+#   into problems, try running it with the $gdb_version variable set
+#   to true.
+# * Sometimes, the current implementation will kill the process it
+#   attaches to. I suspect it has something to do with garbage
+#   collection kicking in... I leave it as an exercise for the reader.
+#
+# See the bottom of this file for a handful of unit tests.
+
+require 'rbconfig'
+
+class Integer
+  # Monkey patch the Integer class to make it easier to compute
+  # word offsets. "5.ints" gives you the size (in bytes) of 5
+  # integers (words) on the current platform.
+  def ints
+    self * 1.size
+  end
+end
+
+# The GDB module provides a "raw", low-level, language-independent
+# interface to GDB (GDB::Interface) as well as a higher-level
+# interface specifically for Ruby programs (GDB::Ruby). Theoretically,
+# GDB::Interface could be extended to support other languages
+# than Ruby.
+module GDB
+  # This module is used to extend objects (like Strings) that originate
+  # in the remote instance. This lets us reuse them easily in subsequent
+  # calls to the remote instance.
+  module RemoteObject
+    attr_accessor :address
+  end
+
+  # The basic interface for wrapping GDB. You could concievably use this
+  # to interace with arbitrary remote processes, though it is best used
+  # by extending it to add platform-specific functionality.
+  class Interface
+    # Creates a new GDB::Interface that connects to process-id and
+    # executable.
+    def initialize(executable, pid)
+      @gdb = IO.popen("gdb -q #{executable} #{pid} 2>&1", "r+")
+      read_to_prompt
+    end
+
+    # Returns the (32-bit) integer at the given address
+    def int_at(address)
+      command("x/1dw #{address}").first.split(/:/).last.to_i
+    end
+
+    # Returns the string located at the given address
+    def string_at(address)
+      command("x/1s *#{address}").first.match(/"(.*)"/)[1]
+    end
+
+    # Returns the (8-bit) double precision floating point value at
+    # the given address.
+    def double_at(address)
+      command("x/1fg #{address}").first.split(/:/).last.to_f
+    end
+
+    # Executes the given command and returns the output as an array
+    # of lines. The command must be in GDB's syntax. If $gdb_verbose
+    # is true, this will print the command to STDOUT as well.
+    def command(cmd)
+      puts "(gdb) #{cmd}" if $gdb_verbose
+      @gdb.puts(cmd.strip)
+      read_to_prompt
+    end
+
+    # Call a C function. The +function+ parameter must include any
+    # parameters, all of which must be in valid C syntax. +opts+
+    # should include a <code>:return</code> key, which indicates
+    # what the expected return type of the function is:
+    #
+    # * <code>:int</code>
+    # * <code>:string</code>
+    # * <code>:void</code>
+    #
+    # Currently, the default is <code>:void</code>. The method
+    # returns a value of the expected type.
+    def call(function, opts={})
+      cast = case opts[:return]
+          when :int       then "int"
+          when :string    then "char*"
+          when nil, :void then "void"
+          else Kernel.raise "unsupported return type #{opts[:return].inspect}"
+        end
+
+      result = command("call (#{cast})#{function}")
+
+      case opts[:return]
+        when :int
+          if md = result.first.match(/= (-?\d+)/)
+            md[1].to_i
+          else
+            Kernel.raise "couldn't match integer result from #{result.inspect}"
+          end
+        when :string then result.first.match(/"(.*)"/)[1]
+        else nil
+      end
+    end
+
+    # Reads all lines emitted by GDB until a recognized prompt is encountered.
+    # Currently recognized prompts are:
+    #
+    # * "(gdb) "
+    # * " >"
+    #
+    # If your version of GDB uses a different kind of prompt, you should
+    # modify this method to include it.
+    #
+    # This method returns the lines read as an array. If $gdb_verbose is
+    # true, the lines will be echoed to STDOUT.
+    def read_to_prompt
+      lines = []
+      line = ""
+      while result = IO.select([@gdb])
+        next if result.empty?
+        c = @gdb.read(1)
+        break if c.nil?
+        line << c
+        break if line == "(gdb) " || line == " >"
+        if line[-1] == ?\n
+          lines << line
+          line = ""
+        end
+      end
+      puts lines.map { |l| "> #{l}" } if $gdb_verbose
+      lines
+    end
+
+    # A convenience method for executing GDB commands. Any unrecognized
+    # message is packaged up and invoked by GDB.
+    def method_missing(sym, *args)
+      cmd = sym.to_s
+      cmd << " #{args.join(' ')}" unless args.empty?
+      command(cmd)
+    end
+  end
+
+  # This is an extension of the Interface class that implements Ruby-specific
+  # functionality.
+  class Ruby < Interface
+    # A wrapper for a remote Object instance.
+    class Object
+      attr_reader :gdb
+      attr_reader :address
+
+      # Given a gdb instance and an address, determine what type of Object
+      # is at the given address, and return it.
+      def self.from_ptr(gdb, address)
+        case
+        when (address & 0x01) == 1 then address >> 1
+        when address == 0 then false
+        when address == 2 then true
+        when address == 4 then nil
+        when (address & 0xff) == 0x0e then gdb.id2name(address)
+        else
+          case (type = (gdb.int_at(address) & 0x3f))
+            when 2 then Object.new(gdb, address)
+            when 6 then gdb.double_at(address+2.ints)
+            when 7 then
+              string = gdb.string_at(address+3.ints)
+              string.extend(RemoteObject)
+              string.address = address
+              string
+            when 9 then Array.new(gdb, address)
+            when 11 then Hash.new(gdb, address)
+            else Object.new(gdb, address)
+          end
+        end
+      end
+
+      # Given a value, return an integer representing the VALUE of the
+      # object on the remote instance.
+      def to_gdb_value(value)
+        return value.address if value.respond_to?(:address)
+
+        case value
+          when Fixnum then ((value << 1)+1).to_s
+          when false  then "0"
+          when true   then "2"
+          when nil    then "4"
+          when String then gdb.call("rb_str_new2(#{value.inspect})", :return => :int).to_s
+          else Kernel.raise "not supported yet: #{value.class.name}"
+        end
+      end
+
+      # Creates a new remote Object reference for the given gdb instance
+      # and address.
+      def initialize(gdb, address)
+        @gdb = gdb
+        @address = address.to_i
+      end
+
+      # Invokes a method on the remote Object reference, returning the
+      # result as another Object.
+      def send(sym, *args)
+        command = "rb_funcall(#{address}, #{gdb.intern(sym.to_s)}, #{args.length}"
+        args = args.map { |arg| to_gdb_value(arg) }.join(", ")
+        command << ", #{args}" unless args.empty?
+        command << ")"
+
+        gdb.object_from(command) 
+      end
+
+      # A convenience method for #send
+      def method_missing(sym, *args)
+        send(sym, *args)
+      end
+    end
+
+    # A representation of a remote Array instance.
+    class Array < Object
+      # Query the length of the remote Array instance
+      def length
+        @length ||= gdb.int_at(address+2.ints)
+      end
+
+      # Return the object at the given index
+      def [](index)
+        gdb.object_from("rb_ary_entry(#{address}, #{index})")
+      end
+
+      # Iterate over each element of the remote array
+      def each
+        length.times { |idx| yield self[idx] }
+      end
+
+      # Convert the remote Array into a local (true) Array instance.
+      def to_ary
+        ary = []
+        each { |item| ary << item }
+        ary
+      end
+    end
+
+    # Wraps a remote Hash instance. All it really provides, though, is a
+    # way to build a local Hash instance that mirrors it.
+    class Hash < Object
+      # Return a ::Hash instance that has the same keys and values as
+      # the remote hash instance. Default values are not preserved.
+      def to_h
+        keys.to_ary.inject({}) do |hash, key|
+          hash[key] = self[key]
+          hash
+        end
+      end
+    end
+
+    # Create a new GDB::Ruby instance that attaches to the given
+    # process ID. By default, the same ruby interpreter is used
+    # as is running the GDB::Ruby script, but you can override
+    # that by using the second parameter.
+    def initialize(pid, ruby=nil)
+      ruby ||= File.join(Config::CONFIG["bindir"],
+        Config::CONFIG["RUBY_INSTALL_NAME"] +
+        Config::CONFIG["EXEEXT"])
+      @interns = {}
+      @names = {}
+      super(ruby, pid)
+    end
+
+    # Returns the symbol for the given numberic ID, using the remote
+    # environment.
+    def id2name(id)
+      @names[id] ||= call("rb_id2name(#{id >> 8})", :return => :string).to_sym
+    end
+
+    # Returns the numeric ID on the remote host that represents the
+    # internalized string.
+    def intern(string)
+      @interns[string] ||= call("rb_intern(#{string.inspect})", :return => :int)
+    end
+
+    # Executes the given command (C API) and returns the result as a wrapped
+    # GDB::Ruby::Object.
+    def object_from(cmd)
+      Object.from_ptr(self, call("#{cmd}", :return => :int))
+    end
+
+    # Evaluates the given string in the remote environment, returning the
+    # resulting object. Exceptions are silently ignored.
+    def eval(string)
+      object_from("rb_eval_string_protect(#{string.inspect}, (int*)0)")
+    end
+
+    # Returns a hash of the local variables that are active in the remote
+    # process, at it's current scope.
+    def local_variables
+      eval("local_variables").to_ary.inject({}) do |hash, name|
+        hash[name] = eval(name)
+        hash
+      end
+    end
+
+    # Returns an array of the backtrace of the remote process.
+    def backtrace
+      object_from("backtrace(-1)").to_ary
+    end
+
+    # Raises an exception in the remote process. The +exc+ parameter
+    # must be one of the core exception classes, like Exception,
+    # RuntimeError, and so forth.
+    def raise(exc, message)
+      call "rb_raise((int)rb_e#{exc}, #{message.inspect})"
+    end
+
+    # Returns a hash of the classes known to the remote instance,
+    # with the number of instances of each of the classes.
+    def object_space
+      eval("h={}; ObjectSpace.each_object { |obj| h[obj.class.name] ||= 0; h[obj.class.name] += 1 }; h").to_h
+    end
+  end
+end
+
+if __FILE__ == $0
+  require 'test/unit'
+
+  SENTINEL = "/tmp/gdb-ruby-test.pid"
+  FLAG_FILE = "/tmp/gdb-ruby-test.flag"
+
+  SCRIPT = <<EOS
+class ZxyVlqrt; end
+glooble = ZxyVlqrt.new
+
+def a(n)
+  b(n, n+1)
+end
+
+def b(x, y)
+  z = x + y
+  File.open("#{SENTINEL}", "w") { |f| f.write($$) }
+  loop { sleep 1 }
+end
+
+begin
+  a(5)
+rescue RuntimeError => e
+  File.open("#{FLAG_FILE}", "w") { |f| f.write(e.message) }
+end
+EOS
+
+  SCRIPT_NAME = "/tmp/gdb-ruby-test.rb"
+
+  class GDBRubyTest < Test::Unit::TestCase
+    def setup
+      File.open(SCRIPT_NAME, "w") { |f| f.write(SCRIPT) }
+      start_script
+      @gdb = GDB::Ruby.new(@pid)
+    end
+
+    def teardown
+      @gdb.quit
+      kill_script
+      File.delete(FLAG_FILE) rescue nil
+      File.delete(SENTINEL) rescue nil
+      File.delete(SCRIPT_NAME) rescue nil
+    end
+
+    def test_local_variables
+      expect = {"x" => 5, "y" => 6, "z" => 11}
+      assert_equal(expect, @gdb.local_variables)
+    end
+
+    def test_backtrace
+      expect = ["#{SCRIPT_NAME}:11:in `sleep'",
+        "#{SCRIPT_NAME}:11:in `b'",
+        "#{SCRIPT_NAME}:11:in `b'",
+        "#{SCRIPT_NAME}:5:in `a'",
+        "#{SCRIPT_NAME}:15"]
+
+      assert_equal expect, @gdb.backtrace
+    end
+
+    def test_raise
+      assert !File.exist?(FLAG_FILE)
+      @gdb.raise RuntimeError, "going boom"
+      assert File.exist?(FLAG_FILE)
+      assert_equal "going boom", File.read(FLAG_FILE)
+    end
+
+    def test_object_space
+      space = @gdb.object_space
+      assert_equal 1, space["ZxyVlqrt"]
+    end
+
+    private
+
+      def start_script
+        if (@pid = fork)
+          sleep 0.1 while !File.exist?(SENTINEL)
+          return
+        end
+
+        exec "ruby", SCRIPT_NAME
+      end
+
+      def kill_script
+        Process.kill("TERM", @pid)
+      end
+  end
+end