ruby-debug 0.9.3 → 0.10.0

data/AUTHORS

@@ -4,3 +4,4 @@ Kent Sibilev
 Contributers:
 Markus Barchfeld
 R. Bernstein
+Anders Lindgren

data/CHANGES

@@ -1,3 +1,44 @@
+0.10.0
+- '-r' option can be used to require additional libraries.
+- --noquit option added to stay in debugger when the program exits
+- gdb-like --annotate option added. Can be used by front-ends to get information
+  without polling
+- Fixed 'var const' command. Issue #10847.
+- Using pretty-print for all var commands.
+- Better error reporting for commands that require a numeric argument.
+- Fixed Kernel#binding_n method
+- Add option -d ($DEBUG = true) and --verbose. Make -v work like ruby.
+- Remove debugger messages caused when warnings are turned on.
+- "info" and "show" commands added. "set" made more like gdb's
+  set. subcommands can be abbreviated and are case insensitive.
+- restart program if it terminates normally and we've got a tty and 
+  we stop on the first statement. 
+- help is in tidy column format. method lists are shown that way as well.
+  the "width" setting ("set/show width") is used  for the line width
+- stack traces now show parameter names and types. "info args" lists just
+  the parameters (with the most recent values, not the values at call time).
+- post-mortem "exit" bug fixed. 
+- More Emacs-friendly: rdebug-track.el will track location inside an Emacs
+  shell. Emacs position information is shown in breakpoints and catchpoints
+  similar to gdba. Commands to position in another window a unit test traceback
+  or ruby traceback. Much more work invisioned for Emacs.
+- INCOMPATIBLE CHANGE: "break" now sets a breakpoint on the current line
+  (same as gdb). Use "info break" for a list of breakpoints.
+- INCOMPATIBLE CHANGE: "script" command removed. Use "source" command instead
+  (same as gdb).
+- Run .rdebugrc on Debugger.start. Look for a file in the current directory and
+  run that instead the one in $HOME if that exists. Again, inspired and compatible
+  with gdb.
+- Changes compatible with Ruby 1.9. NOTE: this debugger will NOT work with
+  Ruby 1.9
+- leaving irb shows position same as entering debugger; "list" position
+  is also cleared when leaving irb
+- help "foo" gives message "Undefined command "foo" rather than a list
+  of help commands. (Message test is gdb's)
+- Add set linetrace+ - similar step+ for linetrace
+- Start unit tests.
+- Start a reference guide.
+
 0.9.3
 - Fixed if..elsif..end stepping.
 - From irb session Ctrl-C or 'cont' command continues execution without showing the debugger prompt.

data/README

@@ -9,9 +9,10 @@ The faster execution speed is achieved by utilizing a new hook Ruby C API.
 
 ruby-debug requires Ruby 1.8.4 or higher.
 
-If you are running Linux or Unix you'll need a C compiler so the extension
-can be compiled when it is installed.
-
+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.
 
 == Install
 
@@ -19,6 +20,18 @@ 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.
+
+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:
+
+<pre>
+  sh ./configure
+  make
+  make install
+</pre>
+
 == Usage
 
 There are two ways of running ruby-debug.
@@ -34,9 +47,9 @@ to set up your breakpoints.
 === ruby-debug API
 
 The second way is to use the ruby-debug API to interrupt your
-code execution at runtime.
+code execution at run time.
 
-  require 'ruby-debug'
+  require 'ruby-debug' ; Debugger.start
   ...
   def your_method
     ...
@@ -49,14 +62,15 @@ and you will be able to inspect and step through your code.
 
 == Performance
 
-The debug.rb script that comes with the standard library uses 
-Kernel#set_trace_func API. This way it is possible to implement
-the debugger in pure Ruby, but has a negative effect on the speed 
-of your program execution. For each trace call Ruby interpreter 
-creates a Binding object, even though it is not being used most
-of the time. ruby-debug library moves most of the functionality 
-of debug.rb to a native extension, this way significantly improving
-the execution of your program.
+The debug.rb script that comes with the standard Ruby library uses
+Kernel#set_trace_func 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
 

data/Rakefile

@@ -0,0 +1,220 @@
+#!/usr/bin/env rake
+# -*- Ruby -*-
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/testtask'
+
+SO_NAME = "ruby_debug.so"
+
+# ------- Default Package ----------
+RUBY_DEBUG_VERSION = open("ext/ruby_debug.c"){|f| f.grep(/^#define DEBUG_VERSION/).first[/"(.+)"/,1]}
+
+COMMON_FILES = FileList[
+  'AUTHORS',
+  'CHANGES',
+  'LICENSE',
+  'README',
+  'Rakefile',
+]                        
+
+CLI_TEST_FILE_LIST = 'test/**/*test-*.rb'
+CLI_FILES = COMMON_FILES + FileList[
+  "cli/**/*",
+  'ChangeLog',
+  'bin/*',
+  'doc/rdebug.1',
+  'test/**/*.cmd',
+  'test/**/*.right',
+  'test/**/gcd.rb',
+  'test/**/helper.rb',
+  'test/**/info-var-bug.rb',
+  'test/**/tdebug.rb',
+  'test/**/test-*.cmd',
+  'runner.sh',
+   CLI_TEST_FILE_LIST,                                    
+]
+
+BASE_TEST_FILE_LIST = 'test/test-ruby-debug-base.rb'
+BASE_FILES = COMMON_FILES + FileList[
+  'lib/**/*',
+  'ext/ChangeLog',
+  'ext/ruby_debug.c',
+  'ext/extconf.rb',
+  'ext/win32/*',
+  BASE_TEST_FILE_LIST,
+]
+
+desc "Test everything."
+test_task = task :test => :lib do 
+  Rake::TestTask.new(:test) do |t|
+    t.libs << ['./ext', './lib', './cli']
+    t.pattern = CLI_TEST_FILE_LIST
+    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
+
+desc "Create a GNU-style ChangeLog via svn2cl"
+task :ChangeLog do
+  system("svn2cl --authors=svn2cl_usermap svn://rubyforge.org/var/svn/ruby-debug/trunk")
+  system("svn2cl --authors=svn2cl_usermap svn://rubyforge.org/var/svn/ruby-debug/trunk/ext -o ext/ChangeLog")
+  system("svn2cl --authors=svn2cl_usermap svn://rubyforge.org/var/svn/ruby-debug/trunk/lib -o lib/ChangeLog")
+end
+
+# Base GEM Specification
+base_spec = Gem::Specification.new do |spec|
+  spec.name = "ruby-debug-base"
+  
+  spec.homepage = "http://rubyforge.org/projects/ruby-debug/"
+  spec.summary = "Fast Ruby debugger - core component"
+  spec.description = <<-EOF
+ruby-debug is a fast implementation of the standard Ruby debugger debug.rb.
+It is implemented by utilizing a new Ruby C API hook. The core component 
+provides support that front-ends can build on. It provides breakpoint 
+handling, bindings for stack frames among other things.
+EOF
+
+  spec.version = RUBY_DEBUG_VERSION
+
+  spec.author = "Kent Sibilev"
+  spec.email = "ksibilev@yahoo.com"
+  spec.platform = Gem::Platform::RUBY
+  spec.require_path = "lib"
+  spec.extensions = ["ext/extconf.rb"]
+  spec.autorequire = "ruby-debug-base"
+  spec.files = BASE_FILES.to_a  
+
+  spec.required_ruby_version = '>= 1.8.2'
+  spec.date = Time.now
+  spec.rubyforge_project = 'ruby-debug'
+  
+  spec.test_files = FileList[BASE_TEST_FILE_LIST]
+  
+  # rdoc
+  spec.has_rdoc = true
+  spec.extra_rdoc_files = ['README', 'ext/ruby_debug.c']
+end
+
+cli_spec = Gem::Specification.new do |spec|
+  spec.name = "ruby-debug"
+  
+  spec.homepage = "http://rubyforge.org/projects/ruby-debug/"
+  spec.summary = "Command line interface (CLI) for ruby-debug-base"
+  spec.description = <<-EOF
+A generic command line interface for ruby-debug.
+EOF
+
+  spec.version = RUBY_DEBUG_VERSION
+
+  spec.author = "Kent Sibilev"
+  spec.email = "ksibilev@yahoo.com"
+  spec.platform = Gem::Platform::RUBY
+  spec.require_path = "cli"
+  spec.bindir = "bin"
+  spec.executables = ["rdebug"]
+  spec.autorequire = "ruby-debug"
+  spec.files = CLI_FILES.to_a
+
+  spec.required_ruby_version = '>= 1.8.2'
+  spec.date = Time.now
+  spec.rubyforge_project = 'ruby-debug'
+  spec.add_dependency('ruby-debug-base', RUBY_DEBUG_VERSION)
+  
+  # FIXME: work out operational logistics for this
+  # spec.test_files = FileList[CLI_TEST_FILE_LIST]
+
+  # rdoc
+  spec.has_rdoc = true
+  spec.extra_rdoc_files = ['README']
+end
+
+# Rake task to build the default package
+Rake::GemPackageTask.new(base_spec) do |pkg|
+  pkg.need_tar = true
+end
+Rake::GemPackageTask.new(cli_spec) do |pkg|
+  pkg.need_tar = true
+end
+
+task :default => [:package]
+
+# Windows specification
+win_spec = base_spec.clone
+win_spec.extensions = []
+win_spec.platform = Gem::Platform::WIN32
+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 fro top level directory	
+	rm(target)
+end
+
+desc "Publish ruby-debug to RubyForge."
+task :publish do 
+  require 'rake/contrib/sshpublisher'
+  
+  # Get ruby-debug path
+  ruby_debug_path = File.expand_path(File.dirname(__FILE__))
+
+  publisher = Rake::SshDirPublisher.new("kent@rubyforge.org",
+        "/var/www/gforge-projects/ruby-debug", ruby_debug_path)
+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
+
+# ---------  RDoc Documentation ------
+desc "Generate rdoc documentation"
+Rake::RDocTask.new("rdoc") do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title    = "ruby-debug"
+  # Show source inline with line numbers
+  rdoc.options << "--inline-source" << "--line-numbers"
+  # Make the readme file the start page for the generated html
+  rdoc.options << '--main' << 'README'
+  rdoc.rdoc_files.include('bin/**/*',
+                          'lib/**/*.rb',
+                          'ext/**/ruby_debug.c',
+                          'README',
+                          'LICENSE')
+end
+

data/bin/rdebug

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# -*- Ruby -*-
 
 require 'rubygems'
 require 'optparse'
@@ -6,75 +7,124 @@ require "ostruct"
 require 'ruby-debug'
 
 options = OpenStruct.new(
-  'server'      => false,
+  'annotate'    => Debugger.annotate,
   'client'      => false,
-  'debug_module'=> 'debug',
+  'control'     => true,
+  'cport'       => Debugger::PORT + 1,
+  'frame_bind'  => false,
   'host'        => nil,
+  'no-quit'     => false,
+  'no-stop'     => false,
+  'nx'          => false,
   'port'        => Debugger::PORT,
-  'cport'       => Debugger::PORT + 1,
-  'control'     => true,
-  'wait'        => false,
-  'nostop'      => false,
   'post_mortem' => false,
   'script'      => nil,
+  'server'      => false,
   'tracing'     => false,
-  'frame_bind'  => false
+  'verbose_long'=> false,
+  'wait'        => false
 )
 
+program = File.basename($0)
 opts = OptionParser.new do |opts|
   opts.banner = <<EOB
-ruby-debug #{Debugger::VERSION}
-Usage: rdebug [options] <script.rb> -- <script.rb parameters>
+#{program} #{Debugger::VERSION}
+Usage: #{program} [options] <script.rb> -- <script.rb parameters>
 EOB
   opts.separator ""
   opts.separator "Options:"
-  opts.on("-s", "--server", "Listen for remote connections") {options.server = true}
-  opts.on("-w", "--wait", "Wait for a client connection, implies -s option") {options.wait = true}
-  opts.on("-c", "--client", "Connect to remote debugger") {options.client = true}
-  opts.on("-h", "--host HOST", "Host name used for remote debugging") {|options.host|}
-  opts.on("-p", "--port PORT", Integer, "Port used for remote debugging") {|options.port|}
-  opts.on("--cport PORT", Integer, "Port used for contol commands") {|options.cport|}
-  opts.on("--no-control", "Do not automatically start control thread") {options.control = false}
-  opts.on("-x", "--trace", "turn on line tracing") {options.tracing = true}
-  opts.on("-n", "--nostop", "Do not stop when stript is loaded") {options.nostop = true}
-  opts.on("-m", "--post-mortem", "Activate post-mortem mode") {options.post_mortem = true}
+  opts.on("-A", "--annotate LEVEL", Integer, "Set annotation level") do 
+    |Debugger::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 
+    |options.cport|
+  end
+  opts.on("-d", "--debug", "Set $DEBUG=true") {$DEBUG = true}
+  opts.on("--emacs", "Activates emacs mode") {ENV['EMACS'] = '1'}
+  opts.on("-h", "--host HOST", "Host name used for remote debugging") do
+    |options.host|
+  end
   opts.on("-I", "--include PATH", String, "Add PATH to $LOAD_PATH") do |path|
     $LOAD_PATH.unshift(path)
   end
-  opts.on("--script FILE", String, "Name of the script file to run") do |options.script| 
+  opts.on("--keep-frame-binding", "Keep frame bindings") do 
+    options.frame_bind = true
+  end
+  opts.on("-m", "--post-mortem", "Activate post-mortem mode") do 
+    options.post_mortem = true
+  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.noquit = true
+  end
+  opts.on("-n", "--no-stop", "Do not stop when script is loaded") do 
+    options.nostop = true
+  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 
+    |options.port|
+  end
+  opts.on("-r", "--require SCRIPT", String,
+          "Require the library, before executing your script") do |name|
+    if name == 'debug'
+      puts "ruby-debug is not compatible with Ruby's 'debug' library. This option is ignored."
+    else
+      require name
+    end
+  end
+  opts.on("--script FILE", String, "Name of the script file to run") do 
+    |options.script| 
     unless File.exists?(options.script)
       puts "Script file '#{options.script}' is not found"
       exit
     end
   end
-  opts.on("-r", "--require debug", String,
-          "Compatibility with Ruby-distributed debug module") do |options.debug_module|
-    if options.debug_module != 'debug'
-      puts "Use '-r' option only with 'debug' (You supplied '#{options.debug_module}'). " + 
-        "This option is ignored."
-    end
+  opts.on("-s", "--server", "Listen for remote connections") do 
+    options.server = true
   end
-  opts.on("--keep-frame-binding", "Keep frame bindings") {options.frame_bind = true}
-  opts.on("--emacs", "Activates emacs mode") {ENV['EMACS'] = '1'}
+  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("-v", "--version", "Show version") do
+  opts.on_tail("--version", 
+               "Print the version") do
     puts "ruby-debug #{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 "ruby-debug #{Debugger::VERSION}"
+    $VERBOSE = true
+  end
 end
 
 begin
-  Debugger::ARGV = ARGV.clone
+  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::INITIAL_DIR = Dir.pwd
   opts.parse! ARGV
 rescue StandardError => e
   puts opts
@@ -87,12 +137,13 @@ 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
   Debugger::PROG_SCRIPT = ARGV.shift
   
@@ -103,16 +154,12 @@ else
   Debugger.wait_connection = options.wait
   Debugger.keep_frame_binding = options.frame_bind
   
-  load_initrc = lambda do
-    script_file = "#{ENV["HOME"] || ENV["HOMEPATH" || "."]}/.rdebugrc"
-    Debugger.run_script script_file, StringIO.new  if File.exists?(script_file)
-  end
-  
   if options.server
     # start remote mode
-    Debugger.start_remote(options.host, [options.port, options.cport], options.post_mortem) do
+    Debugger.start_remote(options.host, [options.port, options.cport], 
+                          options.post_mortem) do
       # load initrc script
-      load_initrc.call
+      Debugger.run_init_script(StringIO.new) unless options.nx
     end
     # load script
     Debugger.debug_load Debugger::PROG_SCRIPT, !options.nostop
@@ -122,8 +169,8 @@ else
     # start control thread
     Debugger.start_control(options.host, options.cport) if options.control
 
-    # load initrc script
-    load_initrc.call
+    # load initrc script (e.g. .rdebugrc)
+    Debugger.run_init_script(StringIO.new) unless options.nx
     
     # run startup script if specified
     if options.script
@@ -132,7 +179,34 @@ else
     # activate post-mortem
     Debugger.post_mortem if options.post_mortem
     Debugger.tracing = options.nostop = true if options.tracing
-    # load script
-    Debugger.debug_load Debugger::PROG_SCRIPT, !options.nostop
+
+    # 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
+    if options.noquit
+      Debugger.stop if Debugger.started?
+      while true do
+        begin
+          Debugger.debug_load Debugger::PROG_SCRIPT, !options.nostop
+        rescue
+          print $!.backtrace.map{|l| "\t#{l}"}.join("\n"), "\n"
+          print "Uncaught exception: #{$!}\n"
+        end
+        # FIXME: add status for whether we are interactive or not.
+        # if STDIN.tty? and !options.nostop
+        if !options.nostop
+          print "The program has finished and will be restarted.\n"
+        else
+          break
+        end
+      end
+    else
+      Debugger.debug_load Debugger::PROG_SCRIPT, !options.nostop
+    end
   end
 end