*VimDebug.txt*      Vim debugger integration


            VIM REFERENCE MANUAL    by Eric Johnson

*VimDebug* *VimDebug.vim*

1. VimDebug Intro                   |VimDebug-intro|
2. Requirements                     |VimDebug-req|
3. Installation                     |VimDebug-install|
4. Usage                            |VimDebug-usage|
5. Keybindings                      |VimDebug-bindings|

==============================================================================
1. VimDebug Intro                   *VimDebug-intro*

VimDebug integrates the Perl debugger with Vim.

To manage saving and restoring key bindings used when running
VimDebug, we use 'savemap', vimscript code written by tyru,
<tyru.exe@gmail.com>, whom we thank! We used files from this commit:
    
https://github.com/tyru/savemap.vim/commit/61c2afcb6e16c01b82950565093cc8b532ea57f6

==============================================================================
2. Requirements                     *VimDebug-req*

VimDebug requires the following to function:

- *nix/Ubuntu/OSX
- Vim with +signs, and +perl compiled in
- Perl 5.FIXME
- The Vim::Debug Perl module

VimDebug is a Vim plugin, see |add-plugin|.  This plugin is only available if
'compatible' is not set and vim has been compiled with '+signs' and '+perl'.

==============================================================================
3. Installation                     *VimDebug-install*

Use Perl's package manager, cpanm, to install the Vim::Debug Perl module.

  curl -L http://cpanmin.us | perl - --sudo App::cpanminus # install cpanm
  sudo cpanm Vim::Debug                                    # install Vim::Debug

For more help with installing Perl modules, see the cpanm documentation on
cpan.

==============================================================================
4. Usage                            *VimDebug-usage*

When you launch Vim, VimDebug will check to see if it has unique normal mode
access to its start key, by default <F12>. If it does, pressing this key will
attempt to launch the debugger on whatever file is loaded in the current
window, prompting you for arguments. If it doesn't, you can still launch the
debugger by invoking the following command, to which you may pass arguments
that will be passed on to the debugger:

    :VDstart foo 42

If VimDebug successfully launches the debugger, it will install its own
|VimDebug-bindings| for navigating it. This may disrupt some of your current
bindings, but VimDebug will have saved those previous bindings, and while the
debugger is running, pressing the start key will toggle the bindings between
your saved key bindings and VimDebug's own. If the start key is not available,
you can always invoke a command to toggle the bindings:

    :VDtoggleKeys
    
The key bindings are also restored upon exit from the debugger.

If you are using the GUI version, gvim, VimDebug will install a "Debugger"
menu. At first only a "Start" entry will be available, to launch the debugger,
prompting for arguments. Once launched, this entry becomes disabled and a
"Toggle key bindings" one becomes available instead, as well as entries for
the debugger commands. These entries show the corresponding key bindings that
can be used; if the key bindings have been toggled back to your previous
bindings, they will be shown in parentheses.

If you don't like the default start key or other key bindings, you can always
change them by editing VimDebug.vim.

==============================================================================
5. Key bindings                     *VimDebug-bindings*

These are the default key bindings. To change them edit VimDebug.vim.

<F12>         Start the debugger, or toggle the key bindings.
<F11>         Exit the debugger.
<F10>         Restart the debugger. Breakpoints are saved.

<F9>          Continue.
<F8>          Next.
<F7>          Step in.
<F6>          Step out.

<Leader>b     Set breakpoint on the current line.
<Leader>c     Clear breakpoint on the current line.
<Leader>ca    Clear all breakpoints.

<Leader>x     Print the value of the variable under the cursor
<Leader>x/    Print the value of an expression thats entered.
<Leader>/     Type a command for the debugger to execute and echo the result.