runtime/doc/debugger.txt

   1 *debugger.txt*  For Vim version 7.2.  Last change: 2005 Mar 29
   2
   3
   4                   VIM REFERENCE MANUAL    by Gordon Prieur
   5
   6
   7 Debugger Support Features                               *debugger-support*
   8
   9 1. Debugger Features            |debugger-features|
  10 2. Vim Compile Options          |debugger-compilation|
  11 3. Integrated Debuggers         |debugger-integration|
  12
  13 {Vi does not have any of these features}
  14
  15 ==============================================================================
  16 1. Debugger Features                                    *debugger-features*
  17
  18 The following features are available for an integration with a debugger or
  19 an Integrated Programming Environment (IPE) or Integrated Development
  20 Environment (IDE):
  21
  22         Alternate Command Input                         |alt-input|
  23         Debug Signs                                     |debug-signs|
  24         Debug Source Highlight                          |debug-highlight|
  25         Message Footer                                  |gui-footer|
  26         Balloon Evaluation                              |balloon-eval|
  27
  28 These features were added specifically for use in the Motif version of gvim.
  29 However, the |alt-input| and |debug-highlight| were written to be usable in
  30 both vim and gvim.  Some of the other features could be used in the non-GUI
  31 vim with slight modifications.  However, I did not do this nor did I test the
  32 reliability of building for vim or non Motif GUI versions.
  33
  34
  35 1.1 Alternate Command Input                             *alt-input*
  36
  37 For Vim to work with a debugger there must be at least an input connection
  38 with a debugger or external tool.  In many cases there will also be an output
  39 connection but this isn't absolutely necessary.
  40
  41 The purpose of the input connection is to let the external debugger send
  42 commands to Vim.  The commands sent by the debugger should give the debugger
  43 enough control to display the current debug environment and state.
  44
  45 The current implementation is based on the X Toolkit dispatch loop and the
  46 XtAddInput() function call.
  47
  48
  49 1.2 Debug Signs                                         *debug-signs*
  50
  51 Many debuggers mark specific lines by placing a small sign or color highlight
  52 on the line.  The |:sign| command lets the debugger set this graphic mark.  Some
  53 examples where this feature would be used would be a debugger showing an arrow
  54 representing the Program Counter (PC) of the program being debugged.  Another
  55 example would be a small stop sign for a line with a breakpoint.  These visible
  56 highlights let the user keep track of certain parts of the state of the
  57 debugger.
  58
  59 This feature can be used with more than debuggers, too.  An IPE can use a sign
  60 to highlight build errors, searched text, or other things.  The sign feature
  61 can also work together with the |debug-highlight| to ensure the mark is
  62 highly visible.
  63
  64 Debug signs are defined and placed using the |:sign| command.
  65
  66
  67 1.3 Debug Source Highlight                              *debug-highlight*
  68
  69 This feature allows a line to have a predominant highlight.  The highlight is
  70 intended to make a specific line stand out.  The highlight could be made to
  71 work for both vim and gvim, whereas the debug sign is, in most cases, limited
  72 to gvim.  The one exception to this is Sun Microsystem's dtterm.  The dtterm
  73 from Sun has a "sign gutter" for showing signs.
  74
  75
  76 1.4 Message Footer                                      *gui-footer*
  77
  78 The message footer can be used to display messages from a debugger or IPE.  It
  79 can also be used to display menu and toolbar tips.  The footer area is at the
  80 bottom of the GUI window, below the line used to display colon commands.
  81
  82 The display of the footer is controlled by the 'guioptions' letter 'F'.
  83
  84
  85 1.5 Balloon Evaluation                                  *balloon-eval*
  86
  87 This feature allows a debugger, or other external tool, to display dynamic
  88 information based on where the mouse is pointing.  The purpose of this feature
  89 was to allow Sun's Visual WorkShop debugger to display expression evaluations.
  90 However, the feature was implemented in as general a manner as possible and
  91 could be used for displaying other information as well.
  92
  93 The Balloon Evaluation has some settable parameters too.  For Motif the font
  94 list and colors can be set via X resources (XmNballoonEvalFontList,
  95 XmNballoonEvalBackground, and XmNballoonEvalForeground).
  96 The 'balloondelay' option sets the delay before an attempt is made to show a
  97 balloon.
  98 The 'ballooneval' option needs to be set to switch it on.
  99
 100 Balloon evaluation is only available when compiled with the |+balloon_eval|
 101 feature.
 102
 103 The Balloon evaluation functions are also used to show a tooltip for the
 104 toolbar.  The 'ballooneval' option does not need to be set for this.  But the
 105 other settings apply.
 106
 107 Another way to use the balloon is with the 'balloonexpr' option.  This is
 108 completely user definable.
 109
 110 ==============================================================================
 111 2. Vim Compile Options                                  *debugger-compilation*
 112
 113 The debugger features were added explicitly for use with Sun's Visual
 114 WorkShop Integrated Programming Environment (ipe).  However, they were done
 115 in as generic a manner as possible so that integration with other debuggers
 116 could also use some or all of the tools used with Sun's ipe.
 117
 118 The following compile time preprocessor variables control the features:
 119
 120     Alternate Command Input                     ALT_X_INPUT
 121     Debug Glyphs                                FEAT_SIGNS
 122     Debug Highlights                            FEAT_SIGNS
 123     Message Footer                              FEAT_FOOTER
 124     Balloon Evaluation                          FEAT_BEVAL
 125
 126 The first integration with a full IPE/IDE was with Sun Visual WorkShop.  To
 127 compile a gvim which interfaces with VWS set the following flag, which sets
 128 all the above flags:
 129
 130     Sun Visual WorkShop                         FEAT_SUN_WORKSHOP
 131
 132 ==============================================================================
 133 3. Integrated Debuggers                                 *debugger-integration*
 134
 135 One fully integrated debugger/IPE/IDE is Sun's Visual WorkShop Integrated
 136 Programming Environment.
 137
 138 For Sun NetBeans support see |netbeans|.
 139
 140  vim:tw=78:sw=4:ts=8:ft=help:norl: