rb8-trepanning

h1. rb8-trepanning a Ruby MRI 1.8 and 1.9 debugger using ruby-debug-base.

This is a rewrite of ruby-debug, but still using ruby-debug base.

Right now, I've mostly tested on MRI 1.8, it sort of works on MRI 1.9.2 Ruby. Since the code is pure Ruby, it probably will work on other Rubies that have ruby-debug-base installed to some degree.

h2. Features

• Syntax highlighting (if "coderay":http://coderay.rubychan.de/ and term-ansicolor are installed)
• tab completion of commands
• expanded on-line help
• easy evaluation of the statement or expression in a statement about to be run (eval and eval? with no arguments)
• cleaner, more modular and more testable code

I realize the last item may not be of importance to many, but it's very important as a developer of the code.

There is a "google group mailing list":http://groups.google.com/group/ruby-debugger for Ruby debuggers.

h2. Installing (from git)

bq. $ git clone git://github.com/rocky/rb8-trepanning.git $ cd rb8-trepanning $ rake test $ rake install

h2. Background

ruby-debug is cool, but it became getting harder to work on and to extend it while keeping compatibility. The code never started out from a test-driven development standpoint--tests were bolted on afterwards.

Over time, I gained a better understanding of what was important (to me), and I learned how to do things better. So I decided to rewrite the code. This code base is a backport of the "trepanning debugger for Rubinius":https://github.com/rocky/rbx-trepanning/wiki which in turn is a port of the "trepanning debugger for a patched MRI YARV 1.9.2":https://github.com/rocky/rb-trepanning/wiki which is a port of "a debugger for Python":http://code.google.com/p/pydbgr/ which is a port of ruby-debug.

h2. Compatibility with ruby-debug

Compatiblity between ruby-debug and trepanning is like compatibility between Ruby 1.8 and Ruby 1.9.

Here are some incompatibilities. Depending on your point of view, I hope you will find as I do that these are improvements:

• "set autoeval" is on by default
• ";;" rather than ";" separates debugger commands. This way, ";" can be used in a Ruby statement to evaluate.
• Command names can be abbreviated if they are unique. For example "st" and "ste" are abbreviations of "step". To turn this off, "set abbrev off".

h2. Dependencies

The debugger needs to work in more limited environments, so there are a number packages which are optional but not required. They are:

• coderay and term-ansicolor for syntax and terminal highlighting
• rb-readline (>= 0.4.0) on MRI 1.8 for better tab completion.
• ParseTree (>= 3.0.7) and its dependencies for showing method S-expressions
• linecache (>= 0.45dev) for syntax highlighting

Required dependencies are the same as ruby-debug:

• ruby-debug-base -- for run-time debugging support
• linecache or linecache19 -- for caching source-code lines and figuring out breakpoint lines
• columnize -- for showing commands in columns