needy_debugger 1.4.0

data/OLD_README

@@ -0,0 +1,122 @@
+*************************************************************
+
+  NOTE: For Ruby 1.9 installation instructions, please see:
+
+     http://wiki.github.com/mark-moseley/ruby-debug
+
+*************************************************************
+
+= ruby-debug
+
+== Overview
+
+ruby-debug is a fast implementation of the standard debugger debug.rb.
+The faster execution speed is achieved by utilizing a new hook in the
+Ruby C API.
+
+== Requirements
+
+ruby-debug requires Ruby 1.8.4 or higher.
+
+Unless you get the packages as a binary (Microsoft Windows binaries
+are sometimes available), you'll need a C compiler and Ruby
+development headers, and a Make program so the extension in
+ruby-debug-base can be compiled when it is installed.
+
+To install on Microsoft Windows, unless you run under cygwin or mingw
+you'll need Microsoft Visual C++ 6.0 also known as VC6.
+http://rubyforge.org/tracker/index.php?func=detail&aid=16774&group_id=1900&atid=7436
+suggests why.
+
+
+== Install
+
+ruby-debug is provided as a RubyGem.  To install:
+
+<tt>gem install ruby-debug</tt>
+
+This should also pull in <tt>ruby-debug-base</tt> as a dependency.
+
+(If you install ruby-debug-base explicitly, you can add in the <tt>--test</tt>
+option after "install" to have the regression test run before
+installing.)
+
+For Emacs support and the Reference Manual, get
+<tt>ruby-debug-extra</tt>.  This is not a RubyGem, you'll need a Make
+program and a POSIX shell. With this installed, run:
+
+  sh ./configure
+  make
+  make test # optional, but a good idea
+  sudo make install
+
+
+==== Install on MS Windows
+
+Compiling under cygwin or mingw works like it does on Unix. 
+
+* Have Microsoft Visual C++ 6.0 (VC6) installed - exactly that version.
+
+* Set the appropriate environment variables.
+
+* run `nmake'.
+
+* Copy ruby_debug.so to `win32'.
+
+* Go to the ruby_debug root.
+
+* rake win32_gem
+
+* The file is in named `rdebug-debug-base-0.10.0-mswin32.gem'.
+
+== Usage
+
+There are two ways of running ruby-debug.
+
+=== rdebug executable:
+
+$ rdebug <your-script>
+
+When you start your script this way, the debugger will stop at
+the first line of code in the script file. So you will be able 
+to set up your breakpoints.
+
+=== ruby-debug API
+
+The second way is to use the ruby-debug API to interrupt your
+code execution at run time.
+
+  require 'ruby-debug' ; Debugger.start
+  ...
+  def your_method
+    ...
+    debugger
+    ...
+  end
+
+or
+
+  require 'ruby-debug' ; 
+  Debugger.start do 
+    ...
+    debugger
+  end
+
+When Kernel#debugger method is executed, the debugger is activated
+and you will be able to inspect and step through your code.
+
+== Performance
+
+The <tt>debug.rb</tt> script that comes with the standard Ruby library uses
+<tt>Kernel#set_trace_func</tt> API. Implementing the debugger in pure Ruby has
+a negative impact on the speed of your program execution. This is
+because the Ruby interpreter creates a Binding object each trace call,
+even though it is not being used most of the time. ruby-debug moves
+most of the functionality for Binding access and for breakpoint
+testing to a native extension. Because this code is in C and because
+and can be selectively enabled or disabled, the overhead in running
+your program can be minimized.
+
+== License
+
+See LICENSE for license information.

data/README.md

@@ -0,0 +1,141 @@
+## Description
+A fork of ruby-debug(19) that works on 1.9.2 and 1.9.3 and installs easily for rvm/rbenv rubies.
+
+[![Build Status](https://travis-ci.org/cldwalker/debugger.png?branch=master)](https://travis-ci.org/cldwalker/debugger)
+
+## Install
+
+    $ gem install debugger
+
+    # If install fails, try passing headers path
+    $ gem install debugger -- --with-ruby-include=PATH_TO_HEADERS
+
+For Windows install instructions, see OLD\_README.
+
+
+## Supported Rubies
+On install, debugger tries to find your ruby's headers. If it's unable to find them and your ruby is
+a patch release, it will use headers included with
+[debugger-ruby_core_source](https://github.com/cldwalker/debugger-ruby_core_source).  For the list
+of rubies supported by debugger [see
+here](https://github.com/cldwalker/debugger-ruby_core_source/tree/master/lib/debugger/ruby_core_source).
+*If your ruby is not an official patch release i.e. head, dev or an rc, you are responsible for
+having headers and setting them with --with-ruby-include.*
+
+## Usage
+
+Wherever you need a debugger, simply:
+
+```ruby
+require 'debugger'; debugger
+```
+
+To use with bundler, drop in your Gemfile:
+
+    gem 'debugger'
+
+### Configuration
+
+At initialization time, debugger loads config files, executing their lines
+as if they were actual commands a user has typed. config files are loaded
+from two locations:
+
+* ~/.rdebugrc (~/rdebug.ini for windows)
+* $PWD/.rdebugrc ($PWD/rdebug.ini for windows)
+
+Here's a common configuration (yeah, I should make this the default):
+
+    set autolist
+    set autoeval
+    set autoreload
+
+To see debugger's current settings, use the `set` command.
+
+### Using Commands
+
+For a list of commands:
+
+    (rdb: 1) help
+
+Most commands are described in rdebug's man page
+
+    $ gem install gem-man
+    $ man rdebug
+
+### More documentation
+
+Some thorough documentation of debugger is found with [this bashdb
+tutorial](http://bashdb.sourceforge.net/ruby-debug.html). For emacs and debugger
+usage, see [another bashdb
+tutorial](http://bashdb.sourceforge.net/ruby-debug/rdebug-emacs.html)
+
+## Reason for Fork
+
+* ruby-debug19 maintainer isn't maintaining:
+  * Despite patches from ruby core, no gem release in 2+ years! - 9/1/09.
+  * Requests to release a known working 1.9.3 version have been ignored.
+  * Doesn't respond to rubyforge issues and doesn't have github issues open.
+* Current install is painful. Requires either [manually downloading gems from rubyforge](
+  http://blog.wyeworks.com/2011/11/1/ruby-1-9-3-and-ruby-debug) and installing with compiler flags
+  or [recompiling
+  ruby](http://blog.sj26.com/post/12146951658/updated-using-ruby-debug-on-ruby-1-9-3-p0).
+* We need a decent ruby debugger for future rubies!
+
+## What's different from ruby-debug19
+
+* Major
+  * Works on 1.9.2 and 1.9.3
+    * 1.9.2 points to ruby-debug-base19-0.11.25 headers
+    * 1.9.3 points to ruby-debug-base19-0.11.26 headers
+  * Install painlessly for rvm and rbenv rubies i.e. no compiler flags needed
+  * No downloading ruby source during install - was behavior of old ruby_core_source dependency
+  * Fix LocalJumpError caused by using proc in extconf.rb
+  * Fix where command failing at top level
+  * A new and improved test suite
+  * Passing tests are up on travis-ci
+* Minor
+  * The gem name matches the module namespace, Debugger, and main required file, debugger.
+  * ruby-debug-base19 and ruby-debug19 are released as one gem
+  * Rake tasks have been updated
+  * No more $LOAD_PATH manipulation or runtime code outside of lib
+  * man page available via gem-man
+
+## Issues
+Please report them [on github](http://github.com/cldwalker/debugger/issues).
+
+## Known Issues
+* 2.0.0 support is only partially working and the test suite dies before it can finish.
+* If you place a debugger call at the end of a block, debugging will start at the next step and
+  outside of your block. A simple work-around is to place a meaningless step (i.e. puts "STAY")
+  at the end of your block and before debugger.
+
+## Contributing
+[See here](http://tagaholic.me/contributing.html) for contribution policies.
+Let's keep this working for the ruby community!
+
+## Related projects
+
+* [debugger-completion](https://github.com/cldwalker/debugger-completion) - autocompletion for
+  debugger commands and more
+* [debugger-pry](https://github.com/pry/debugger-pry) - using pry within debugger
+* [pry-debugger](https://github.com/nixme/pry-debugger) - using debugger within pry
+* [ruby-debug-passenger](https://github.com/davejamesmiller/ruby-debug-passenger) - rake task to
+  restart Passenger with debugger connected
+* [jruby-debug](https://github.com/jruby/jruby-debug)
+* [rb-trepanning](https://github.com/rocky/rb-trepanning) - rewrite of ruby-debug that requires a
+  patched ruby
+
+## Credits
+
+* Thanks to the original authors: Kent Sibilev and Mark Moseley
+* Thanks to astashov for bringing in a new and improved test suite and various bug fixes.
+* Thanks to windwiny for porting to 2.0.0
+* Contributors: ericpromislow, jnimety, adammck, hipe, FooBarWidget, aghull
+* Fork started on awesome @relevance fridays!
+
+## TODO
+
+* Fix test/test-*.rb
+* Port some of bashdb's docs
+* Use ~/.debuggerrc and bin/debugger and gracefully deprecate rdebug*
+* Work with others willing to tackle jruby, rubinius or windows support

data/Rakefile

@@ -0,0 +1,78 @@
+# -*- Ruby -*-
+require 'rubygems/package_task'
+require 'rake/testtask'
+require 'rake/extensiontask'
+
+Rake::ExtensionTask.new('ruby_debug')
+
+SO_NAME = "ruby_debug.so"
+
+desc "Run new MiniTest tests."
+task :test do
+  Rake::TestTask.new(:test) do |t|
+    t.test_files = FileList["test/*_test.rb"]
+    t.verbose = true
+  end
+end
+
+desc "Test everything - same as test."
+task :check => :test
+
+desc "Create the core ruby-debug shared library extension"
+task :lib do
+  Dir.chdir("ext") do
+    system("#{Gem.ruby} extconf.rb && make")
+  end
+end
+
+desc "Compile Emacs code"
+task :emacs => "emacs/rdebug.elc"
+file "emacs/rdebug.elc" => ["emacs/elisp-comp", "emacs/rdebug.el"] do
+  Dir.chdir("emacs") do
+    system("./elisp-comp ./rdebug.el")
+  end
+end
+
+base_spec = eval(File.read('debugger.gemspec'), binding, 'debugger.gemspec')
+# Rake task to build the default package
+Gem::PackageTask.new(base_spec) do |pkg|
+  pkg.need_tar = true
+end
+
+# Windows specification
+win_spec = base_spec.clone
+win_spec.extensions = []
+## win_spec.platform = Gem::Platform::WIN32 # deprecated
+win_spec.platform = 'mswin32'
+win_spec.files += ["lib/#{SO_NAME}"]
+
+desc "Create Windows Gem"
+task :win32_gem do
+  # Copy the win32 extension the top level directory
+  current_dir = File.expand_path(File.dirname(__FILE__))
+  source = File.join(current_dir, "ext", "win32", SO_NAME)
+  target = File.join(current_dir, "lib", SO_NAME)
+  cp(source, target)
+
+  # Create the gem, then move it to pkg.
+  Gem::Builder.new(win_spec).build
+  gem_file = "#{win_spec.name}-#{win_spec.version}-#{win_spec.platform}.gem"
+  mv(gem_file, "pkg/#{gem_file}")
+
+  # Remove win extension from top level directory.
+  rm(target)
+end
+
+desc "Remove built files"
+task :clean do
+  cd "ext" do
+    if File.exists?("Makefile")
+      sh "make clean"
+      rm  "Makefile"
+    end
+    derived_files = Dir.glob(".o") + Dir.glob("*.so")
+    rm derived_files unless derived_files.empty?
+  end
+end
+
+task :default => :test

data/bin/rdebug

@@ -0,0 +1,397 @@
+#!/usr/bin/env ruby
+
+#=== Summary
+#
+#A command-line front-end to the Ruby debugger, <tt>debugger</tt>, the
+#Fast Ruby Debugger.
+#
+#Command invocation:
+#
+#   rdebug [options] [--] [script-options] ruby-script-to-debug
+#   rdebug [options] [script-options] [--client]
+#   rdebug [--version | --help]
+#
+#=== Options
+#
+#<tt>-A | --annotate</tt> <i>level</i>::
+#    Set gdb-style annotation to <i>level</i>, a number.  Additional
+#    information is output automatically when program state is
+#    changed. This can be used by front-ends such as GNU Emacs to post
+#    this updated information without having to poll for it.
+#
+#<tt>--client</tt>::
+#    Connect to a remote debugger. Used with another rdebug invocation
+#    using <tt>--server</tt>.  See also <tt>--host</tt> and
+#    <tt>--cport</tt> options
+#
+#<tt>--cport=</tt><i>port</i>::
+#    Use port <i>port</i> for access to debugger control.
+#
+#<tt>-d | --debug</tt>::
+#    Set $DEBUG true.
+#
+#<tt>--emacs</tt>::
+#    Activates full GNU Emacs mode. Is the equivalent of setting the
+#    options <tt>--emacs-basic --annotate=3 --no-stop --no-control
+#    --post-mortem</tt>.
+#
+#<tt>--emacs-basic</tt>::
+#     Activates GNU Emacs mode. Debugger prompts are prefaced with two
+#     octal 032 characters.
+#
+#<tt>-h | --host=</tt><i>host</i>::
+#     Use host name <i>host</i> for remote debugging.
+#
+#<tt>-I | --include</tt> <i>path</i>
+#     Add <i>path</i> to <tt>$LOAD_PATH</tt>
+#
+#<tt>-m | --post-mortem</tt>::
+#     Activate post-mortem mode.
+#
+#<tt>--no-control</tt>::
+#      Do not automatically start control thread.
+#
+#<tt>--no-stop</tt>::
+#      Do not stop when script is loaded.
+#
+#<tt>-p | --port=PORT</tt>::
+#      Host name used for remote debugging.
+#
+#<tt>-r | --require</tt><i>script</i>::
+#      Require the library, before executing your script.
+#
+#<tt>--script</tt> <i>file</i>::
+#      Run debugger script file <i>file</i>
+#
+#<tt>-x | --trace</tt>::
+#      Show lines before executing them.
+#
+#<tt>--no-quit</tt>::
+#      Do not quit when script terminates. Instead rerun the
+#      program.
+#
+#<tt>--version</tt>::
+#      Show the version number and exit.
+#
+#<tt>--verbose</tt>::
+#      Turn on verbose mode.
+#
+#<tt>--v</tt>::
+#      Print the version number, then turn on verbose mode if
+#      a script name is given. If no script name is given
+#     just exit after printing the version number.
+#
+#<tt>--nx</tt>::
+#      Don’t execute commands  found in any initialization
+#      files, e.g. <tt>.rdebugrc</tt>.
+#
+#<tt>--keep-frame-binding</tt>::
+#      Keep frame bindings.
+#
+#<tt>--script=</tt><i>file</i>::
+#      Name of the script file to run
+#
+#<tt>-s | --server</tt>::
+#      Listen for remote connections. Another rdebug session
+#      accesses using the <tt>--client</tt>  option. See also the
+#      <tt>--host</tt>, <tt>--port</tt> and <tt>--cport</tt> options
+#
+#<tt>-w | --wait</tt>::
+#      Wait for a client connection; implies <tt>-s</tt> option.
+#
+#<tt>--help</tt>::
+#      Show invocation help and exit.
+
+require 'optparse'
+require 'ostruct'
+require 'debugger'
+
+def debug_program(options)
+  # Make sure Ruby script syntax checks okay.
+  # Otherwise we get a load message that looks like rdebug has
+  # a problem.
+  output = `ruby -c "#{Debugger::PROG_SCRIPT}" 2>&1`
+  if $?.exitstatus != 0 and RUBY_PLATFORM !~ /mswin/
+    puts output
+    exit $?.exitstatus
+  end
+  print "\032\032starting\n" if Debugger.annotate and Debugger.annotate > 2
+
+  # Record where we are we can know if the call stack has been
+  # truncated or not.
+  Debugger.start_sentinal=caller(0)[1]
+
+  bt = Debugger.debug_load(Debugger::PROG_SCRIPT, options.stop, false)
+  if bt
+    print bt.backtrace.map{|l| "\t#{l}"}.join("\n"), "\n"
+    print "Uncaught exception: #{bt}\n"
+  end
+end
+
+# Do a shell-like path lookup for prog_script and return the results.
+# If we can't find anything return prog_script.
+def whence_file(prog_script)
+  if prog_script.index(File::SEPARATOR)
+    # Don't search since this name has path separator components
+    return prog_script
+  end
+  for dirname in ENV['PATH'].split(File::PATH_SEPARATOR) do
+    prog_script_try = File.join(dirname, prog_script)
+    return prog_script_try if File.exist?(prog_script_try)
+  end
+  # Failure
+  return prog_script
+end
+
+options = OpenStruct.new(
+  'annotate'           => Debugger.annotate,
+  'client'             => false,
+  'control'            => true,
+  'cport'              => Debugger::PORT + 1,
+  'host'               => nil,
+  'quit'               => true,
+  'no_rewrite_program' => false,
+  'stop'               => true,
+  'nx'                 => false,
+  'port'               => Debugger::PORT,
+  'restart_script'     => nil,
+  'script'             => nil,
+  'server'             => false,
+  'tracing'            => false,
+  'verbose_long'       => false,
+  'wait'               => false
+)
+
+def process_options(options)
+  program = File.basename($0)
+  opts = OptionParser.new do |opts|
+    opts.banner = <<EOB
+#{program} #{Debugger::VERSION}
+Usage: #{program} [options] <script.rb> -- <script.rb parameters>
+EOB
+    opts.separator ""
+    opts.separator "Options:"
+    opts.on("-A", "--annotate LEVEL", Integer, "Set annotation level") do
+      |annotate|
+        Debugger.annotate = annotate
+    end
+    opts.on("-c", "--client", "Connect to remote debugger") do
+      options.client = true
+    end
+    opts.on("--cport PORT", Integer, "Port used for control commands") do
+      |cport|
+      options.cport = cport
+    end
+    opts.on("-d", "--debug", "Set $DEBUG=true") {$DEBUG = true}
+    opts.on("--emacs LEVEL", Integer,
+            "Activates full Emacs support at annotation level LEVEL") do
+      |level|
+      Debugger.annotate = level.to_i
+      ENV['EMACS'] = '1'
+      ENV['COLUMNS'] = '120' if ENV['COLUMNS'].to_i < 120
+      options.control = false
+      options.quit = false
+    end
+    opts.on('--emacs-basic', 'Activates basic Emacs mode') do
+      ENV['EMACS'] = '1'
+    end
+    opts.on('-h', '--host HOST', 'Host name used for remote debugging') do
+      |host|
+      options.host = host
+    end
+    opts.on('-I', '--include PATH', String, 'Add PATH to $LOAD_PATH') do |path|
+      $LOAD_PATH.unshift(path)
+    end
+    opts.on('--no-control', 'Do not automatically start control thread') do
+      options.control = false
+    end
+    opts.on('--no-quit', 'Do not quit when script finishes') do
+      options.quit = false
+    end
+    opts.on('--no-rewrite-program',
+            'Do not set $0 to the program being debugged') do
+      options.no_rewrite_program = true
+    end
+    opts.on('--no-stop', 'Do not stop when script is loaded') do
+      options.stop = false
+    end
+    opts.on('-nx', 'Not run debugger initialization files (e.g. .rdebugrc') do
+      options.nx = true
+    end
+    opts.on('-p', '--port PORT', Integer, 'Port used for remote debugging') do
+      |port|
+      options.port = port
+    end
+    opts.on('-r', '--require SCRIPT', String,
+            'Require the library, before executing your script') do |name|
+      if name == 'debug'
+        puts "debugger is not compatible with Ruby's 'debug' library. This option is ignored."
+      else
+        require name
+      end
+    end
+    opts.on('--restart-script FILE', String,
+            'Name of the script file to run. Erased after read') do
+      |restart_script|
+      options.restart_script = restart_script
+      unless File.exists?(options.restart_script)
+        puts "Script file '#{options.restart_script}' is not found"
+        exit
+      end
+    end
+    opts.on('--script FILE', String, 'Name of the script file to run') do
+      |script|
+      options.script = script
+      unless File.exists?(options.script)
+        puts "Script file '#{options.script}' is not found"
+        exit
+      end
+    end
+    opts.on('-s', '--server', 'Listen for remote connections') do
+      options.server = true
+    end
+    opts.on('-w', '--wait', 'Wait for a client connection, implies -s option') do
+      options.wait = true
+    end
+    opts.on('-x', '--trace', 'Turn on line tracing') {options.tracing = true}
+    opts.separator ''
+    opts.separator 'Common options:'
+    opts.on_tail('--help', 'Show this message') do
+      puts opts
+      exit
+    end
+    opts.on_tail('--version',
+                 'Print the version') do
+      puts "debugger #{Debugger::VERSION}"
+      exit
+    end
+    opts.on('--verbose', 'Turn on verbose mode') do
+      $VERBOSE = true
+      options.verbose_long = true
+    end
+    opts.on_tail('-v',
+                 'Print version number, then turn on verbose mode') do
+      puts "debugger #{Debugger::VERSION}"
+      $VERBOSE = true
+    end
+  end
+  return opts
+end
+
+# What file is used for debugger startup commands.
+unless defined?(OPTS_INITFILE)
+  if RUBY_PLATFORM =~ /mswin/
+    # Of course MS Windows has to be different
+    OPTS_INITFILE = 'rdbopt.ini'
+    HOME_DIR =  (ENV['HOME'] ||
+                 ENV['HOMEDRIVE'].to_s + ENV['HOMEPATH'].to_s).to_s
+  else
+    OPTS_INITFILE = '.rdboptrc'
+    HOME_DIR = ENV['HOME'].to_s
+  end
+end
+begin
+  initfile = File.join(HOME_DIR, OPTS_INITFILE)
+  eval(File.read(initfile)) if
+    File.exist?(initfile)
+rescue
+end
+
+opts = process_options(options)
+begin
+  if not defined? Debugger::ARGV
+    Debugger::ARGV = ARGV.clone
+  end
+  rdebug_path = File.expand_path($0)
+  if RUBY_PLATFORM =~ /mswin/
+    rdebug_path += '.cmd' unless rdebug_path =~ /\.cmd$/i
+  end
+  Debugger::RDEBUG_SCRIPT = rdebug_path
+  Debugger::RDEBUG_FILE = __FILE__
+  Debugger::INITIAL_DIR = Dir.pwd
+  opts.parse! ARGV
+rescue StandardError => e
+  puts opts
+  puts
+  puts e.message
+  exit(-1)
+end
+
+if options.client
+  Debugger.start_client(options.host, options.port)
+else
+  if ARGV.empty?
+    exit if $VERBOSE and not options.verbose_long
+    puts opts
+    puts
+    puts 'Must specify a script to run'
+    exit(-1)
+  end
+
+  # save script name
+  prog_script = ARGV.shift
+  prog_script = whence_file(prog_script) unless File.exist?(prog_script)
+  Debugger::PROG_SCRIPT = File.expand_path prog_script
+
+  # install interruption handler
+  trap('INT') { Debugger.interrupt_last }
+
+  # set options
+  Debugger.wait_connection = options.wait
+
+  if options.server
+    # start remote mode
+    Debugger.start_remote(options.host, [options.port, options.cport]) do
+      # load initrc script
+      Debugger.run_init_script(StringIO.new) unless options.nx
+    end
+    debug_program(options)
+  else
+    # Set up trace hook for debugger
+    Debugger.start
+    # start control thread
+    Debugger.start_control(options.host, options.cport) if options.control
+
+    # load initrc script (e.g. .rdebugrc)
+    Debugger.run_init_script(StringIO.new) unless options.nx
+
+    # run restore-settings startup script if specified
+    if options.restart_script
+      require 'fileutils'
+      Debugger.run_script(options.restart_script)
+      FileUtils.rm(options.restart_script)
+    end
+
+    # run startup script if specified
+    if options.script
+      Debugger.run_script(options.script)
+    end
+
+    options.stop = false if options.tracing
+    Debugger.tracing = options.tracing
+
+    if !options.quit
+      if Debugger.started?
+        until Debugger.stop do end
+      end
+      begin
+        debug_program(options)
+      rescue SyntaxError
+        puts $!.backtrace.map{|l| "\t#{l}"}.join("\n")
+        puts "Uncaught Syntax Error\n"
+      rescue
+        print $!.backtrace.map{|l| "\t#{l}"}.join("\n"), "\n"
+        print "Uncaught exception: #{$!}\n"
+      end
+      print "The program finished.\n" unless
+        Debugger.annotate.to_i > 1 # annotate has its own way
+      interface = Debugger::LocalInterface.new
+      # Not sure if ControlCommandProcessor is really the right
+      # thing to use. CommandProcessor requires a state.
+      processor = Debugger::ControlCommandProcessor.new(interface)
+      processor.process_commands
+    else
+      debug_program(options)
+    end
+  end
+end