*pyclewn.txt* Last change: 2013 September 10 PYCLEWN USER MANUAL The Pyclewn user guide *pyclewn* 1. Introduction |pyclewn-intro| 2. Starting pyclewn |:Pyclewn| 3. Options |pyclewn-options| 4. Using pyclewn |pyclewn-using| 5. Gdb |pyclewn-gdb| 6. Pdb |pyclewn-pdb| 7. Windows |pyclewn-windows| 8. Key mappings |pyclewn-mappings| 9. Watched variables |pyclewn-variable| 10. Extending pyclewn |pyclewn-extending| ============================================================================== 1. Introduction *pyclewn-intro* Pyclewn is a python program that allows the use of vim as a front end to a debugger. Pyclewn supports the gdb and the pdb debuggers. Pyclewn uses the netbeans protocol to control vim. 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 (the default is the|C|letter), and with vim command 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. Pyclewn currently supports the following debuggers: * gdb: version 6.2.1 and above, pyclewn uses the gdb MI interface * pdb: the Python debugger * simple: a fake debugger implemented in python to test pyclewn internals Pyclewn provides the following 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. * 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, whith the |project-file|command line option. The ``project`` command is currently only available with gdb. * Vim command completion on the commands and their first argument. The remaining sections of this manual are: ----------------------------------------- 2.|:Pyclewn|explains how to start pyclewn. 3.|pyclewn-options|lists pyclewn options and their usage. 4.|pyclewn-using|explains how to use the pyclewn features common to all supported debuggers 5.|pyclewn-gdb|details the topics relevant to pyclewn and the gdb debugger. 6.|pyclewn-pdb|details the topics relevant to pyclewn and the pdb debugger. 7.|pyclewn-windows|describes what is specific to pyclewn on Windows. 8.|pyclewn-mappings|lists the pyclewn key mappings and how to use them. 9.|pyclewn-variable|explains how to use the variable debugger window with gdb. 10.|pyclewn-extending|explains how to implement a new debugger in pyclewn ============================================================================== 2. Starting pyclewn *:Pyclewn* Start pyclewn from vim: ----------------------- The|:Pyclewn|vim command requires at least vim 7.3. To start pyclewn with the gdb debugger: > :Pyclewn To start pyclewn with the pdb debugger: > :Pyclewn pdb [script.py] Next, the gdb debugger is started by running a debugger command from vim command line. For example, load foobar with the gdb command "file" and start gbd by typing on the vim command line: > :Cfile foobar To just start gdb with a command that does not have any effect: > :Cecho To terminate pyclewn and the vim netbeans interface, run the following command: > :nbclose To know if the netbeans interface is connected, run the following command: > :echo has("netbeans_enabled") The|:Pyclewn|command is provided by the vim plugin installed as the "pyclewn.vim" file in vim plugin directory. Pyclewn command line arguments and connection details may be set with the "pyclewn_args" and the "pyclewn_connection" vim global variables. For further customization you can edit the "pyclewn.vim" file in vim autoload directory. The|:Pyclewn|command does the following: * spawn pyclewn * start the vim netbeans interface and connect it to pyclewn * source a script automatically generated by pyclewn containing utility functions and the debugger commands as vim commands Start the pyclewn process: -------------------------- Pyclewn with the gdb debugger is simply started as: > pyclewn On Windows, pyclewn is started with a Desktop shortcut that runs pyclewn.bat. The pyclewn.bat file is located in the Scripts directory of the python distribution. ============================================================================== 3. Options *pyclewn-options* The pyclewn options can be set: * on pyclewn command line * in the "pyclewn_args" and the "pyclewn_connection" vim global variables when starting pyclewn with the|:Pyclewn|command * as the keyword parameters of the pdb function options: --version show program's version number and exit -h, --help show this help message and exit -s, --simple select the simple debugger --pdb select 'pdb', the python debugger --run allow the debuggee to run after the pdb() call (default 'False') --tty=TTY use TTY for input/output by the python script being debugged (default '/dev/null') -g PARAM_LIST, --gdb=PARAM_LIST select the gdb application (the default), with a mandatory, possibly empty, PARAM_LIST --terminal=TERMINAL set the terminal to use with the inferiortty command for running gdb or pdb inferior (default 'xterm,-e') -d, --daemon run as a daemon (default 'False') -p PGM, --pgm=PGM set the debugger program to PGM -a ARGS, --args=ARGS set the debugger program arguments to ARGS -e EDITOR, --editor=EDITOR set the Vim program to EDITOR; Vim is not spawned by pyclewn when this parameter is set to an empty string -c ARGS, --cargs=ARGS set the Vim program arguments to ARGS -w LOCATION, --window=LOCATION open the debugger console window at LOCATION which may be one of (top, bottom, left, right), the default is top -m LNUM, --maxlines=LNUM set the maximum number of lines of the debugger console window to LNUM (default 10000 lines) -x PREFIX, --prefix=PREFIX set the commands prefix to PREFIX (default|C|) -b COLORS, --background=COLORS COLORS is a comma separated list of the three colors of the breakpoint enabled, breakpoint disabled and frame sign background colors, in this order (default 'Cyan,Green,Magenta') -n CONN, --netbeans=CONN set netBeans connection parameters to CONN with CONN as 'host[:port[:passwd]]', (the default is ':3219:changeme' where the empty host represents INADDR_ANY) -l LEVEL, --level=LEVEL set the log level to LEVEL: critical, error, warning, info, debug or nbdebug (default error) -f FILE, --file=FILE set the log file name to FILE The full description of pyclewn options follows: ------------------------------------------------ --version Show program's version number and exit. -h --help Show this help message and exit. -s --simple Select the simple debugger. In that case, the --pgm and --args options are meaningless. The simple debugger is documented in debugger/simple.py, in the source distribution. --pdb Select 'pdb', the python debugger. --run By default the python debuggee is stopped at the first statement after the call to pdb(). Enabling this option allows the debuggee to run after the call to pdb(). --tty={TTY} Use TTY for input/output by the python script being debugged. The default is "/dev/null". -g {PARAM_LIST} --gdb={PARAM_LIST} Select the gdb debugger (the default). The default value of the "pgm" option is "gdb". The PARAM_LIST option parameter is a comma separated list of parameters and is mandatory when the option is present. So, to run gdb with no specific parameter, the following commands are equivalent: > pyclewn pyclewn -g "" pyclewn --gdb= . There are three optional parameters: * the "async" keyword sets the|async-option| * the "nodereference" keyword, see|gdb-balloon|. * the project file name sets the|project-file| The project file name can be an absolute pathname, a relative pathname starting with '.' or a home relative pathname starting with '~'. The directory of the project file name must be an existing directory. For example on unix: > pyclewn --gdb=async,./project_name --terminal=TERMINAL Set the terminal to use with the inferiortty command for running gdb or pdb inferior (default 'xterm,-e'). The option is a comma separated list of the arguments needed to start the terminal and a program running in this terminal. -d --daemon Run as a daemon (default 'False'): on unix, pyclewn is detached from the terminal from where it has been launched, which means that this terminal cannot be used as a controlling terminal for the program to debug, and cannot be used for printing the pyclewn logs as well. On Windows, this option hides the pyclewn Windows console and it is set on the shortcut that is installed on the Desktop. -p {PGM} --pgm={PGM} Set the debugger program to PGM. PGM must be in one of the directories listed in the PATH environment variable. -a {ARGS} --args={ARGS} Set the debugger program arguments to ARGS. These arguments may be double quoted. For example, start gdb with the program foobar and "this is foobar argument" as foobar's argument: > pyclewn -a '--args foobar "this is foobar argument"' -e {EDITOR} --editor={EDITOR} Set the editor program to EDITOR. EDITOR must be in one of the directories listed in the PATH environment variable, or the full pathname to vim or gvim executable. When this command line option is not set, pyclewn uses the value of the EDITOR environment variable, and if this environment variable is not set either, then pyclewn defaults to using "gvim" as the name of the program to spawn. -c {ARGS} --cargs={ARGS} Set the editor program arguments to ARGS, possibly double quoted (same as option --args). -w {LOCATION} --window={LOCATION} The debugger console window pops up at LOCATION, which may be one of top, bottom, left, right or none. The default is top. In the left or right case, the window pops up on the left (resp. right) if there is only one window currently displayed, otherwise the debugger window is opened at the default top. When LOCATION is none, the automatic display of the console is disabled. -m {LNUM} --maxlines={LNUM} Set the maximum number of lines of the debugger console window to LNUM (default 10000 lines). When the number of lines in the buffer reaches LNUM, 10% of LNUM first lines are deleted from the buffer. -x {PREFIX} --prefix={PREFIX} Set the user defined vim commands prefix to PREFIX (default|C|). The prefix may be more than one letter long. The first letter must be upper case. -b {COLORS} --background={COLORS} COLORS is a comma separated list of the three colors of the breakpoint enabled, breakpoint disabled and frame sign background colors, in this order (default 'Cyan,Green,Magenta'). The color names are case sensitive. See|highlight-ctermbg|for the list of the valid color names. This option has no effect when vim version is vim72 or older. -n {CONN} --netbeans={CONN} Set netBeans connection parameters to CONN with CONN as 'host[:port[:passwd]]', (the default is ':3219:changeme' where the empty host represents INADDR_ANY). Pyclewn listens on host:port, with host being a name or the IP address of one of the local network interfaces in standard dot notation. These parameters must match those used by vim for the connection to succeed. -l {LEVEL} --level={LEVEL} Set the log level to LEVEL: critical, error, warning, info, debug or nbdebug (default critical). Level nbdebug is very verbose and logs all the netbeans pdu as well as all the debug traces. Critical error messages are printed on stderr. No logging is done on stderr (including critical error messages) when the "--level" option is set to something else than "critical" and the "--file" option is set. -f {FILE} --file={FILE} Set the log file name to FILE. On unix, when the 'CLEWN_PIPES' environment variable is set, pyclewn uses pipes instead of a pseudo tty to communicate with gdb and emulates the select event loop with threads. When the 'CLEWN_POPEN' environment variable is set, pyclewn uses pipes instead of a pseudo tty but continues using the select event loop. These variables are mainly used for regression testing. ============================================================================== 4. Using pyclewn *pyclewn-using* *pyclewn-console* Console: -------- The debugger output is redirected to a vim window: the console. The console window pops up whenever a|Ccommand|is entered on vim command line or a key mapped by pyclewn is hit. This behavior may be disabled by setting to `none` the `window`|pyclewn-options|and may be useful when using Vim tabs and wanting to keep the console in a tab of its own. In this case, the cursor position in the console is not updated by pyclewn, so you need to set manually the cursor at the bottom of the console, the first time you open (clewn)_console. The initial console window height is set with the vim option 'previewheight' that defaults to 12 lines. Commands: *Ccommand* *C* --------- The prefix letter|C|is the default vim command prefix used to map debugger commands to vim user-defined commands. These commands are called|Ccommand|in this manual. The prefix can be changed with a command line option. A debugger command can be entered on vim command line with the|C|prefix. It is also possible to enter the command as the first argument of the|C|command. In the following example with gdb, both methods are equivalent: > :Cfile /path/to/foobar :C file /path/to/foobar The first method provides completion on the file name while the second one does not. The second method is useful when the command is a user defined command in the debugger (user defined commands built by in gdb), and therefore not a vim command. It is also needed for gdb command names that cannot be mapped to a vim command because vim does not accept non alphanumeric characters within command names (for example in gdb). To get help on the pyclewn commands, use Chelp. Pyclewn commands can be mapped to keys, or called within a Vim script or a menu. Note: The gdb debugger cannot handle requests asynchronously, so the |async-option|must be set, when mapping a key to a sequence of commands. With this option set, one can build for example the following mapping: > :map :Cfile /path/to/foobar Cbreak main Crun Note: Quotes and backslashes must be escaped on vim command line. For example, to print foo with a string literal as first argument to the foo function: > :Cprint foo(\"foobar\", 1) And to do the same thing with the string including a new line: > :Cprint foo(\"foobar\\n\", 1) Completion: ----------- Command line completion in vim is usually done using the key (set by the 'wildchar' option). To get the list of all valid completion matches, type CTRL-D. For example, to list all the debugger commands (assuming the default|C|prefix is being used): > :C See also the 'wildmenu' option. With this option, the possible matches are shown just above the command line and can be selected with the arrow keys. The first argument completion of a|Ccommand|may be done on a file name or on a list. For example with gdb, the following command lists all the gdb help items: > :Chelp The first argument completion of the|C|command is the list of all the debugger commands. For example, to list all the debugger commands (note the space after the|C|): > :C Command line search: -------------------- Use the powerful command line search capabilities of the Vim command line. For example, you want to type again, possibly after a little editing, one of the commands previously entered: > :Cprint (*(foo*)0x0123ABCD)->next->next->part1->something_else.aaa You can get rapidly to this command by using the Vim command line window |cmdline-window|: > : /something_else or from normal mode > q: /something_else Vim in a terminal ----------------- The debuggee output is redirected to '/dev/null' when the name of the program is "vim" or "vi". One must use the "set inferior-tty" gdb command to redirect the debuggee output to a terminal. Do not use the "--daemon" command line option when running vim in a console. Balloon: -------- A variable is evaluated by the debugger and displayed in a balloon in gvim, when the mouse pointer is hovering over the the variable. To get the evaluation of an expression, first select the expression in visual mode in the source code and point the mouse over the selected expression. To disable this feature, set the vim option 'noballooneval'. ============================================================================== 5. Gdb *pyclewn-gdb* When gdb is started, it automatically executes commands from its init file, normally called '.gdbinit'. See the gdb documentation. Debuggee standard input and output: ----------------------------------- On Windows, gdb pops up a console attached to the program to debug. *inferior_tty* On unix, when starting pyclewn from a terminal and using gvim, pyclewn creates a pseudo terminal that is the the controlling terminal of the program to debug. Programs debugged by gdb, including those based on curses and termios such as vim, run in this terminal. A typed in the terminal interrupts the debuggee. When pyclewn is started from vim with the|:Pyclewn|command, there is no terminal associated with pyclewn. The|inferiortty|command provides the same functionality as above and spawns the controlling terminal (using the --terminal option, default xterm) of the debuggee and sets accordingly gdb 'inferior-tty' variable and the TERM environment variable. The gdb 'inferior-tty' variable MUST be set BEFORE the inferior is started. One can also do step by step what the above command does automatically: start the "inferior_tty.py" script installed with pyclewn. This script creates a pseudo terminal to be used as the controlling terminal of the process debugged by gdb. For example, to debug vim (not gvim) and start the debugging session at vim's main function. From pyclewn, spawn an xterm terminal and launch "inferior_tty.py" in this terminal: > :Cfile /path/to/vim :Cshell setsid xterm -e inferior_tty.py & "inferior_tty.py" prints the name of the pseudo terminal to be used by gdb and the two gdb commands needed to configure properly gdb with this terminal. Copy and paste these two commands in vim command line: > :Cset inferior-tty /dev/pts/nn :Cset environment TERM = xterm Then start the debugging session of vim and stop at vim main(): > :Cstart Note: * is necessary to prevent gdb from killing the xterm process when a is typed from gdb to interrupt the debuggee. This is not needed when the terminal emulator is not started from gdb. *async-option* Async option: ------------- The gdb event loop is not asynchronous in most configurations, which means that gdb cannot handle a command while the previous one is being processed and discards it. When gdb is run with the|async-option|set, pyclewn queues the commands in a fifo and send a command to gdb, only when gdb is ready to process the command. This allows the key mappings of a sequence of gdb commands. To set the |async-option|, see|pyclewn-options|. *gdb-keys* List of the gdb default key mappings: ------------------------------------- These keys are mapped after the|Cmapkeys|vim command is run. CTRL-Z send an interrupt to gdb and the program it is running (unix only) B info breakpoints L info locals A info args S step CTRL-N next: next source line, skipping all function calls F finish R run Q quit C continue W where X foldvar CTRL-U up: go up one frame CTRL-D down: go down one frame cursor position: ~ CTRL-B set a breakpoint on the line where the cursor is located CTRL-E clear all breakpoints on the line where the cursor is located mouse pointer position: ~ CTRL-P print the value of the variable defined by the mouse pointer position CTRL-X print the value that is referenced by the address whose value is that of the variable defined by the mouse pointer position *$cdir* Source path: ----------- Pyclewn automatically locates the source file with the help of gdb, by using the debugging information stored in the file that is being debugged. This is useful when the program to debug is the result of multiple compilation units located in different directories. *Csymcompletion* Symbols completion: ------------------- The gdb and commands are set initially with file name completion. This can be changed to completion matching the symbols of the program being debugged, after running the|Csymcompletion|command. This is a pyclewn command. To minimize the number of loaded symbols and to avoid fetching the shared libraries symbols, run the Csymcompletion command after the file is loaded with the gdb command, and before the program is run. Note: The and filename completion is not the same as gdb file name completion for these two commands. Gdb uses the symbols found in the program file to debug, while pyclewn uses only the file system. *gdb-balloon* Balloon evaluation: ------------------- The gdb command is used by pyclewn to get the type of the variable or the type of the selected expression that is being hovered over by the mouse. When it is a pointer to data, the pointer is dereferenced and its value displayed in the vim balloon. The paramater of the "--gdb" option named "nodereference" disables this feature: the balloon prints the pointer address value. *project-command* *project-file* Project file: ------------- The pyclewn|project-command|name is "project". This command saves the current gdb settings to a project file that may be sourced later by the gdb "source" command. These settings are: * current working directory * debuggee program file name * program arguments * all the breakpoints (at most one breakpoint per source line is saved) The argument of the|project-command|is the pathname of the project file. For example: > :Cproject /path/to/project When the "--gdb" option is set with a project filename (see|pyclewn-options|), the project file is automatically sourced when a a gdb session is started, and the project file is automatically saved when the gdb session or vim session, is terminated. Note: When gdb sources the project file and cannot set a breakpoint because, for example, it was set in a shared library that was loaded at the time the project file was saved, gdb ignores silently the breakpoint (see gdb help on "set breakpoint pending"). Limitations: ------------ When pyclewn cannot setup a pseudo tty to communicate with gdb, pyclewn falls back to pipes. In this case, the Csigint command does not work as gdb does not handle interrupts over a pipe. Instead, one must send a SIGINT signal to the debuggee in order to interrupt the debuggee while it is running. This can be done from Vim with the command: > :!kill -SIGINT $(pgrep debuggee_process_name) On Windows, it is not possible to interrupt gdb with the Csigint command, but you can type in the console to interrupt the debuggee. When setting breakpoints on an overloaded method, pyclewn bypasses the gdb prompt for the multiple choice and sets automatically all breakpoints. In order to set a pending breakpoint (for example in a shared library that has not yet been loaded by gdb), you must explicitly set the breakpoint pending mode to "on", with the command: > :Cset breakpoint pending on After a "detach" gdb command, the frame sign remains highlighted because gdb/mi considers the frame as still valid. When answering "Abort" to a dialog after pyclewn attempts to edit a buffer and set a breakpoint in a file already opened within another Vim session, the breakpoint is set in gdb, but not highlighted in the corresponding buffer. However, it is possible to|bwipeout|a buffer at any time, and load it again in order to restore the correct highlighting of all the breakpoints in the buffer. Pyclewn commands: ----------------- The|Ccommand|list includes all the gdb commands and some pyclewn specific commands that are listed here: *|Ccwindow| opens a vim quickfix window holding the list of the breakpoints with their current state; the quickfix window allows moving directly to any breakpoint (requires the vim|+quickfix|feature) *|Cdbgvar| add a watched variable or expression to the (clewn)_dbgvar buffer *|Cdelvar| delete a watched variable from the (clewn)_dbgvar buffer * Cdumprepr print on the console pyclewn internal structures that may be used for debugging pyclewn *|Cfoldvar| collapse/expand the members of a watched structure or class instance * Chelp print on the console, help on the pyclewn specific commands (those on this list) in addition to the help on the debugger commands *inferiortty* * Cinferiortty spawn the controlling terminal (default xterm) of the debuggee and sets accordingly gdb 'inferior-tty' variable and the TERM environment variable; this command MUST be issued BEFORE starting the inferior. * Cloglevel print or set the log level dynamically from inside Vim *|Cmapkeys| map pyclewn keys *|Cproject| save the current gdb settings to a project file *|Csetfmtvar| set the output format of the value of a watched variable * Csigint send a character to the debugger to interrupt the running program that is being debugged; only with gdb, and when pyclewn and gdb communicate over a pseudo terminal, which means on unix but not on Windows; on Windows, to interrupt the debuggee, one must type in the console that is popped by gdb on debuggee start up *|Csymcompletion|populate the break and clear commands with symbols completion (only with gdb) * Cunmapkeys unmap the pyclewn keys, this vim command does not invoke pyclewn List of illegal gdb commands: ----------------------------- The following gdb commands cannot be run from pyclewn: complete edit end set annotate set confirm set height set width shell ============================================================================== 6. Pdb *pyclewn-pdb* Start a python script from Vim and debug it, or attach to a running python process and start the debugging session. Start a python script from Vim and debug it: ------------------------------------------- To debug a python script named "script.py", run the vim command (arg1, arg2, ... being the script.py command line arguments): > :Pyclewn pdb script.py arg1 arg2 ... Or, more conveniently, debug the python script being edited in vim as the current buffer with: > :Pyclewn pdb %:p On unix, the script is started without a controlling terminal unless the "tty" option has been set (see below). The|Cinferiortty|command spawns a controlling terminal (using the --terminal option that defaults to xterm) connected to a pseudo tty, and redirects all three standard streams of the script to this pseudo tty. One may also redirect the script output to another tty, using the "tty" option and setting the "pyclewn_args" vim global variable before starting the script. For example: > :let g:pyclewn_args="--tty=/dev/pts/4" The ":Cquit" command and the Vim ":quitall" command terminate the debugging session and the script being debugged. Both commands MUST be issued at the pdb prompt. Attach to a python process and debug it: > ---------------------------------------- To debug a python process after having attached to it, first insert the following statement in the debuggee source code before starting it: > import clewn.vim as vim; vim.pdb() By default, the debuggee is stopped at the first statement following the call to vim.pdb(). To let the debuggee run instead, then use the "run" option: > import clewn.vim as vim; vim.pdb(run=True) Next, attach to the process and start the debugging session by running the vim command: > :Pyclewn pdb Notes: When the pyclewn installation has been made following the "home scheme" (see INSTALL) and in order to have python find the clewn package, one must set the PYTHONPATH environment variable to include the python home library pathname. For example with bash, run the script as: > PYTHONPATH=$HOME/lib/python python script_pathname The current debugging session may be terminated with the ":Cdetach" or the Vim ":quitall" command. Another debugging session with the same process can be started later with the ":Pyclewn pdb" command. The ":Cdetach", ":Cquit" or the Vim ":quitall" commands do not terminate the debuggee. To kill the debuggee, issue the following command at the pdb prompt: > :C import sys; sys.exit(1) On posix platforms, when the python process is not attached, typing two instead of one, is needed to kill the process. This is actually a feature that allows the process to run without any tracing overhead (before the first ) when it is not attached and no breakpoints are being set (there is still the small overhead of the context switches between the idle clewn thread and the process threads). Pdb commands: ------------- The commands "interrupt", "detach" and "threadstack" are new pdb commands and are the only commands that are available at the "[running...]" prompt when the debuggee is running. Use the "help" command (and completion on the first argument of the help command) to get help on each command. The following list describes the pdb commands that are new or behave differently from the pdb commands of the Python standard library: *Cinterrupt* interrupt This command interrupts the debuggee and is available from the "[running...]" prompt. *Cinferiortty* inferiortty Without argument, the pdb command "inferiortty" spawns a terminal connected to a pseudo tty and redirects all three standard streams to this pseudo tty. With the name of an existing pseudo tty as an argument, "inferiortty' redirects all three standard streams to this pseudo tty (convenient for re-using the same pseudo tty across multiple debugging sessions). This command can be issued after the script has been started. Available on unix. *Cdetach* detach This command terminates the debugging session by closing the netbeans socket. The debuggee is free to run and does not stop at the breakpoints. To start another debugging session, run the command: > :Pyclewn pdb . The breakpoints becomes effective again when the new session starts up. Available from the "[running...]" prompt and from the pdb prompt. *Cquit* quit This command terminates the debugging session by closing the netbeans socket, and removes the python trace function. The pyclewn thread in charge of handling netbeans connection terminates and it is not possible anymore to attach to the process. Since there is no trace function, the breakpoints are ineffective and the process performance is not impaired anymore by the debugging overhead. When the script has been started from Vim, this command terminates the script. *Cthreadstack* threadstack The command uses the sys._current_frames() function from the standard library to print a stack of the frames for all the threads. The function sys._current_frames() is available since python 2.5. Available from the "[running...]" prompt and from the pdb prompt. *Cclear* clear This command is the same as the Python standard library "clear" command, except it requires at least one parameter and therefore, it is not possible to clear all the breakpoints in one shot with the "clear" command without parameters. the prefix alone: There is no "!" pdb command as in the Python standard library since Vim does not allow this character in a command name. However, the equivalent way to execute a python statement in the context of the current frame is with the command prefix alone, for example: > :C global list_options; list_options = ['-l'] :C import sys; sys.exit(1) . The first word of the statement must not be a pdb command and will be expanded if it is an alias. not implemented: The following pdb commands are not implemented: list, ll, whatis, source, display, undisplay, interact, run, restart. *pdb-pdbrc* The initialisation file .pdbrc: ------------------------------- This file is read at initialisation and its commands are executed on startup. See the pdb python documentation for the location of this file. Breakpoints can be set through this file, or aliases may be defined. One useful alias entered in the file would be for example: > alias kill import sys; sys.exit(1) So that the debuggee may be killed with the command: > :C kill *pdb-keys* List of the pdb default key mappings: ------------------------------------- These keys are mapped after the|Cmapkeys|vim command is run. CTRL-Z interrupt the pdb process B list all breaks, including for each breakpoint, the number of times that breakpoint has been hit, the current ignore count, and the associated condition if any A print the argument list of the current function S step CTRL-N next: next source line, skipping all function calls R continue execution until the current function returns C continue W where CTRL-U up: go up one frame CTRL-D down: go down one frame cursor position: ~ CTRL-B set a breakpoint on the line where the cursor is located CTRL-E clear all breakpoints on the line where the cursor is located mouse pointer position: ~ CTRL-P print the value of the selected expression defined by the mouse pointer position Pyclewn commands: ----------------- The|Ccommand|list includes pdb commands and some pyclewn specific commands that are listed here: * Cdumprepr print on the console pyclewn internal structures that may be used for debugging pyclewn * Cloglevel print or set the log level dynamically from inside Vim *|Cmapkeys| map pyclewn keys * Cunmapkeys unmap the pyclewn keys, this vim command does not invoke pyclewn Troubleshooting: ---------------- * Pyclewn error messages can be logged in a file with the "--file" option. When starting the debuggee from vim, use the "pyclewn_args" vim global variable before starting the script: > :let g:pyclewn_args="--file=/path/to/logfile" When attaching to a python process, use the corresponding keyword argument: > import clewn.vim as vim; vim.pdb(file='/path/to/logfile') * To conduct two debugging sessions simultaneously (for example when debugging pyclewn with pyclewn), change the netbeans socket port with the "pyclewn_connection" vim global variable before starting the script: > :let g:pyclewn_connection="localhost:3220:foo" And change the corresponding keyword argument: > import clewn.vim as vim; vim.pdb(netbeans='localhost:3220:foo') Limitations: ------------ On Windows, the netbeans session is not closed in Vim after the Python script terminates normaly. The Vim ":nbclose" command must be issued in order to start a new debugging session. See Vim issue 107 at http://code.google.com/p/vim/. The|Cinterrupt|command does not properly interrupt the input() Python function. Workaround: after the Cinterrupt command has been issued while at the prompt displayed by input(), enter some data to allow the input() function to complete execution of its C code implementation, this allows pdb to gain control when back in python code and to stop. ============================================================================== 7. Windows *pyclewn-windows* Installation: ------------- See http://pyclewn.wiki.sourceforge.net/install for installing pyclewn on Windows. If pyclewn does not start once installed, edit the desktop shortcut and add "-l debug -f \path\to\logfile.txt" to the command line. Check the content of logfile.txt. When pyclewn stops with the following error in the logfile: gdb CRITICAL cannot start gdb as "C:\msys\mingw\bin\gdb.exe" This means you have to update the shortcut command line with the correct path to gdb. Interrupt the debuggee: ----------------------- Gdb is started with the "console-new" gdb variable set to on. When you start the debuggee, gdb pops up the console attached to the debuggee. You can type in the console to interrupt the debuggee. If this console bothers you, run the following gdb command: > :Cset new-console off Escape quotes: -------------- The following is true as well for pyclewn on unix, but since pathnames containing space characters are common on Windows, it may be useful to recall that quotes must be escaped on Vim command line. For example one could write: > :Cfile \"\path with space\to\foobar.exe\" ============================================================================== 8. Key mappings *pyclewn-mappings* All|Ccommand|can be mapped to vim keys using the vim|:map-commands|. For example, to set a breakpoint at the current cursor position: > :map :exe "Cbreak " . expand("%:p") . ":" . line(".") Or to print the value of the variable under the cursor: > :map :exe "Cprint " . expand("") *Cmapkeys* Pyclewn key mappings: --------------------- This section describes another mapping mechanism where pyclewn maps vim keys by reading a configuration file. This is done when the|Cmapkeys|vim command is run. The pyclewn keys mapping is mostly useful for the pyclewn casual user. When the configuration file cannot be found, pyclewn sets the default key mappings. See|gdb-keys|for the list of default key mappings for gdb and|pdb-keys|for the list of default key mappings for pdb. Please note that pyclewn relies on the vim|balloon-eval|feature to get the text under the mouse position when expanding the ${text} macro. This feature is not available with vim console. So in this case you must build your own key mapping as in the above example. The configuration file is named .pyclewn_keys.{debugger}, where debugger is the name of the debugger. The default placement for this file is $CLEWNDIR/.pyclewn_keys.{debugger}, or $HOME/.pyclewn_keys.{debugger}. To customize pyclewn key mappings copy the configurations files found in the distribution to the proper directory: > cp runtime/.pyclewn_keys.gdb $CLEWNDIR or > cp runtime/.pyclewn_keys.gdb $HOME The comments in the configuration file explain how to customize the key mappings. On Windows, the .pyclewn_keys.{debugger} configuration files are found in the directory $VIM\vimfiles\macros. The value of $VIM can be obtained by running the following command in Vim: > :echo $VIM Copy these files to the $CLEWNDIR or $HOME directory, and customize the key mappings. ============================================================================== 9. Watched variables *pyclewn-variable* The Watched Variables feature is available with the gdb debugger. The vim watched variables buffer is named "(clewn)_dbgvar". *Cdbgvar* The|Cdbgvar|command is used to create a gdb watched variable in the variables buffer from any valid expression. A valid expression is an expression that is valid in the current frame. The argument of the|Cdbgvar|pyclewn command is the expression to be watched. For example, to create a watched variable for the expression "len - max": > :Cdbgvar len - max Upon creation, the watched variable is given a name by gdb, for example: . The watched variables buffer, "(clewn)_dbgvar", is created upon creation of the first watched variable. It is created but not displayed in a window. To display "(clewn)_dbgvar" just after the creation of the first variable: > :e # or > CTL-^ Use the following command to find the number N of the "(clewn)_dbgvar" buffer: > :ls Knowing N, the following commands display the "(clewn)_dbgvar" buffer: > :Nb or > N CTL-^ To split the current window and display "(clewn)_dbgvar": > :Nsb . *Cfoldvar* When the watched variable is a structure or class instance, it can be expanded with the|Cfoldvar|pyclewn command to display all its members and their values as children watched variables. The argument of the|Cfoldvar|command is the line number of the watched variable to expand, in the watched variable window. For example: > :Cfoldvar 1 The|Cfoldvar|command is meant to be used in a key mapping. This is the 'X' key when using pyclewn key mappings, or one can use the following mapping: > :map :exe "Cfoldvar " . line(".") The watched variable can also be collapsed with the|Cfoldvar|command. *Cdelvar* A gdb watched variable can be deleted with the|Cdelvar|pyclewn command. The argument of the|Cdelvar|command is the name of the variable as given by gdb upon creation. For example: > :Cdelvar var1 When the watched variable is a structure or class instance and it has been expanded, all its children are also deleted. *Csetfmtvar* Set the output format of the value of the watched variable to be : > :Csetfmtvar Parameter is the gdb/mi name of the watched variable or one of its children. Parameter is one of the strings in the following list: {binary | decimal | hexadecimal | octal | natural} The "natural" format is the default format chosen automatically based on the variable type (like "decimal" for an int, "hexadecimal" for pointers, etc.). For a variable with children, the format is set only on the variable itself, and the children are not affected. Note: The setting of the format of a child watched variable is lost after folding one of its parents (because the child is actually not watched anymore by gdb after the folding). Highlighting: ------------- When the value of a watched variable has changed, it is highlighted with the "Special" highlight group. When a watched variable becomes out of scope, it is highlighted with the "Comment" highlight group. The foreground and background colors used by these highlight groups are setup by the|:colorscheme|currently in use. ============================================================================== 10. Extending pyclewn *pyclewn-extending* NAME debugger FILE clewn/debugger.py DESCRIPTION This module provides the basic infrastructure for using Vim as a front-end to a debugger. The basic idea behind this infrastructure is to subclass the 'Debugger' abstract class, list all the debugger commands and implement the processing of these commands in 'cmd_' methods in the subclass. When the method is not implemented, the processing of the command is dispatched to the 'default_cmd_processing' method. These methods may call the 'Debugger' API methods to control Vim. For example, 'add_bp' may be called to set a breakpoint in a buffer in Vim, or 'console_print' may be called to write the output of a command in the Vim debugger console. The 'Debugger' subclass is made available to the user after adding an option to the 'parse_options' method in the 'Vim' class, see vim.py. The 'Simple' class in simple.py provides a simple example of a fake debugger front-end. CLASSES __builtin__.object Debugger class Debugger(__builtin__.object) | Abstract base class for pyclewn debuggers. | | The debugger commands received through netbeans 'keyAtPos' events | are dispatched to methods whose name starts with the 'cmd_' prefix. | | The signature of the cmd_ methods are: | | cmd_(self, str cmd, str args) | cmd: the command name | args: the arguments of the command | | The '__init__' method of the subclass must call the '__init__' | method of 'Debugger' as its first statement and forward the method | parameters as an opaque list. The __init__ method must update the | 'cmds' and 'mapkeys' dict attributes with its own commands and key | mappings. | | Instance attributes: | cmds: dict | The debugger command names are the keys. The values are the | sequence of available completions on the command first | argument. The sequence is possibly empty, meaning no | completion. When the value is not a sequence (for example | None), this indicates file name completion. | mapkeys: dict | Key names are the dictionary keys. See the 'keyCommand' | event in Vim netbeans documentation for the definition of a | key name. The values are a tuple made of two strings | (command, comment): | 'command' is the debugger command mapped to this key | 'comment' is an optional comment | One can use template substitution on 'command', see the file | runtime/.pyclewn_keys.template for a description of this | feature. | options: optparse.Values | The pyclewn command line parameters. | vim_socket_map: dict | The asyncore socket dictionary | testrun: boolean | True when run from a test suite | started: boolean | True when the debugger is started. | closed: boolean | True when the debugger is closed. | pyclewn_cmds: dict | The subset of 'cmds' that are pyclewn specific commands. | __nbsock: netbeans.Netbeans | The netbeans asynchat socket. | _jobs: list | list of pending jobs to run on a timer event in the | dispatch loop | _jobs_enabled: bool | process enqueued jobs when True | _last_balloon: str | The last balloonText event received. | prompt: str | The prompt printed on the console. | _consbuffered: boolean | True when output to the vim debugger console is buffered | | Methods defined here: | | __init__(self, options, vim_socket_map, testrun) | Initialize instance variables and the prompt. | | __str__(self) | Return the string representation. | | add_bp(self, bp_id, pathname, lnum) | Add a breakpoint to a Vim buffer at lnum. | | Load the buffer in Vim and set an highlighted sign at 'lnum'. | | Method parameters: | bp_id: object | The debugger breakpoint id. | pathname: str | The absolute pathname to the Vim buffer. | lnum: int | The line number in the Vim buffer. | | balloon_text(self, text) | Process a netbeans balloonText event. | | Used when 'ballooneval' is set and the mouse pointer rests on | some text for a moment. | | Method parameter: | text: str | The text under the mouse pointer. | | close(self) | Close the debugger and remove all signs in Vim. | | cmd_dumprepr(self, cmd, args) | Print debugging information on netbeans and the debugger. | | cmd_help(self, *args) | Print help on all pyclewn commands in the Vim debugger | console. | | cmd_loglevel(self, cmd, level) | Get or set the pyclewn log level. | | cmd_mapkeys(self, *args) | Map the pyclewn keys. | | cmd_unmapkeys(self, cmd, *args) | Unmap the pyclewn keys. | | This is actually a Vim command and it does not involve pyclewn. | | console_flush(self) | Flush the console. | | console_print(self, format, *args) | Print a format string and its arguments to the console. | | Method parameters: | format: str | The message format string. | args: str | The arguments which are merged into 'format' using the | python string formatting operator. | | debugger_background_jobs = _newf(self, *args, **kwargs) | The decorated method. | | default_cmd_processing(self, cmd, args) | Fall back method for commands not handled by a 'cmd_' | method. | | This method must be implemented in a subclass. | | Method parameters: | cmd: str | The command name. | args: str | The arguments of the command. | | delete_bp(self, bp_id) | Delete a breakpoint. | | The breakpoint must have been already set in a Vim buffer with | 'add_bp'. | | Method parameter: | bp_id: object | The debugger breakpoint id. | | get_console(self) | Return the console. | | get_lnum_list(self, pathname) | Return a list of line numbers of all enabled breakpoints in a | Vim buffer. | | A line number may be duplicated in the list. | This is used by Simple and may not be useful to other debuggers. | | Method parameter: | pathname: str | The absolute pathname to the Vim buffer. | | inferiortty(self) | Spawn the inferior terminal. | | netbeans_detach(self) | Request vim to close the netbeans session. | | not_a_pyclewn_method(self, cmd) | "Warn that 'cmd' cannot be used as 'C' parameter. | | post_cmd(self, cmd, args) | The method called after each invocation of a 'cmd_' | method. | | This method must be implemented in a subclass. | | Method parameters: | cmd: str | The command name. | args: str | The arguments of the command. | | pre_cmd(self, cmd, args) | The method called before each invocation of a 'cmd_' | method. | | This method must be implemented in a subclass. | | Method parameters: | cmd: str | The command name. | args: str | The arguments of the command. | | print_prompt(self) | Print the prompt in the Vim debugger console. | | remove_all(self) | Remove all annotations. | | Vim signs are unplaced. | Annotations are not deleted. | | set_nbsock(self, nbsock) | Set the netbeans socket. | | set_nbsock_owner(self, thread_ident, socket_map=None) | Add nbsock to 'socket_map' and make 'thread_ident' nbsock owner. | | show_balloon(self, text) | Show 'text' in the Vim balloon. | | Method parameter: | text: str | The text to show in the balloon. | | show_frame(self, pathname=None, lnum=1) | Show the frame highlighted sign in a Vim buffer. | | The frame sign is unique. | Remove the frame sign when 'pathname' is None. | | Method parameters: | pathname: str | The absolute pathname to the Vim buffer. | lnum: int | The line number in the Vim buffer. | | start(self) | This method must be implemented in a subclass. | | timer(self, callme, delta) | Schedule the 'callme' job at 'delta' time from now. | | The timer granularity is LOOP_TIMEOUT, so it does not make sense | to request a 'delta' time less than LOOP_TIMEOUT. | | Method parameters: | callme: callable | the job being scheduled | delta: float | time interval | | update_bp(self, bp_id, disabled=False) | Update the enable/disable state of a breakpoint. | | The breakpoint must have been already set in a Vim buffer with | 'add_bp'. | Return True when successful. | | Method parameters: | bp_id: object | The debugger breakpoint id. | disabled: bool | When True, set the breakpoint as disabled. | | update_dbgvarbuf(self, getdata, dirty, lnum=None) | Update the variables buffer in Vim. | | Update the variables buffer in Vim when one the following | conditions is | True: | * 'dirty' is True | * the content of the Vim variables buffer and the content of | pyclewn 'dbgvarbuf' are not consistent after an error in the | netbeans protocol occured | Set the Vim cursor at 'lnum' after the buffer has been updated. | | Method parameters: | getdata: callable | A callable that returns the content of the variables | buffer as a string. | dirty: bool | When True, force updating the buffer. | lnum: int | The line number in the Vim buffer. | | vim_script_custom(self, prefix) | Return debugger specific Vim statements as a string. | | A Vim script is run on Vim start-up, for example to define all | the debugger commands in Vim. This method may be overriden to | add some debugger specific Vim statements or functions to this | script. | | Method parameter: | prefix: str | The prefix used for the debugger commands in Vim. | FUNCTIONS restart_timer(timeout) Decorator to re-schedule the method at 'timeout', after it has run. ============================================================================== vim:tw=78:ts=8:ft=help:norl:et: