
Pyclewn allows using vim_ as a front end to a debugger. Pyclewn currently
supports gdb_ and pdb_.

The debugger output is redirected to a vim window, the pyclewn console. The
debugger commands are mapped to vim user-defined commands with a common letter
prefix, and with completion available on the commands and their first argument.

On unix when running gvim, the controlling terminal of the program to debug is
the terminal used to launch pyclewn. Any other terminal can be used when the
debugger allows it, for example after using the ``attach`` or ``tty`` gdb
commands or using the ``--tty`` option with pdb. On Windows, gdb pops up a
console attached to the program to debug.

Features
--------

* A debugger command can be mapped in vim to a key sequence using vim key
  mappings. This allows, for example, to set/clear a breakpoint or print a
  variable value at the current cursor or mouse position by just hitting a
  key.

* A sequence of gdb commands can be run from a vim script when the ``async``
  option is set. This may be useful in a key mapping.

* Breakpoints and the line in the current frame, are highlighted in the source
  code. Disabled breakpoints are noted with a different highlighting color.
  Pyclewn automatically finds the source file for the breakpoint if it exists,
  and tells vim to load and display the file and highlight the line.

* Multiple consecutive pyclewn sessions can be started from within vim with
  the ``:Pyclewn`` command.

* The value of an expression or variable is displayed in a balloon in gvim when
  the mouse pointer is hovering over the selected expression or the variable.

* Similarly to gdb, one may attach to a running python process with the pdb
  debugger, interrupt the process, manage a debugging session and terminate
  the debugging session by detaching from the process. A new debugging session
  may be conducted later on this same process, possibly from another Vim
  instance.

* An expression can be watched in a vim window. The expression value is
  updated and highlighted whenever it has changed. When the expression is a
  structure or class instance, it can be expanded (resp. folded) to show
  (resp. hide) its members and their values. This feature is only available
  with gdb.

* The ``project`` command saves the current gdb settings to a project file
  that may be sourced later by the gdb ``source`` command. These settings are
  the working directory, the debuggee program file name, the program arguments
  and the breakpoints. The sourcing and saving of the project file can be
  automated to occur on each gdb startup and termination, with the
  ``project`` command line option. The ``project`` command is currently only
  available with gdb.

* Vim command completion on the commands and their first argument.

.. note::

   Pyclewn uses the ``netbeans`` protocol to interact with vim. Vim
   implementation of netbeans in ``plain vim`` (vim running in a terminal) is
   available since vim version 7.3.

   The vim ``:nbstart`` command that allows pyclewn to be started from within
   vim, is available since vim version 7.3.

   Support of Python 3 is available since pyclewn 1.6.

Comparison of clewn, vimGdb and pyclewn
---------------------------------------

The following table lists the differences between clewn, vimGdb and pyclewn
(clewn and vimGdb are hosted at clewn_).

    +---------------+-------------+-----------------------+------------------------+
    |               | vimGdb      | clewn                 | pyclewn                |
    +===============+=============+=======================+========================+
    | platform      | unix        | unix                  | all unix platforms     |
    |               |             |                       | supported by python -  |
    |               |             |                       | requires GNU gdb from  |
    |               |             |                       | macports on Mac Os X   |
    |               |             |                       |                        |
    |               |             |                       | Windows (Python 3 only)|
    +---------------+-------------+-----------------------+------------------------+
    | language      | C           | C                     | Python 2.4 and         |
    |               |             |                       | above                  |
    |               |             |                       | Python 3               |
    +---------------+-------------+-----------------------+------------------------+
    | vim mode      | vim in a    | gvim                  | vim in a               |
    |               | terminal,   |                       | terminal (vim 7.3      |
    |               | gvim        |                       | or above **required**),|
    |               |             |                       | gvim                   |
    +---------------+-------------+-----------------------+------------------------+
    | vim interface | a vim patch | a standalone program  | a standalone program   |
    |               |             | connected to gvim with| connected to vim with  |
    |               |             | a netbeans socket     | a netbeans socket      |
    |               |             |                       |                        |
    |               |             |                       | pyclewn may be started |
    |               |             |                       | from within vim        |
    +---------------+-------------+-----------------------+------------------------+
    | vim version   | a different | vim 6.3 and above     | vim 7.0 and above      |
    |               | patch for   |                       |                        |
    |               | each vim    |                       |                        |
    |               | version     |                       |                        |
    +---------------+-------------+-----------------------+------------------------+
    | debuggers     | gdb         | gdb                   | gdb, pdb               |
    |               |             |                       |                        |
    +---------------+-------------+-----------------------+------------------------+
    | gdb features  |             | * watched variables   | * tight integration    |
    |               |             |                       |   with vim             |
    |               |             | * project file        |                        |
    |               |             |                       | * gdb/mi interface     |
    |               |             |                       |                        |
    |               |             |                       | * asynchronous gdb     |
    |               |             |                       |   commands             |
    |               |             |                       |                        |
    |               |             |                       | * watched variables    |
    |               |             |                       |                        |
    |               |             |                       | * project file         |
    +---------------+-------------+-----------------------+------------------------+
    | pdb features  |             |                       | * interrupt the        |
    |               |             |                       |   debuggee             |
    |               |             |                       |                        |
    |               |             |                       | * attach to a running  |
    |               |             |                       |   python process       |
    |               |             |                       |                        |
    |               |             |                       | * the ``threadstack``  |
    |               |             |                       |   command              |
    +---------------+-------------+-----------------------+------------------------+

Licensing
---------

This software is licensed under the GNU General Public License Version 2.

Copyright © 2001-2012 Python Software Foundation; All Rights Reserved.
pdb-clone is a derivative work of a part of Python and as such, subject to the
python license_.

.. toctree::
   :maxdepth: 2
   :hidden:

   news
   install
   faq
   mercurial
   vim-patches

.. _vim: http://www.vim.org/
.. _gdb: http://www.gnu.org/software/gdb/gdb.html
.. _pdb: http://docs.python.org/library/pdb.html
.. _clewn: http://clewn.sourceforge.net
.. _license: http://docs.python.org/2.7/license.html
.. vim:filetype=rst:tw=78:ts=8:et:

