*ruby_debugger.txt*	Plugin for debugging Ruby applications

Author: Anton Astashov 
<anton (yup) astashov (dot) net>		|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 <Leader>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:
   * <Leader>b - set breakpoint at current line
   * <Leader>v - open/close window with variables. You can expand/collapse
                 variables by 'o' in normal mode or left-mouse double-click
   * <Leader>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.
   * <Leader>t - open/close window with backtrace. You can open file/line in
                 this window by pressing 'o' or left-mouse double-click on it
   * <Leader>n - step over
   * <Leader>s - step into
   * <Leader>f - step out
   * <Leader>c - continue
   * <Leader>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 <Leader>b  :call g:RubyDebugger.toggle_breakpoint()<CR>
        map <Leader>v  :call g:RubyDebugger.open_variables()<CR>
        map <Leader>m  :call g:RubyDebugger.open_breakpoints()<CR>
        map <Leader>t  :call g:RubyDebugger.open_frames()<CR>
        map <Leader>s  :call g:RubyDebugger.step()<CR>
        map <Leader>f  :call g:RubyDebugger.finish()<CR>
        map <Leader>n  :call g:RubyDebugger.next()<CR>
        map <Leader>c  :call g:RubyDebugger.continue()<CR>
        map <Leader>e  :call g:RubyDebugger.exit()<CR>
        map <Leader>d  :call g:RubyDebugger.remove_breakpoints()<CR>
>
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 (<Leader>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: