From nobody at rubyforge.org Thu Feb 3 20:41:12 2011 From: nobody at rubyforge.org (nobody at rubyforge.org) Date: Thu, 3 Feb 2011 20:41:12 -0500 (EST) Subject: [Ruby-debug-commits] [987] trunk/doc/ruby-debug.texi: Explain that ruby-debug is not debug.rb Message-ID: <20110204014112.7DD1E1858356@rubyforge.org> Revision: 987 Author: rockyb Date: 2011-02-03 20:41:11 -0500 (Thu, 03 Feb 2011) Log Message: ----------- Explain that ruby-debug is not debug.rb Modified Paths: -------------- trunk/doc/ruby-debug.texi Modified: trunk/doc/ruby-debug.texi =================================================================== --- trunk/doc/ruby-debug.texi 2010-12-25 15:18:08 UTC (rev 986) +++ trunk/doc/ruby-debug.texi 2011-02-04 01:41:11 UTC (rev 987) @@ -162,6 +162,7 @@ @smallexample def triangle(n) (n * (n+1)) / 2 end @end smallexample + The code we use in this example and the next is more for pedagogical purposes than how to write short Ruby code.} @@ -655,6 +656,7 @@ require 'rubygems' require 'ruby-debug/debugger' @end smallexample + The line @code{require "rubygems"} is needed if @code{ruby-debug} is installed as a Ruby gem. @@ -677,7 +679,7 @@ solutions = [] (rdb:1) @end smallexample -and we see that we are stopped at line 9 just before the + at noindent and we see that we are stopped at line 9 just before the initialization of the list @code{solutions}. Now let's see where we are... @@ -951,14 +953,16 @@ @smallexample Tracing(1):gcd.rb:18 a, b = ARGV[0..1].map @{|arg| arg.to_i@} @end smallexample -appears three times. If we were to break this line into the equivalent + + at noindent appears three times. If we were to break this line into the equivalent multi-line expression: @smallexample a, b = ARGV[0..1].map do |arg| arg.to_i end @end smallexample -we would find one stop at the first line before running @code{map} and + + at noindent we would find one stop at the first line before running @code{map} and two listings of @code{arg.to_i}, once for each value of arg which here is 0 and then 1. Perhaps this is is not surprising because we have a loop here which gets run in this situation 3 times. A similar command @@ -1166,10 +1170,60 @@ @node Installation @chapter Installing @code{ruby-debug} + at menu +* ruby-debug is not debug.rb:: +* Installing the gem:: + at end menu There are a number of pitfalls that one can run into in trying to install @code{ruby-debug}. We will try to go over them here. + at node ruby-debug is not debug.rb + at section @code{ruby-debug} is not @code{debug.rb} + +One problem that comes up a bit is a confusion of this gem package, + at code{ruby-debug}, with the Ruby library program @code{debug.rb}. The +latter comes distributed with Ruby. + +When you run @code{ruby -r debug test.rb} or without the space between the + at code{-r} and the @code{debug}: + + at smallexample + $ ruby -rdebug test.rb # This is something not described here + at end smallexample + + at noindent you are getting the program that comes installed with Ruby. Although +what we describe here, @code{ruby-debug}, has commands which are largely +a superset of the @code{debug.rb} commands, @code{ruby-debug} is +something vastly different. + + at code{ruby-debug} is a packaged as a gem. When installed, the program + at code{bin/rdebug} is installed. This allows you to invoke the debugger +from the outset. But don't confuse the example above with + + at smallexample + $ rdebug test.rb # not the same as the above! + at end smallexample + +The Pickaxe books talk about @code{debug.rb}, not the @code{ruby-debug} +gem. I think it safe to say that most folks who use any sort of debugger +are nowadays using ruby-debug. (Even the IDE's like the ones from +Eclipse, JetBrains, or Aptana use common code from @code{ruby-debug} and +none import any code from @code{debug.rb}) + +I realize all of this is confusing. Unfortunately it is a bit too late +to change this in any significant way. + +In the next round of debuggers, the ``trepanning'' debuggers --- + at url{http://github.com/rocky/rb-trepanning} and + at url{http://github.com/rocky/rbx-trepanning} --- I've tried to make the +distinction more clear. The command-line invocation is no longer + at code{rdebug}. And the prompt which had been inside the debugger + at code{(rdb)} is now different. + + at node Installing the gem + at section Installing the gem + In the simplest case, one should be able to run: @smallexample From nobody at rubyforge.org Fri Feb 11 16:37:27 2011 From: nobody at rubyforge.org (nobody at rubyforge.org) Date: Fri, 11 Feb 2011 16:37:27 -0500 (EST) Subject: [Ruby-debug-commits] [988] trunk/Rakefile: Adding --verbose to test/ unit has changed over the years Message-ID: <20110211213727.20940197833E@rubyforge.org> Revision: 988 Author: rockyb Date: 2011-02-11 16:37:26 -0500 (Fri, 11 Feb 2011) Log Message: ----------- Adding --verbose to test/unit has changed over the years Modified Paths: -------------- trunk/Rakefile Modified: trunk/Rakefile =================================================================== --- trunk/Rakefile 2011-02-04 01:41:11 UTC (rev 987) +++ trunk/Rakefile 2011-02-11 21:37:26 UTC (rev 988) @@ -85,7 +85,7 @@ t.libs += %W(#{ROOT_DIR}/lib #{ROOT_DIR}/cli) t.libs << ext if File.exist?(ext) t.test_files = CLI_TEST_FILE_LIST - t.verbose = true + t.options = '--verbose' if $VERBOSE end end @@ -94,7 +94,7 @@ Rake::TestTask.new(:test_base) do |t| t.libs += ['./ext', './lib'] t.test_files = FileList[BASE_TEST_FILE_LIST] - t.verbose = true + t.options = '--verbose' if $VERBOSE end end From nobody at rubyforge.org Sat Feb 19 23:14:32 2011 From: nobody at rubyforge.org (nobody at rubyforge.org) Date: Sat, 19 Feb 2011 23:14:32 -0500 (EST) Subject: [Ruby-debug-commits] [989] trunk/doc/ruby-debug.texi: Start describing how out-of-process execution works. Message-ID: <20110220041432.17C5918582E2@rubyforge.org> Revision: 989 Author: rockyb Date: 2011-02-19 23:14:31 -0500 (Sat, 19 Feb 2011) Log Message: ----------- Start describing how out-of-process execution works. That is options port, host, server and client. Modified Paths: -------------- trunk/doc/ruby-debug.texi Modified: trunk/doc/ruby-debug.texi =================================================================== --- trunk/doc/ruby-debug.texi 2011-02-11 21:37:26 UTC (rev 988) +++ trunk/doc/ruby-debug.texi 2011-02-20 04:14:31 UTC (rev 989) @@ -141,6 +141,7 @@ * Second Sample Session:: Second Session Delving a little deeper @code{rdebug} session * Unit Testing Session:: Using the debugger in unit testing * Debugger.start with a block:: Using the Debugger.start with a block +* Remote Debugging:: Connecting to the debugger from the outside * Debugging Oddities:: How debugging Ruby may be different... @end menu @@ -811,6 +812,82 @@ issuing another @code{debugger} call will not have any effect even if it is nested inside another @code{Debugger.start}. + at node Remote Debugging + at section Connectiong to the debugger from the Outside + at menu +* Remote Execution from the outset:: +* Remote Execution from inside a Ruby program:: + at end menu + + at node Remote Execution from the outset + at subsection Remote execution from the outset + +It is possible to set up debugging so that you can issue debugger +commands from outside of the process running the Ruby code. In fact, you +might even be on a different computer than the one running the Ruby +program. + +To do this one sets up the to debug a program a ``server'' mode. For +this use the @option{--server}. We will use one other option in the +command below @option{--wait}: + + at smallexample +$ @b{rdebug --server --wait tri3.rb} +# Nothing happens + at end smallexample + +Without @option{--wait} the program would run and terminate before we +have a chance to connect to it. In a different window on the same +machine we now run the ``client'' side to connect to this waiting program: + + at smallexample +$ @b{rdebug --client} +Connected. +(rdb:1) @b{bt} +--> #0 at line triangle.rb:4 + at end smallexample + +Other options related to remote debugging on both the client and servers +side are the @option{--host}, @option{--port} options. By setting these +options appropriately, is possible that to debug the program over a +TCP/IP connection. + +Note however that program output is still going to the place it normally +would go; output is not redirected across the debugger connection. + + at node Remote Execution from inside a Ruby program + at subsection Going into Remote execution from inside a Ruby program + +Arrange for the following code to get executed. It only needs to happen +one sometime before you code gets run that needs the debugger. As +before, you probably want to put before to many methods get nested in +the call chain, because you won't be able to inspect frames of those +that were created before the ``start_remote'' below + + at smallexample + require 'rubygems'; require 'ruby-debug'; + + # Omit the following assignment statment line if don't want to wait + # for a client before continuing... + Debugger.wait_connection = true + Debugger.start_remote + at end smallexample + +Now at a place of program execution wich gets run before you might ever +want a debugger stop, add a call to ``debugger'' as was done without +remote execution: + + at smallexample + # work, work, work.... + debugger + some ruby code # debugger will stop before this is run + at end smallexample + +I've not tried this, but I think you could but the call ``debugger'' +inside a signal handler. When the signal handler returns you would be at +the place you interrupted the Ruby program. + + @node Debugging Oddities @section How debugging Ruby may be different than debugging other Languages @@ -1334,6 +1411,7 @@ @menu * rdebug command-line options:: Options you can pass to rdebug +* Out-of-process execution options:: * rdebug default options:: How to Set Default Command-Line Options @end menu @@ -1524,6 +1602,26 @@ @end table + at node Out-of-process execution options + at subsection Options for Out-of-process execution + +Option @option{--wait} (pause execution until a client connects to the +program) is only meaningful in ``server'' mode or with @option{server}. + +With option @option{--client} you don't give the name of a program to +debug. That was done when running the server. + +With both @option{--client} and @option{--server} you can specify the +interface name to listen on (for server) or connect to (for client) as +either a DNS name or as an IP address. Likewise one can specify a port +number to listen on or connect to. As with any other TCP/IP connection +the port names and interface name (as either an IP or a name) much +correspond for the client to connect to a program in server mode. In +the simple cases, the port names and host names will be the +same. However due to port forwarding and NAT translation that sometimes +occurs behind firewalls, it is possible these may be different. + + @node rdebug default options @subsection How to Set Default Command-Line Options From nobody at rubyforge.org Sat Feb 19 23:22:17 2011 From: nobody at rubyforge.org (nobody at rubyforge.org) Date: Sat, 19 Feb 2011 23:22:17 -0500 (EST) Subject: [Ruby-debug-commits] [990] trunk/doc/ruby-debug.texi: Move menuing around a little for command options Message-ID: <20110220042218.0519618582E2@rubyforge.org> Revision: 990 Author: rockyb Date: 2011-02-19 23:22:17 -0500 (Sat, 19 Feb 2011) Log Message: ----------- Move menuing around a little for command options Modified Paths: -------------- trunk/doc/ruby-debug.texi Modified: trunk/doc/ruby-debug.texi =================================================================== --- trunk/doc/ruby-debug.texi 2011-02-20 04:14:31 UTC (rev 989) +++ trunk/doc/ruby-debug.texi 2011-02-20 04:22:17 UTC (rev 990) @@ -1354,6 +1354,12 @@ @node Starting the debugger @section Starting the debugger + at menu +* rdebug command-line options:: Options you can pass to rdebug +* Out-of-process execution options:: +* rdebug default options:: How to Set Default Command-Line Options + at end menu + Although one can enter @DBG{} via Emacs (described in a later section) and possibly others interfaces, probably the most familiar thing to do is invoke the debugger from a command line. @@ -1409,12 +1415,6 @@ Options for the @code{rdebug} are shown in the following list. - at menu -* rdebug command-line options:: Options you can pass to rdebug -* Out-of-process execution options:: -* rdebug default options:: How to Set Default Command-Line Options - at end menu - @node rdebug command-line options @subsection Options you can pass to rdebug From nobody at rubyforge.org Sat Feb 19 23:23:06 2011 From: nobody at rubyforge.org (nobody at rubyforge.org) Date: Sat, 19 Feb 2011 23:23:06 -0500 (EST) Subject: [Ruby-debug-commits] [991] trunk/doc/ruby-debug.texi: One more small doc change Message-ID: <20110220042306.42DB818582EE@rubyforge.org> Revision: 991 Author: rockyb Date: 2011-02-19 23:23:05 -0500 (Sat, 19 Feb 2011) Log Message: ----------- One more small doc change Modified Paths: -------------- trunk/doc/ruby-debug.texi Modified: trunk/doc/ruby-debug.texi =================================================================== --- trunk/doc/ruby-debug.texi 2011-02-20 04:22:17 UTC (rev 990) +++ trunk/doc/ruby-debug.texi 2011-02-20 04:23:05 UTC (rev 991) @@ -1606,7 +1606,7 @@ @subsection Options for Out-of-process execution Option @option{--wait} (pause execution until a client connects to the -program) is only meaningful in ``server'' mode or with @option{server}. +program) is only meaningful in ``server'' mode or with @option{--server}. With option @option{--client} you don't give the name of a program to debug. That was done when running the server. From nobody at rubyforge.org Sat Feb 19 23:27:13 2011 From: nobody at rubyforge.org (nobody at rubyforge.org) Date: Sat, 19 Feb 2011 23:27:13 -0500 (EST) Subject: [Ruby-debug-commits] [992] trunk/doc/ruby-debug.texi: Another typo Message-ID: <20110220042713.B44A018582E2@rubyforge.org> Revision: 992 Author: rockyb Date: 2011-02-19 23:27:13 -0500 (Sat, 19 Feb 2011) Log Message: ----------- Another typo Modified Paths: -------------- trunk/doc/ruby-debug.texi Modified: trunk/doc/ruby-debug.texi =================================================================== --- trunk/doc/ruby-debug.texi 2011-02-20 04:23:05 UTC (rev 991) +++ trunk/doc/ruby-debug.texi 2011-02-20 04:27:13 UTC (rev 992) @@ -813,7 +813,7 @@ it is nested inside another @code{Debugger.start}. @node Remote Debugging - at section Connectiong to the debugger from the Outside + at section Connecting to the debugger from the Outside @menu * Remote Execution from the outset:: * Remote Execution from inside a Ruby program:: From nobody at rubyforge.org Mon Feb 21 01:05:49 2011 From: nobody at rubyforge.org (nobody at rubyforge.org) Date: Mon, 21 Feb 2011 01:05:49 -0500 (EST) Subject: [Ruby-debug-commits] [993] trunk/doc/ruby-debug.texi: Typo: wich->which Message-ID: <20110221060549.A87A91858357@rubyforge.org> Revision: 993 Author: rockyb Date: 2011-02-21 01:05:49 -0500 (Mon, 21 Feb 2011) Log Message: ----------- Typo: wich->which Modified Paths: -------------- trunk/doc/ruby-debug.texi Modified: trunk/doc/ruby-debug.texi =================================================================== --- trunk/doc/ruby-debug.texi 2011-02-20 04:27:13 UTC (rev 992) +++ trunk/doc/ruby-debug.texi 2011-02-21 06:05:49 UTC (rev 993) @@ -873,7 +873,7 @@ Debugger.start_remote @end smallexample -Now at a place of program execution wich gets run before you might ever +Now at a place of program execution which gets run before you might ever want a debugger stop, add a call to ``debugger'' as was done without remote execution: From nobody at rubyforge.org Mon Feb 21 12:00:07 2011 From: nobody at rubyforge.org (nobody at rubyforge.org) Date: Mon, 21 Feb 2011 12:00:07 -0500 (EST) Subject: [Ruby-debug-commits] [994] trunk/doc/ruby-debug.texi: More out-of-process documentation hacking Message-ID: <20110221170010.0D9AD1858361@rubyforge.org> Revision: 994 Author: rockyb Date: 2011-02-21 12:00:06 -0500 (Mon, 21 Feb 2011) Log Message: ----------- More out-of-process documentation hacking Modified Paths: -------------- trunk/doc/ruby-debug.texi Modified: trunk/doc/ruby-debug.texi =================================================================== --- trunk/doc/ruby-debug.texi 2011-02-21 06:05:49 UTC (rev 993) +++ trunk/doc/ruby-debug.texi 2011-02-21 17:00:06 UTC (rev 994) @@ -828,17 +828,18 @@ program. To do this one sets up the to debug a program a ``server'' mode. For -this use the @option{--server}. We will use one other option in the -command below @option{--wait}: +this use the @option{--server} option on a @value{ttrdebug} +invocation. We will use one other option below: @option{--wait}: @smallexample $ @b{rdebug --server --wait tri3.rb} # Nothing happens @end smallexample -Without @option{--wait} the program would run and terminate before we -have a chance to connect to it. In a different window on the same -machine we now run the ``client'' side to connect to this waiting program: +Without @option{--wait} the program would run and probably terminate +before we have a chance to connect to it. Next, in a different window on +the same machine, run the ``client'' side. This will connect to this +waiting program in ``server'' mode: @smallexample $ @b{rdebug --client} @@ -847,7 +848,7 @@ --> #0 at line triangle.rb:4 @end smallexample -Other options related to remote debugging on both the client and servers +Other options related to remote debugging on both the client and server side are the @option{--host}, @option{--port} options. By setting these options appropriately, is possible that to debug the program over a TCP/IP connection. @@ -858,12 +859,13 @@ @node Remote Execution from inside a Ruby program @subsection Going into Remote execution from inside a Ruby program -Arrange for the following code to get executed. It only needs to happen -one sometime before you code gets run that needs the debugger. As -before, you probably want to put before to many methods get nested in -the call chain, because you won't be able to inspect frames of those -that were created before the ``start_remote'' below +As with the case where you are debugging on the same machine, often you +might not want call the debugger initially, but only after something +happens. It is possible to call the debugger and arrange it to start out +in server mode. +To do this, arrange for the following code to get executed. + @smallexample require 'rubygems'; require 'ruby-debug'; @@ -873,7 +875,13 @@ Debugger.start_remote @end smallexample -Now at a place of program execution which gets run before you might ever +The above only needs to happen one sometime before you code gets run +that needs the debugger. As before, you probably want to put this before +too many methods get nested in the call chain. Otherwise you won't be +able to inspect frames of those that were created before the +``start_remote'' above. + +Next, at a place of program execution which gets run before you might ever want a debugger stop, add a call to ``debugger'' as was done without remote execution: @@ -883,11 +891,12 @@ some ruby code # debugger will stop before this is run @end smallexample -I've not tried this, but I think you could but the call ``debugger'' -inside a signal handler. When the signal handler returns you would be at -the place you interrupted the Ruby program. +If you are running for example a web service, you might create a URL +that basically invokes ``debugger''. And although, I've not tried this, +I think you could but the call ``debugger'' inside a signal +handler. When the signal handler returns you would be at the place you +interrupted the Ruby program. - @node Debugging Oddities @section How debugging Ruby may be different than debugging other Languages @@ -1606,18 +1615,19 @@ @subsection Options for Out-of-process execution Option @option{--wait} (pause execution until a client connects to the -program) is only meaningful in ``server'' mode or with @option{--server}. +program) is only meaningful in ``server'' mode or with the + at option{--server} option. With option @option{--client} you don't give the name of a program to debug. That was done when running the server. -With both @option{--client} and @option{--server} you can specify the -interface name to listen on (for server) or connect to (for client) as -either a DNS name or as an IP address. Likewise one can specify a port -number to listen on or connect to. As with any other TCP/IP connection -the port names and interface name (as either an IP or a name) much -correspond for the client to connect to a program in server mode. In -the simple cases, the port names and host names will be the +With both the @option{--client} and @option{--server} options, you can +specify the interface name to listen on (for server) or connect to (for +client) as either a DNS name or as an IP address. Likewise one can +specify a port number to listen on or connect to. As with any other +TCP/IP connection the port names and interface name (as either an IP or +a name) much correspond for the client to connect to a program in server +mode. In the simple cases, the port names and host names will be the same. However due to port forwarding and NAT translation that sometimes occurs behind firewalls, it is possible these may be different.