Sample debug session

The below is a sample trepan session (with bugs and misfeatures included) to show what’s available at this early stage.

First here’s the program /tmp/gcd.rb:

require 'rubygems'; require 'trepanning'
debugger
def gcd(a, b)
  # Make: a <= b
  if a > b
    a, b = [b, a]
  end

  return nil if a >= 0

  if a == 1 or b-a == 0
    return a
  end
  return gcd(b-a, a)
end

a, b = ARGV[0..1].map {|arg| arg.to_i}  # line 18
puts "The GCD of %d and %d is %d" % [a, b, gcd(a, b)]

Now let us run that…

$ rbx /tmp/gcd.rb 3 5
-- (/tmp/gcd.rb:3)
def gcd(a, b)
(trepanx): info program
PC offset 40 of method: __script__
It stopped at a line event.

The debugger command next or “step over” runs to the next statement at this scope. Here we want to step over the call to install the gcd method.

The “--” in “-- (tmp/gcd.rb 3 5)” above, indicates we are stopped at a line event which is also shown in more detail when I run info program.

(trepanx): next
-- (/tmp/gcd.rb:18)
a, b = ARGV[0..1].map {|arg| arg.to_i}
(trepanx): step
-- (/tmp/gcd.rb:19)
puts "The GCD of %d and %d is %d" % [a, b, gcd(a, b)]

There is extensive on-line help. Below we just show the available commands and subcommands for show

(trepanx): help *
All command names:
  alias        directory      finish    kill     ps         step   
  backtrace    disassemble    frame     list     restart    tbreak 
  break        down           help      next     set        unalias
  continue     eval           info      nexti    show       up     
  delete       exit           irb       pr       source 
(trepanx): help d.*
Command names matching /^d.*/:
  delete    directory    disassemble    down
(trepanx): help show *
List of subcommands for command 'show':
  alias    auto        debug        hidelevel     max  
  args     basename    different    kernelstep    trace

Above we encountered the 2-character icons, -- which indicates a line event. You an find a list of event names and icons in Event Icons. Below we will see new one, -> for a call event.

(trepanx): s
-> (./tmp/gcd.rb:4)
(trepanx): where 
   0 Object#gcd(a, b) at /tmp/gcd.rb:5
   1 main.__script__ at /tmp/gcd.rb:18
(trepanx): [a, b]
$d1 = [a, b]

Breakpoints are a bit different than ruby-debug. The main difference is that a breakpoint is associated with a particular VM instruction offset.

(trepanx) list
  6   	    a, b = [b, a]
  7   	  end
  8   	
  9   	  return nil if a >= 0
 10   	
 11   	  if a == 1 or b-a == 0
 12   	    return a
 13   	  end
 14   	  return gcd(b-a, a)
 15   	end
(trepanx): break
Set breakpoint 1: /tmp/gcd.rb:5 (@0)

We tell you where the breakpoint has been set, that’s the number after the @ sign, or 0 here.

Now when I run continue I should hit the breakpoint I just entered.

(trepanx) continue
xx (/tmp/gcd.rb:5)
(trepanx) 

Note the even now is “xx” for breakpoint. To run to the end of the method use “finish”:

(trepanx): finish
<- (/tmp/gcd.rb:9)
return nil if a >= 0

And you see the event is now <-.

And finally we show restarting execution and quitting.

(trepanx): R
Restart args:
	["/home/rocky-rvm/.rvm/rubies/rbx-head/bin/rbx", "/tmp/gcd.rb", "3", "5"]
Restart (exec)? (N/y) 
Restarting...
-- (/tmp/gcd.rb:4)
def gcd(a, b)
(trepanx): exit
Really quit? (N/y) Y
$

Use q! to quit without prompting.