dissimulo/drunkendotfiles
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit.

Browse Source
This commit is contained in:
yan
2011-11-17 15:45:33 -06:00
commit 882015bc6d
1819 changed files with 111625 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

338
vim/doc/ruby_debugger.txt Normal file
View File

@@ -0,0 +1,338 @@
*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: