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