Basic Usage

David Rodríguez edited this page Aug 10, 2013 · 14 revisions

To get started:

gem install rbx-trepanning  # may need to add 'sudo' 

should install the debugger gem and its dependencies.

There are several ways to get into the debugger, after installing. We’ll list these next.

Running the standalone debugger

 trepanx ruby-program [program]

if your program needs options of its own:

 trepanx -- ruby-program [program args...]

Using -Xdebug

By default Rubinius will use its own reference debugger. However you can change that to run trepanning by setting Rubinius::Load.debugger inside your Rubinius startup script ~/.rbxrc :

 Rubinius::Loader.debugger = proc { 
    require 'rubygems'
    require 'trepanning'
    Trepan.start
  }

Modify source to call debugger

 require 'trepanning'
 debugger     # Don't stop here...  
 work         # but stop here.

The above is really shorthand for something like:

 $trepan = Trepan.new
 $trepan.debugger

Trepan.new returns a debugger object which can then be used over again. Although in the above we explicitly assigned this newly created object to $trepan, Trepan.debugger also does this. The debugger object holds debugger state including debugger settings. The debugger method is an alias for start, so above we could have written

$trepan = Trepan.new
$trepan.start # same as $trepan.debugger

The debugger method has an optional parameter, a hash which can be used to specify various options.

If for some reason you want a synchronous stop in your program call to the debugger at the point of the call, set value hash key :immediate of this optional parameter to true.

For example:

 # In Ruby code  ... work, work, work
 debugger(:immediate=>true)   # enter debugger here
 #    ... work, work, work

There are a number of other options that can be specified here. setting the value of hash key :nx to false prevent a debugger startup file, e.g. .rbxrc not to be read. The value of hash key :cmdfiles can be used to give a debugger command.

We will show the use of key :server in to allow for remote debugging in the next section.

Out-of-process debugging

It is possible to connect debug a program from outside the process; in fact it is possible to connect to the program from outside the computer the program is running on. As with in-process debugging, there are a couple of ways to do this: by calling the debugger initially and by modifying the source code to make a debugger call.

First, to start debugging a program so that another process can connect to it and debug it, use the —server option on the trepanx command. For example:

 $ trepanx --server my-ruby-program.rb

By default, stops the program before running it and sets up a TCP server socket listening at “localhost” on port 1027. To connect to it, use the —client option in another trepanx invocation:

$ trepanx --client   # Assumes you have a program already running

As before, one instead modify source code to make a call to the debugger in a way that another program can attach to. Use set the value of key :server to true in the debugger method:

require 'trepanning'
    $dbgr = Trepan.new(:server => true)
    # work work work
    $dbgr.debugger

Running the debugger via sending a signal to the process.

One important thing to observe in the above examples where an explicit call to the debugger is made, is that it is possible to delay loading the debugger until just before it is needed. Although one generally issues require early in Ruby programs, it doesn’t have to be that way. Specifically, one can defer require “trepanning” until right before a debugger call. In this way one might but the those two statements inside a signal handler. Doing this allows one to send a signal to a process and have it go into the debugger.

Give a specific example here