339 lines
13 KiB
Plaintext
339 lines
13 KiB
Plaintext
*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:
|