import of ruby-debug from
Emacs Lisp Ruby C Shell
Failed to load latest commit information.
bin Add test for filename with embedded space. Apr 18, 2010
cli More rdoc work. Oct 15, 2010
doc pm.rb: spelling mistake Sep 12, 2010
emacs Off by one on showing breakpoint positions Aug 3, 2010
ext reworked stop skipping breakpoints on the same line Nov 16, 2010
lib Bump ruby-debug-extra version. Oct 27, 2010
test improve list and list - (backwards) handling when hitting end of file. Oct 14, 2010
.cvsignore More administrivia Nov 15, 2008
AUTHORS breakpoints.*: main -> Object. Add bad Class name test Dec 25, 2007
CHANGES Go over documentation (1st pass) including that created by rdoc. Oct 15, 2010
ChangeLog Bump ruby-debug-extra version. Oct 27, 2010
INSTALL.SVN Go over documentation (1st pass) including that created by rdoc. Oct 15, 2010
LICENSE initial import Oct 9, 2006 Split out ChangeLogs better (I hope). Jan 7, 2008
README Go over documentation for 0.10.3 release. rdoc creates files in doc/r… Nov 14, 2008
Rakefile Go over documentation (1st pass) including that created by rdoc. Oct 15, 2010 Make NEWS->CHANGES symlnk since NEWS is what autotools wants. Nov 22, 2007 Bump ruby-debug-extra version. Oct 27, 2010 Go over documentation (1st pass) including that created by rdoc. Oct 15, 2010
rdbg.rb INCOMPATIBLE CHANGE: "finish" works like gdb - stop just before the Mar 13, 2008 interface.rb: print is really printf Oct 12, 2007
svn2cl_usermap Go over packaging: Dec 23, 2007


= 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.
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

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 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 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


  require 'ruby-debug' ; 
  Debugger.start do 

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.