vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

debug.txt (6909B)


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