ruby-debug 0.9.3 → 0.10.0

data/doc/rdebug.1

@@ -0,0 +1,236 @@
+.\" $Id: rdebug.1 461 2007-12-22 11:18:14Z rockyb $
+.TH rdebug 1 
+.SH NAME
+rdebug \- Fast Ruby debugger
+.SH SYNOPSIS
+.B rdebug 
+[debugger-options] 
+rdebug
+[script-options...]
+.SH "DESCRIPTION"
+This manual page documents briefly the
+.BR rdebug
+command.
+.PP
+.B rdebug
+is a fast implementation of the standard Ruby debugger debug.rb.  It
+is implemented by utilizing a Ruby C API hook, allows for remote
+debugging and can be used as the Ruby debugger backend interface for a
+development environment.
+.PP
+The commands generally follow gdb's command set unless there's good
+reason not to.
+
+.PP
+rdebug can do four main kinds of things (plus other things in support of
+these) to help you catch bugs in the act:
+
+.TP
+\ \ \ \(bu
+Start or restart your Ruby script, specifying arguments that might
+affect its behavior.
+
+.TP
+\ \ \ \(bu
+Make your program stop at various points possibly determined by
+specified conditions.
+
+.TP
+\ \ \ \(bu
+Examine what has happened when your program has stopped.
+
+.TP
+\ \ \ \(bu
+Change things in your program, so you can experiment with correcting the
+effects of one bug and go on to learn about another.
+.PP
+
+Here are some of the most frequently-needed commands:
+.TP
+.B break \fR[\|\fIfile\fB:\fIline\fR\fR|\fIclass.method\fR] \fR[if \fIexpr\fR]
+\&
+Set a breakpoint at \c
+.I class.method\c
+\& or at the specified file and line.
+.TP
+.B continue \fR[\fIline\fR]
+Continue running your program (after stopping, e.g. at a
+breakpoint). If a line is given a one-time breakpoint is set there.
+.TP
+.B delete \fR[\fIbreakpoint-numbers\fR]
+\&
+Delete breakpoints by number. If no number is given delete all breakpoints.
+.TP
+.B down \fR[\|\fIcount\fR\|]
+Move down one block frame. If count is given move up that many frames. A negative number
+goes the other direction and is like the up command
+.TP
+.B finish
+Run until the completion of the current function or method.
+.TP
+.BI frame " frame-number"
+Set the stack frame to \fIframe-number\fR for purposes of examinine local variables. For positioning relative to the current frame, use 
+.B up
+or 
+.B down. A negative number starts counting from the other end.
+.TP
+.B help \fR[\|\fIname\fR\|]
+Show information about rdebug command \c
+.I name\c
+\&, or general information
+about using rdebug.
+.TP
+.B info \fR[\|\fIname\fR\|]
+Get the various information usually about the debugged program.
+.TP
+.B irb \fIcommand\fR
+Run an interactive ruby shell (irb) using the current environment.
+.TP
+.B list \fR[\|\fIfile\fB:\fIline\fR|\fIfunction]
+type the text of the program in the vicinity of where it is presently stopped
+or at the specified function or file and line.
+.TP
+.B next \fR[\|\fIcount\fR\|]
+Execute next program line(s) (after stopping); step \c
+.I over\c
+\& any
+function calls in the line.
+.TP
+.BI pp " expr"\c
+\&
+Pretty print the value of an expression.
+.TP
+.BI print " expr"\c
+\&
+Display the value of an expression.
+.TP
+.BI ps " expr"\c
+\&
+Print an array as a columized sorted list.
+.TP
+.B quit
+Exit from the debugger.
+.TP
+.B run \fR[\|\fIarglist\fR\|]
+(Re)start your program (with \c
+.I arglist\c
+\&, if specified). If you want the debugger to get reloaded, use
+.B restart
+instead.
+.TP
+.B set
+Modify parts of the debugger environment.
+.TP
+.B show
+See the debugger environment settings
+.TP
+.BI source " filename"\c
+\&
+Read and execute the lines in file \fIfilename\fR as a series of debugger 
+commands.
+.TP
+.B step \fR[\|\fIcount\fR\|]
+Execute next program line(s) (after stopping); step \c
+.I into\c
+\& any
+function calls in the line.
+.TP
+.B up \fR[\|\fIcount\fR\|]
+Move up one block frame. If count is given move up that many frames. A negative number
+goes the other direction and is like the down command
+.TP
+.B where \fR[\|\fIcount\fR\|]
+Display all or \fIcount\fR items of the program stack.
+.PP
+For full details on rdebug, see \c
+http://rubyforge.org/projects/ruby-debug/
+.SH OPTIONS
+.PP
+.TP 10
+.TP
+.B \-A | \-\-annotate LEVEL
+Set gdb-style annotation to LEVEL, 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.
+.TP
+.B \-\-client
+Connect to a remote debugger. Used with another rdebug invocation using \-\-server.
+See also \-\-host and \-\-cport options
+.TP
+.B \-\-cport=PORT
+Port used for control commands.
+.TP
+.B \-d | \-\-debug
+Set $DEBUG true.
+.TP
+.B \-\-emacs
+Activates GNU Emacs mode. Debugger prompts are prefaced with two octal
+032 characters.
+.TP
+.B \-h | \-\-host=HOST
+Host name used for remote debugging.
+.TP
+.B \-I | \-\-include PATH
+Add PATH to $LOAD_PATH
+.TP
+.B \-m | \-\-post-mortem
+Activate post-mortem mode.
+.TP
+.B \-\-no-control
+Do not automatically start control thread.
+.TP
+.B \-n | \-\-no\-stop
+Do not stop when script is loaded.
+.TP
+.B \-p | \-\-port=PORT
+Host name used for remote debugging.
+.TP
+.B \-r | \-\-require SCRIPT
+Require the library, before executing your script.
+.TP
+.B \-\-script FILE
+Name of the script file to run.
+.TP
+.B \-x | \-\-trace
+Show lines before executing them.
+.TP
+.B \-\-no\-quit
+Do not quit when script terminates. Instead rerun the program.
+.TP
+.B \-\-version
+Show the version number and exit.
+.TP
+.B \-\-verbose
+Turn on verbose mode.
+.TP
+.B \-\-v
+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.
+.TP
+.B \-\-nx
+Don't execute commands found in any initialization files, e.g. .rdebugrc.
+.TP
+.B \-\-keep-frame-binding
+Keep frame bindings.
+.TP
+.B \-\-script=FILE
+Name of the script file to run
+.B \-s | \-\-server
+Listen for remote connections. Another rdebug session accesses using the \-\-client option.
+See also the \-\-host, \-\-port and
+\-\-cport options
+.TP
+.B \-w | \-\-wait
+Wait for a client connection, implies -s option.
+.TP
+.B \-\-help
+Show invocation help and exit.
+.PD
+.SH "SEE ALSO"
+.Sp
+http://rubyforge.org/projects/ruby-debug/
+.SH AUTHOR
+rdebug was written by Kent Siblev. This manual page was written by
+Rocky Bernstein <rocky@gnu.org>

data/runner.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+ruby=${RUBY:-ruby}
+dir=`dirname $0`
+rdebug=${RDEBUG:-${dir}/bin/rdebug}
+$ruby -I${dir}/ext:${dir}/lib:${dir}/cli -- $rdebug $*
+exit $?

data/test/breakpoints.cmd

@@ -0,0 +1,43 @@
+# ********************************************************
+# This tests step, next, finish, continue, disable and 
+# enable.
+# FIXME: break out enable/disable
+# ********************************************************
+set debuggertesting on
+set callstyle last
+set autoeval off
+break 6
+break 10
+continue
+where
+break Foo.bar
+break Object.gcd
+info break
+continue
+where
+info program
+c 10
+info break
+break foo
+info break
+disable  1
+info break
+enable breakpoint 1
+enable br 10
+delete 1
+# We should see breakpoint 2 but not 1
+info break
+# We should still be able to access 2
+disable 2
+enable
+enable foo
+disable bar
+disable
+# We should be able to delete 2
+delete 2 3
+info break
+# Should get a message about having no breakpoints.
+disable 1
+enable 1
+# finish
+quit

data/test/breakpoints.right

@@ -0,0 +1,94 @@
+gcd.rb:4
+def gcd(a, b)
+# # ********************************************************
+# # This tests step, next, finish, continue, disable and 
+# # enable.
+# # FIXME: break out enable/disable
+# # ********************************************************
+# set debuggertesting on
+Currently testing the debugger is on.
+# set callstyle last
+Frame call-display style is last.
+# set autoeval off
+autoeval is off.
+# break 6
+Breakpoint 1 file gcd.rb, line 6
+# break 10
+Breakpoint 2 file gcd.rb, line 10
+# continue
+Breakpoint 1 at gcd.rb:6
+gcd.rb:6
+if a > b
+# where
+--> #0 Object.gcd(a#Fixnum, b#Fixnum) at line gcd.rb:6
+    #1 at line gcd.rb:18
+# break Foo.bar
+Unknown class Foo.
+# break Object.gcd
+Breakpoint 3 at Object::gcd
+# info break
+Num Enb What
+  1 y   at gcd.rb:6
+  2 y   at gcd.rb:10
+  3 y   at Object:gcd
+# continue
+Breakpoint 2 at gcd.rb:10
+gcd.rb:10
+return nil if a <= 0
+# where
+--> #0 Object.gcd(a#Fixnum, b#Fixnum) at line gcd.rb:10
+    #1 at line gcd.rb:18
+# info program
+Program stopped. It stopped at a breakpoint.
+# c 10
+Breakpoint 3 at Object:gcd
+gcd.rb:4
+def gcd(a, b)
+# info break
+Num Enb What
+  1 y   at gcd.rb:6
+  2 y   at gcd.rb:10
+  3 y   at Object:gcd
+# break foo
+Unknown command
+# info break
+Num Enb What
+  1 y   at gcd.rb:6
+  2 y   at gcd.rb:10
+  3 y   at Object:gcd
+# disable  1
+# info break
+Num Enb What
+  1 n   at gcd.rb:6
+  2 y   at gcd.rb:10
+  3 y   at Object:gcd
+# enable breakpoint 1
+# enable br 10
+Enable breakpoints argument '10' needs to at most 3.
+# delete 1
+# # We should see breakpoint 2 but not 1
+# info break
+Num Enb What
+  2 y   at gcd.rb:10
+  3 y   at Object:gcd
+# # We should still be able to access 2
+# disable 2
+# enable
+"enable" must be followed "display", "breakpoints" or breakpoint numbers.
+# enable foo
+Enable breakpoints argument 'foo' needs to be a number.
+# disable bar
+Disable breakpoints argument 'bar' needs to be a number.
+# disable
+"disable" must be followed "display", "breakpoints" or breakpoint numbers.
+# # We should be able to delete 2
+# delete 2 3
+# info break
+No breakpoints.
+# # Should get a message about having no breakpoints.
+# disable 1
+No breakpoints have been set.
+# enable 1
+No breakpoints have been set.
+# # finish
+# quit

data/test/display.cmd

@@ -0,0 +1,18 @@
+# ***************************************************
+# This tests display expressions.
+# ***************************************************
+set debuggertesting on
+b 6
+c
+display a
+display b 
+disable display b
+disable display 1
+c
+enable display b
+enable display 1
+undisplay a
+undisplay 2
+c
+q
+

data/test/display.right

@@ -0,0 +1,37 @@
+gcd.rb:4
+def gcd(a, b)
+# # ***************************************************
+# # This tests display expressions.
+# # ***************************************************
+# set debuggertesting on
+Currently testing the debugger is on.
+# b 6
+Breakpoint 1 file gcd.rb, line 6
+# c
+Breakpoint 1 at gcd.rb:6
+gcd.rb:6
+if a > b
+# display a
+1: a = 3
+# display b 
+2: b  = 5
+# disable display b
+Disable display argument 'b' needs to be a number.
+# disable display 1
+# c
+Breakpoint 1 at gcd.rb:6
+2: b  = 3
+gcd.rb:6
+if a > b
+# enable display b
+Enable display argument 'b' needs to be a number.
+# enable display 1
+# undisplay a
+Undisplay argument 'a' needs to be a number.
+# undisplay 2
+# c
+Breakpoint 1 at gcd.rb:6
+1: a = 1
+gcd.rb:6
+if a > b
+# q

data/test/frame.cmd

@@ -0,0 +1,21 @@
+# ***************************************************
+# This tests step, next, finish and continue
+# ***************************************************
+set debuggertesting on
+set callstyle last
+continue 6
+where
+up
+where
+down
+where
+frame 0
+where
+frame -1
+where
+up 2
+where
+down 2
+where
+# finish
+quit