codekingpro/portable-devtools

1*debug.txt*	For Vim version 9.2.  Last change: 2026 Feb 142 3 4		  VIM REFERENCE MANUAL	  by Bram Moolenaar5 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* *gdb*19 20When Vim crashes in one of the test files, and you are using gcc for21compilation, 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 src/Makefile for25   this, which you can uncomment).  Also make sure "strip" is disabled (do not26   install it, or use the line "STRIP = /bin/true").27 282. Execute these commands (replace "11" with the test that fails): >29	cd testdir30	gdb ../vim31	run -u unix.vim -U NONE -s dotest.in test11.in32 333. Check where Vim crashes, gdb should give a message for this.34 354. Get a stack trace from gdb with this command: >36	where37<  You can check out different places in the stack trace with: >38	frame 339<  Replace "3" with one of the numbers in the stack trace.40 41==============================================================================42 432. Locating memory leaks			*debug-leaks* *valgrind*44 45If you suspect Vim is leaking memory and you are using Linux, the valgrind46tool is very useful to pinpoint memory leaks.47 48First of all, build Vim with EXITFREE defined.  Search for this in MAKEFILE49and uncomment the line.50 51Use this command to start Vim:52>53	valgrind --log-file=valgrind.log --leak-check=full ./vim54 55Note: Vim will run much slower.  If your .vimrc is big or you have several56plugins you need to be patient for startup, or run with the "--clean"57argument.58 59There are often a few leaks from libraries, such as getpwuid() and60XtVaAppCreateShell().  Those are unavoidable.  The number of bytes should be61very small a Kbyte or less.62 63==============================================================================64 653. Windows Bug Reporting				*debug-win32*66 67If the Windows version of Vim crashes in a reproducible manner, you can take68some steps to provide a useful bug report.69 70 713.1 GENERIC ~72 73You must obtain the debugger symbols (PDB) file for your executable: gvim.pdb74for gvim.exe, or vim.pdb for vim.exe.  The PDB should be available from the75same place that you obtained the executable.  Be sure to use the PDB that76matches the EXE (same date).77 78If you built the executable yourself with the Microsoft Visual C++ compiler,79then the PDB was built with the EXE.80 81If you have Visual Studio, use that instead of the VC Toolkit and WinDbg.82 83For other compilers, you should always use the corresponding debugger: gdb84(see above |debug-gcc|) for the Cygwin and MinGW compilers.85 86 87								*debug-vs2005*883.2 Debugging Vim crashes with Visual Studio 2005/Visual C++ 2005 Express ~89 90First launch vim.exe or gvim.exe and then launch Visual Studio.  (If you don't91have Visual Studio, follow the instructions at |get-ms-debuggers| to obtain a92free copy of Visual C++ 2005 Express Edition.)93 94On the Tools menu, click Attach to Process.  Choose the Vim process.95 96In Vim, reproduce the crash.  A dialog will appear in Visual Studio, telling97you about the unhandled exception in the Vim process.  Click Break to break98into the process.99 100Visual Studio will pop up another dialog, telling you that no symbols are101loaded and that the source code cannot be displayed.  Click OK.102 103Several windows will open.  Right-click in the Call Stack window.  Choose Load104Symbols.  The Find Symbols dialog will open, looking for (g)vim.pdb.  Navigate105to the directory where you have the PDB file and click Open.106 107At this point, you should have a full call stack with vim function names and108line numbers.  Double-click one of the lines and the Find Source dialog will109appear.  Navigate to the directory where the Vim source is (if you have it.)110 111If you don't know how to debug this any further, follow the instructions112at ":help bug-reports".  Paste the call stack into the bug report.113 114If you have a non-free version of Visual Studio, you can save a minidump via115the Debug menu and send it with the bug report.  A minidump is a small file116(<100KB), which contains information about the state of your process.117Visual C++ 2005 Express Edition cannot save minidumps and it cannot be118installed as a just-in-time debugger.  Use WinDbg, |debug-windbg|, if you119need to save minidumps or you want a just-in-time (postmortem) debugger.120 121								*debug-windbg*1223.3 Debugging Vim crashes with WinDbg ~123 124See |get-ms-debuggers| to obtain a copy of WinDbg.125 126As with the Visual Studio IDE, you can attach WinDbg to a running Vim process.127You can also have your system automatically invoke WinDbg as a postmortem128debugger.  To set WinDbg as your postmortem debugger, run "windbg -I".129 130To attach WinDbg to a running Vim process, launch WinDbg.  On the File menu,131choose Attach to a Process.  Select the Vim process and click OK.132 133At this point, choose Symbol File Path on the File menu, and add the folder134containing your Vim PDB to the sympath.  If you have Vim source available,135use Source File Path on the File menu.  You can now open source files in136WinDbg and set breakpoints, if you like.  Reproduce your crash.  WinDbg should137open the source file at the point of the crash.  Using the View menu, you can138examine the call stack, local variables, watch windows, and so on.139 140If WinDbg is your postmortem debugger, you do not need to attach WinDbg to141your Vim process.  Simply reproduce the crash and WinDbg will launch142automatically.  As above, set the Symbol File Path and the Source File Path.143 144To save a minidump, type the following at the WinDbg command line: >145        .dump vim.dmp146<147							*debug-minidump*1483.4 Opening a Minidump ~149 150If you have a minidump file, you can open it in Visual Studio or in WinDbg.151 152In Visual Studio 2005: on the File menu, choose Open, then Project/Solution.153Navigate to the .dmp file and open it.  Now press F5 to invoke the debugger.154Follow the instructions in |debug-vs2005| to set the Symbol File Path.155 156In WinDbg: choose Open Crash Dump on the File menu.  Follow the instructions157in |debug-windbg| to set the Symbol File Path.158 159							*get-ms-debuggers*1603.5 Obtaining Microsoft Debugging Tools ~161 162The Debugging Tools for Windows (including WinDbg) can be downloaded from163    https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/debugger-download-tools164This includes the WinDbg debugger.165 166Visual C++ 2005 Express Edition can be downloaded for free from:167    https://visualstudio.microsoft.com/168 169=========================================================================170 vim:tw=78:ts=8:noet:ft=help:norl:171