runtime/doc/debug.txt

   1 *debug.txt*     For Vim version 7.2.  Last change: 2006 May 01
   2
   3
   4                   VIM REFERENCE MANUAL    by Bram Moolenaar
   5
   6
   7 Debugging Vim                                           *debug-vim*
   8
   9 This is for debugging Vim itself, when it doesn't work properly.
  10 For debugging Vim scripts, functions, etc. see |debug-scripts|
  11
  12 1. Location of a crash, using gcc and gdb       |debug-gcc|
  13 2. Windows Bug Reporting                        |debug-win32|
  14
  15 ==============================================================================
  16
  17 1. Location of a crash, using gcc and gdb               *debug-gcc*
  18
  19 When Vim crashes in one of the test files, and you are using gcc for
  20 compilation, here is what you can do to find out exactly where Vim crashes.
  21 This also applies when using the MingW tools.
  22
  23 1. Compile Vim with the "-g" option (there is a line in the Makefile for this,
  24    which you can uncomment).
  25
  26 2. Execute these commands (replace "11" with the test that fails): >
  27         cd testdir
  28         gdb ../vim
  29         run -u unix.vim -U NONE -s dotest.in test11.in
  30
  31 3. Check where Vim crashes, gdb should give a message for this.
  32
  33 4. Get a stack trace from gdb with this command: >
  34         where
  35 <  You can check out different places in the stack trace with: >
  36         frame 3
  37 <  Replace "3" with one of the numbers in the stack trace.
  38
  39 ==============================================================================
  40
  41 2. Windows Bug Reporting                                *debug-win32*
  42
  43 If the Windows version of Vim crashes in a reproducible manner, you can take
  44 some steps to provide a useful bug report.
  45
  46
  47 GENERIC ~
  48
  49 You must obtain the debugger symbols (PDB) file for your executable: gvim.pdb
  50 for gvim.exe, or vim.pdb for vim.exe. The PDB should be available from the
  51 same place that you obtained the executable. Be sure to use the PDB that
  52 matches the EXE (same date).
  53
  54 If you built the executable yourself with the Microsoft Visual C++ compiler,
  55 then the PDB was built with the EXE.
  56
  57 Alternatively, if you have the source files, you can import Make_ivc.mak into
  58 Visual Studio as a workspace.  Then select a debug configuration, build and
  59 you can do all kinds of debugging (set breakpoints, watch variables, etc.).
  60
  61 If you have Visual Studio, use that instead of the VC Toolkit and WinDbg.
  62
  63 For other compilers, you should always use the corresponding debugger: TD for
  64 a Vim executable compiled with the Borland compiler; gdb (see above
  65 |debug-gcc|) for the Cygwin and MinGW compilers.
  66
  67
  68                                                                 *debug-vs2005*
  69 2.2 Debugging Vim crashes with Visual Studio 2005/Visual C++ 2005 Express ~
  70
  71 First launch vim.exe or gvim.exe and then launch Visual Studio.  (If you don't
  72 have Visual Studio, follow the instructions at |get-ms-debuggers| to obtain a
  73 free copy of Visual C++ 2005 Express Edition.)
  74
  75 On the Tools menu, click Attach to Process.  Choose the Vim process.
  76
  77 In Vim, reproduce the crash.  A dialog will appear in Visual Studio, telling
  78 you about the unhandled exception in the Vim process.  Click Break to break
  79 into the process.
  80
  81 Visual Studio will pop up another dialog, telling you that no symbols are
  82 loaded and that the source code cannot be displayed.  Click OK.
  83
  84 Several windows will open.  Right-click in the Call Stack window.  Choose Load
  85 Symbols.  The Find Symbols dialog will open, looking for (g)vim.pdb.  Navigate
  86 to the directory where you have the PDB file and click Open.
  87
  88 At this point, you should have a full call stack with vim function names and
  89 line numbers.  Double-click one of the lines and the Find Source dialog will
  90 appear.  Navigate to the directory where the Vim source is (if you have it.)
  91
  92 If you don't know how to debug this any further, follow the instructions
  93 at ":help bug-reports".  Paste the call stack into the bug report.
  94
  95 If you have a non-free version of Visual Studio, you can save a minidump via
  96 the Debug menu and send it with the bug report.  A minidump is a small file
  97 (<100KB), which contains information about the state of your process.
  98 Visual C++ 2005 Express Edition cannot save minidumps and it cannot be
  99 installed as a just-in-time debugger. Use WinDbg, |debug-windbg|, if you
 100 need to save minidumps or you want a just-in-time (postmortem) debugger.
 101
 102                                                                 *debug-windbg*
 103 2.3 Debugging Vim crashes with WinDbg ~
 104
 105 See |get-ms-debuggers| to obtain a copy of WinDbg.
 106
 107 As with the Visual Studio IDE, you can attach WinDbg to a running Vim process.
 108 You can also have your system automatically invoke WinDbg as a postmortem
 109 debugger. To set WinDbg as your postmortem debugger, run "windbg -I".
 110
 111 To attach WinDbg to a running Vim process, launch WinDbg. On the File menu,
 112 choose Attach to a Process. Select the Vim process and click OK.
 113
 114 At this point, choose Symbol File Path on the File menu, and add the folder
 115 containing your Vim PDB to the sympath. If you have Vim source available,
 116 use Source File Path on the File menu. You can now open source files in WinDbg
 117 and set breakpoints, if you like. Reproduce your crash. WinDbg should open the
 118 source file at the point of the crash. Using the View menu, you can examine
 119 the call stack, local variables, watch windows, and so on.
 120
 121 If WinDbg is your postmortem debugger, you do not need to attach WinDbg to
 122 your Vim process. Simply reproduce the crash and WinDbg will launch
 123 automatically. As above, set the Symbol File Path and the Source File Path.
 124
 125 To save a minidump, type the following at the WinDbg command line: >
 126         .dump vim.dmp
 127 <
 128                                                         *debug-minidump*
 129 2.4 Opening a Minidump ~
 130
 131 If you have a minidump file, you can open it in Visual Studio or in WinDbg.
 132
 133 In Visual Studio 2005: on the File menu, choose Open, then Project/Solution.
 134 Navigate to the .dmp file and open it. Now press F5 to invoke the debugger.
 135 Follow the instructions in |debug-vs2005| to set the Symbol File Path.
 136
 137 In WinDbg: choose Open Crash Dump on the File menu. Follow the instructions in
 138 |debug-windbg| to set the Symbol File Path.
 139
 140                                                         *get-ms-debuggers*
 141 2.5 Obtaining Microsoft Debugging Tools ~
 142
 143 The Debugging Tools for Windows (including WinDbg) can be downloaded from
 144     http://www.microsoft.com/whdc/devtools/debugging/default.mspx
 145 This includes the WinDbg debugger.
 146
 147 Visual C++ 2005 Express Edition can be downloaded for free from:
 148     http://msdn.microsoft.com/vstudio/express/visualC/default.aspx
 149
 150 =========================================================================
 151  vim:tw=78:ts=8:ft=help:norl: