How do I debug a Ruby gem? (Compass)

Question

I am in the early stages of learning Ruby and want to learn how to debug a gem, but am having trouble finding learning resources around this. A simple example would go a long way for me.

Is debugger the preferred debugger? Where do I require it? How do I set breakpoints with it?

Note: I am making an educated guess that the debugging process may be different depending on the gem that needs debugging, so for reference I am particularly interested in debugging certain issues with Compass.

Answer 1

OK, figured this out on my own. Here were the steps I took..

I am running Ruby 1.9.3 (determined by running ruby -v), so after testing ruby-debug and ruby-debug19, I determined these debuggers were no longer maintained, or at least didn't work properly with my install of ruby1.9.3-p125. This lead me to debugger.

The install instructions that worked were:

$ gem install debugger -- --with-ruby-include=PATH_TO_HEADERS

The PATH_TO_HEADERS on my machine, was simply the source location of ruby:

/Users/myusername/.rvm/src/ruby-1.9.3-p125/

Since I was particularly determined to debug the Compass compiler, I did the following:

1. Cloned the source: $ git clone git://github.com/chriseppstein/compass.git
2. Checked existing compass version first $ compass -v which was 13.0
3. Edited VERSION.yml and increased the patch number (to 13.1) so it didn't conflict with my existing install.
4. Edited the .rb of the file I wanted to debug, which was lib/compass/compiler.rb and added this line at the top: require 'debugger'; debugger
5. Built the gem: gem build compass.gemspec
6. Installed the newly compiled gem: sudo gem install compass-0.13.2.058ead2.gem
7. Compiled an existing compass based project that I was experiencing problems with, and started debugging.
8. When I was done debugging, I uninstalled the debugging version with sudo gem uninstall compass and chose the number corresponding to Compass 13.2.

Note about step 7: Since debugger has the same debugging commands as ruby-debug/ruby-debug19, I was able to follow existing tutorials around debugging steps..

• Such as this RailsCast: http://railscasts.com/episodes/54-debugging-with-ruby-debug
• And this blog (and linked cheat sheet): http://pivotallabs.com/users/chad/blog/articles/366-ruby-debug-in-30-seconds-we-don-t-need-no-stinkin-gui-

If you have other debugger tutorials, pointers, tips, etc, please post them.