*ruby_debugger.txt*	Plugin for debugging Ruby applications

Author: Anton Astashov
<anton (dot) astashov (at) gmail.com>		|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-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, +clientserver and +ruby
and Vim version >= 7. To check it, run >
	:echo has("signs") && has("clientserver") && has("ruby") && v:version > 700
Result should be equal to 1

Also, it requires debugger-xml gem. To install it, run >
	gem install debugger-xml

or just add it to your Gemfile: >
        gem 'debugger-xml'

Please make sure, that vim/gvim/mvim, rdebug-vim and ruby directories are set
in your $PATH variable.

This version of vim-ruby-debugger doesn't work with Ruby <= 1.8.7. If you need
to debug that version of Ruby, you may try old vim-ruby-debugger, in the "v1.0"
branch (http://github.com/astashov/vim-ruby-debugger/tree/v1.0)

Windows is not supported.

{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 debugger-xml
gem

2. The debugger looks like in any IDE - you can go through the code, watch
variables, breakpoints in a separate window, set and remove breakpoints.

3. It supports execution of commands in the context of stopped line. E.g., you
can execute >
        :RdbEval User.all
in the Vim command line and it will display the results 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 the vim-ruby-debugger dir to the vim directory (~/.vim)). Or, if you
use pathogen, copy the vim-ruby-debugger dir to ~/.vim/bundle/vim-ruby-debugger.

Then, run: >
	:helptags ~/.vim/doc
for generating the local tags file.

Now you can use the >
	:help ruby-debugger
and watch the help file you just added.

==============================================================================
QUICKSTART					*ruby-debugger-quickstart*

1. Run Vim. If you use mvim/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 2 application. >
	:cd ~/projects/rails

3. Run Server with Debugger: >
	:Rdebugger

It will run debugger-xml's rdebug-vim executable, create a UNIX socket in tmp
directory, and connect to debugger-xml through it.

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

6. To see when the ruby debugger is running, you can add the following function call
to your status line:

   set statusline=%{ruby_debugger#statusline()}

   When the debugger is running you'll see '[ruby debugger running]'

==============================================================================
DETAILS					*ruby-debugger-details*

*  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>
>
*  Standard output and errors (STDOUT and STDERR) of running script is
redirected to ~/.vim/tmp/ruby_debugger_output file

*  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 them into single quotes: >
        :Rdebugger '/path/to/bla.rb 1234 bla_bla'

*  You can specify default script which will be run when you specify
   :Rdebugger without arguments. By default it is 'script/rails server',
   but you can change it by adding such line to your .vimrc: >
        let g:ruby_debugger_default_script = 'rackup -p 4567'

*  To run some rdebug command, use :RdbCommand. E.g.: >
	:RdbCommand where

*  To eval some code, use :RdbEval. E.g.: >
        :RdbEval u.name
        :RdbEval app_config['settings'].map { |s| s.capitalize }

*  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

* To stop running server, you can use :RdbStop command: >
        :RdbStop

* For communicating with the rdebug the plugin uses temp file:
   ~/.vim/tmp/ruby_debugger. debugger-xml 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.

*  The plugin will log all its actions to ~/.vim/tmp/ruby_debugger_log, if you
   set g:ruby_debugger_debug_mode in your .vimrc: >
        let g:ruby_debugger_debug_mode = 1

*  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()

*  To watch standard output of executing of the 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 'rspec /path/to/some_spec.rb'      " for RSpec
  :Rdebugger '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 a just plain text! :)

If you store rspec or cucumber executables in some different place, not in
$PATH, you should set path to them explicitly.

For this, set some variables in your .vimrc. E.g.: >
  let g:ruby_debugger_spec_path = '/path/to/rspec'         " set Rspec path
  let g:ruby_debugger_cucumber_path = '/path/to/cucumber' " set Cucumber path

A single rspec test can be invoked by RdbTestSingle which will invoke rspec
and pass the current line to rspec via "-l" argument to rspec.  For Cucumber
and Test::Unit all tests/features are run.

==============================================================================
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 rdebug-vim (executable of debugger-xml) is not in your $PATH, you can
specify where is it explicitly: >
  let g:ruby_debugger_executable = "bundle exec rdebug-vim"

4. If you still can't fix the issue, you can enable debug mode by: >
  let g:ruby_debugger_debug_mode = 1
in your .vimrc, and then open the new issue in Github Issue Tracker
(or write email to me) and attach ~/.vim/tmp/ruby_debugger_log file.

5. Sometimes the default key bindings can conflict with the key bindings of
other plugins. In this case you may want to disable the default bindings of
vim-ruby-debugger and assign your own bindings. For that, use this: >
  let g:ruby_debugger_no_maps = 1
in your .vimrc, and then you can specify your own bindings

==============================================================================
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 (dot) astashov (at) gmail.com
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: