*ruby_debugger.txt* Plugin for debugging Ruby applications Author: Anton Astashov |ruby-debugger-plugin-author| |ruby-debugger-introduction| Introduction and Feature Summary |ruby-debugger-installation| Installation |ruby-debugger-quickstart| QuickStart |ruby-debugger-details| Some additional details about the plugin |ruby-debugger-tests| Debugging of tests |ruby-debugger-ruby19| Using the plugin with ruby 1.9 |ruby-debugger-issues| Troubleshooting |ruby-debugger-bugs| Bugreporting |ruby-debugger-about| About This plugin is only available if 'compatible' is not set. The plugin requires Vim to be compiled with +signs and +clientserver and Vim version >= 7. To check it, run > :echo has("signs") && has("clientserver") && v:version > 700 Result should be equal to 1 If you use Linux, make sure you have "lsof" installed. See > http://en.wikipedia.org/wiki/Lsof Also, it requires ruby-debug-ide gem. To install it, run > gem install ruby-debug-ide Please make sure, that vim/gvim, rdebug-ide and ruby directories are set in your $PATH variable {Vi does not have any of this} ============================================================================== INTRODUCTION *ruby-debugger-introduction* *ruby-debugger* This plugin implements interactive Ruby debugger in Vim. 1. It can debug any Ruby application (Rails, by default), using ruby-debug-ide gem 2. The debugger looks like in the Netbeans - you can go through the code, watch variables, breakpoints in separate window, set and remove breakpoints. 3. It supports command-line rdebug commands. E.g., you can you can execute > :RdbCommand p User.all in command line of VIM and it will display result like usual echo VIM command. ============================================================================== INSTALLATION *ruby-debugger-installation* Clone current version of the repo from GitHub: > git clone git://github.com/astashov/vim-ruby-debugger.git or if you don't have Git, download the archive from here: > http://github.com/astashov/vim-ruby-debugger/tarball/master Then, copy files from ./vim directory to vimfiles (Windows) or ~/.vim (everything else). Or, if you use pathogen, copy ./vim directory contents to ~/.vim/bundle/vim-ruby-debugger. You should have the following files: > plugin/ruby_debugger.vim autoload/ruby_debugger.vim bin/ruby_debugger.rb doc/ruby_debugger.txt The first one is a debugger plugin loader (maps shortcuts and commands), second is ruby-debugger itself. Third is a small ruby script, that makes an interaction between the VIM and the ruby-debug-ide gem, and fourth is the help file. Then, run: > :helptags ~/.vim/doc for generating local tags file. Now you can use the > :help ruby-debugger and watch help file you just added. ============================================================================== QUICKSTART *ruby-debugger-quickstart* 1. Run Vim. If you use gvim, it will automatically start the server, but if you use vim, you need to set servername explicitly, e.g., > vim --servername VIM 2. Go to the directory with some your Rails application. > :cd ~/projects/rails 3. Run Server with Debugger: > :Rdebugger It will kill any listeners of ports 39767 and 39768 and run rdebug-ide and ~/.vim/bin/ruby_debugger.rb on these ports accordingly. 3. Set breakpoint somewhere by b (usually, '\b'). You should see "xx" symbol at the current line. 4. Open page with the breakpoint in the browser. Vim should automatically set its current line to breakpoint. 5. After this, you can use commands: * b - set breakpoint at current line * v - open/close window with variables. You can expand/collapse variables by 'o' in normal mode or left-mouse double-click * m - open/close window with breakpoints. You can open file with breakpoint by pressing 'o' or left-mouse double-click on it, or delete the breakpoint by pressing 'd' on it. * t - open/close window with backtrace. You can open file/line in this window by pressing 'o' or left-mouse double-click on it * n - step over * s - step into * f - step out * c - continue * d - remove all breakpoints ============================================================================== DETAILS *ruby-debugger-details* 1. Of course, you can set your own mappings instead of mine. For this, just add this to your .vimrc and change keys for mapping: > map b :call g:RubyDebugger.toggle_breakpoint() map v :call g:RubyDebugger.open_variables() map m :call g:RubyDebugger.open_breakpoints() map t :call g:RubyDebugger.open_frames() map s :call g:RubyDebugger.step() map f :call g:RubyDebugger.finish() map n :call g:RubyDebugger.next() map c :call g:RubyDebugger.continue() map e :call g:RubyDebugger.exit() map d :call g:RubyDebugger.remove_breakpoints() > 2. Standard output and errors (STDOUT and STDERR) of running script is redirected to ~/.vim/tmp/ruby_debugger_output file (only for POSIX systems - Linux, MacOS) 3. If you are using POSIX OS (Linux, MacOS), you can try fast C implementation of message sender to debugger. For this, copy "socket" file from additionals/bin/ to ~/.vim/bin/, add execution rights to it (chmod +x) and add this string to your .vimrc: > let g:ruby_debugger_fast_sender = 1 4. You can specify path to Ruby (if it is not in your PATH environment or you want to use specific version of Ruby) 4. To run some other Ruby application (not Rails), you should specify its path as argument of Rdebugger command. E.g. > :Rdebugger bla.rb If your script receives arguments, quote it into single quotes: > :Rdebugger '/path/to/bla.rb 1234 bla_bla' 5. To run some rdebug command, use :RdbCommand. E.g.: > :RdbCommand where 6. To eval some code, use :RdbEval. E.g.: > :RdbEval u.name :RdbEval app_config['settings'].map { |s| s.capitalize } 7. To add condition to some breakpoint, you can move cursor on the breakpoint, and type command: > :RdbCond condition E.g.: > :RdbCond current_user.name == "John" Then, execution will be stopped on the breakpoint only if condition is true 8. To add exceptions catcher, use command: > :RdbCatch NameOfException This way, when exception is raised, debugger will catch it, jump to file/line of the exception and you'll be allowed to watch variables, backtrace, etc there. To reset all catched exceptions just restart the server by :Rdebugger command. You can watch placed catchers in the Breakpoints Window (m by default). See the bottom line of the window. WARNING!!! If you try to set catcher to unexisted exception (e.g., if you mistyped class of the exception), ruby-debug-ide will be crashed! Then, you will have to restart the server by :Rdebugger command 9. To stop running server, you can use :RdbStop command: > :RdbStop 10. For communicating with the rdebug the plugin uses temp file: ~/.vim/tmp/ruby_debugger. Rdebug writes some response to this file, "kicks" the plugin remotely calling RubyDebugger.receive_command() by Vim's client-server functionality and the plugin make actions. For this reason, you need Vim compiled with +clientserver. 11. The plugin logs all its actions to ~/.vim/tmp/ruby_debugger_log. 12. You also can run Unit tests for the plugin. For this, copy to ~/.vim/autoload/ ruby_debugger.vim from additionals/autoload (instead of vim/autoload). It has the same functionality, but with unit tests at end of the file. To run unit tests, change current directory to some rails project and run > call g:TU.run() 13. To watch standard output of executing of Ruby script, you can use > :RdbLog It actually just opens ~/.vim/tmp/ruby_debugger_output, with options: > setlocal autoread setlocal wrap setlocal nonumber Also, if plugin AnsiEsc is installed (http://www.vim.org/scripts/script.php?script_id=302, (it colorizes ANSI escape sequences, they are used heavily by e.g. ActiveRecord logging)), it will be run automatically after :RdbLog call to colorize ruby_debugger_output. ============================================================================== DEBUGGING OF TESTS *ruby-debugger-tests* The plugin supports debugging of Test::Unit tests, RSpec specs and Cucumber features by :RdbTest command. Just open file with the test, set some breakpoints and type: > :RdbTest It equals to running > :Rdebugger /path/to/some_test.rb " for Test::Unit tests :Rdebugger '/usr/bin/spec /path/to/some_spec.rb' " for RSpec :Rdebugger '/usr/bin/cucumber /path/to/some.feature' " for Cucumber feautres For debugging Cucumber features, you should set breakpoints in step definitions file (e.g., user_steps.rb), but start debugger by :RdbTest command in blabla.feature file. You can't set breakpoints in .feature file (I mean you can, but they will be ignored), because... well, it is just plain text! :) If you store spec or cucumber executables in some different place, not in /usr/bin (e.g., if you have Windows), you should set path to them explicitly. For this, set some variables in your .vimrc. E.g.: > let g:ruby_debugger_spec_path = 'c:\gembins\spec' " set Rspec path let g:ruby_debugger_cucumber_path = 'c:\gembins\cucumber' " set Cucumber path ============================================================================== RUBY 1.9 *ruby-debugger-ruby19* If you want to use vim-ruby-debugger with Ruby 1.9, the best way will be using 'rvm' (http://rvm.beginrescueend.com/). Install it and then install ruby 1.9: > rvm install 1.9.2 Then, switch to ruby 1.9.2 version: > rvm 1.9.2 Make sure you use correct version of Ruby: > which ruby it will show path to current ruby executable, e.g. > /Users/anton/.rvm/rubies/ruby-1.9.2-p0/bin/ruby Then install ruby-debug-ide19 gem: > gem install ruby-debug-ide19 After installation of the gem, you need make sure path to rdebug-ide points now to RVM dir: > $ which rdebug-ide /Users/anton/.rvm/gems/ruby-1.9.2-p0/bin/rdebug-ide Now you can use vim-ruby-debugger for debugging ruby 1.9 scripts. If you want to debug Rails 3 applications, you (of course) need to install it: > gem install rails then create new Rails 3 app somewhere: > rails new demo go to the dir with the project, and run vim there. Then, run: > :Rdebugger 'script/rails server' to run Rails 3 app. Then, you can set breakpoints, watch variables, etc, as usual. I really recommend to try it with Ruby 1.9 and Rails 3, the plugin will help you to learn how Rails 3 works inside - it is a good experience! :) ============================================================================== TROUBLESHOOTING *ruby-debugger-issues* 1. Sometimes (e.g., if you use Mac OS and mvim), you can notice strange and not correct behavior of the plugin (only a couple commands work, you can't see variables list, next/step commands don't work). Make sure variable 'g:ruby_debugger_progname' contains proper name of Vim's executable (mvim if you run mvim, gvim for gvim, vim for vim): > :echo g:ruby_debugger_progname If it contains some incorrect value, set it in your .vimrc. E.g. for mvim: > let g:ruby_debugger_progname = 'mvim' If Vim's executable directory is not in your PATH environment variable, set full path to executable: > let g:ruby_debugger_progname = '/opt/local/bin/mvim' 2. If you try to set exceptions catcher to unexisted exception class, ruby-debug-ide will be crushed with error. This is issue of the ruby-debud-ide. 3. By default, if Vim is compiled with +ruby, the plugin is trying to send messages to debugger by built-in Ruby interface (details are in ':help ruby'). Some users have issues with built-in Ruby interface, so they may try to "degradate" to external Ruby script instead of using built-in Ruby interface. For that, add to your .vimrc: > let g:ruby_debugger_builtin_sender = 0 and the plugin will call external ruby interpreter instead of built-in interface. ============================================================================== BUGS *ruby-debugger-bugs* If you meet any bug (even small), please, report about it. You can write email to me (|ruby-debugger-plugin-author|), or even better - write about your issue here: > http://github.com/astashov/vim-ruby-debugger/issues > Also, any feedback is highly desired. Please, send all comments, complaints and compliments to the author. Thanks! ============================================================================== ABOUT *ruby-debugger-about* *ruby-debugger-plugin-author* This plugin was written by Anton Astashov. Email: anton (at) astashov (dot) net Website: astashov.net The latest version of plugin can be found at: http://github.com/astashov/vim-ruby-debugger This plugin is distributable under the same terms as Vim itself. See |license|. No warranties, expressed or implied. ============================================================================== vim:tw=78:ts=8:ft=help:norl: