blob: 37a5772f42d5bcb4534e8a506549d76ab07eb999 [file] [log] [blame]
Bram Moolenaarb1c91982018-05-17 17:04:55 +02001*debug.txt* For Vim version 8.1. Last change: 2017 Jul 15
Bram Moolenaare344bea2005-09-01 20:46:49 +00002
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.
Bram Moolenaaracf53452005-12-17 22:06:52 +000010For debugging Vim scripts, functions, etc. see |debug-scripts|
Bram Moolenaare344bea2005-09-01 20:46:49 +000011
121. Location of a crash, using gcc and gdb |debug-gcc|
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100132. Locating memory leaks |debug-leaks|
143. Windows Bug Reporting |debug-win32|
Bram Moolenaare344bea2005-09-01 20:46:49 +000015
16==============================================================================
17
Bram Moolenaar5dc62522012-02-13 00:05:22 +0100181. Location of a crash, using gcc and gdb *debug-gcc* *gdb*
Bram Moolenaare344bea2005-09-01 20:46:49 +000019
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
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +0100241. 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
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +020026 install it, or use the line "STRIP = /bin/true").
Bram Moolenaare344bea2005-09-01 20:46:49 +000027
282. 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
333. Check where Vim crashes, gdb should give a message for this.
34
354. 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
Bram Moolenaar164fca32010-07-14 13:58:07 +0200432. Locating memory leaks *debug-leaks* *valgrind*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010044
45If you suspect Vim is leaking memory and you are using Linux, the valgrind
46tool is very useful to pinpoint memory leaks.
47
48First of all, build Vim with EXITFREE defined. Search for this in MAKEFILE
49and uncomment the line.
50
Bram Moolenaar164fca32010-07-14 13:58:07 +020051Use this command to start Vim:
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010052>
Bram Moolenaar164fca32010-07-14 13:58:07 +020053 valgrind --log-file=valgrind.log --leak-check=full ./vim
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010054
55Note: Vim will run much slower. If your .vimrc is big or you have several
Bram Moolenaarc4da1132017-07-15 19:39:43 +020056plugins you need to be patient for startup, or run with the "--clean"
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010057argument.
58
Bram Moolenaar164fca32010-07-14 13:58:07 +020059There are often a few leaks from libraries, such as getpwuid() and
60XtVaAppCreateShell(). Those are unavoidable. The number of bytes should be
61very small a Kbyte or less.
62
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010063==============================================================================
64
653. Windows Bug Reporting *debug-win32*
Bram Moolenaare344bea2005-09-01 20:46:49 +000066
Bram Moolenaarf9393ef2006-04-24 19:47:27 +000067If the Windows version of Vim crashes in a reproducible manner, you can take
68some steps to provide a useful bug report.
Bram Moolenaare344bea2005-09-01 20:46:49 +000069
Bram Moolenaarf9393ef2006-04-24 19:47:27 +000070
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +0200713.1 GENERIC ~
Bram Moolenaarf9393ef2006-04-24 19:47:27 +000072
73You must obtain the debugger symbols (PDB) file for your executable: gvim.pdb
Bram Moolenaard68071d2006-05-02 22:08:30 +000074for gvim.exe, or vim.pdb for vim.exe. The PDB should be available from the
75same place that you obtained the executable. Be sure to use the PDB that
76matches the EXE (same date).
Bram Moolenaare344bea2005-09-01 20:46:49 +000077
78If you built the executable yourself with the Microsoft Visual C++ compiler,
79then the PDB was built with the EXE.
80
Bram Moolenaarf9393ef2006-04-24 19:47:27 +000081If you have Visual Studio, use that instead of the VC Toolkit and WinDbg.
82
83For other compilers, you should always use the corresponding debugger: TD for
84a Vim executable compiled with the Borland compiler; gdb (see above
85|debug-gcc|) for the Cygwin and MinGW compilers.
86
87
Bram Moolenaard68071d2006-05-02 22:08:30 +000088 *debug-vs2005*
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +0200893.2 Debugging Vim crashes with Visual Studio 2005/Visual C++ 2005 Express ~
Bram Moolenaarf9393ef2006-04-24 19:47:27 +000090
91First launch vim.exe or gvim.exe and then launch Visual Studio. (If you don't
Bram Moolenaard68071d2006-05-02 22:08:30 +000092have Visual Studio, follow the instructions at |get-ms-debuggers| to obtain a
Bram Moolenaarf9393ef2006-04-24 19:47:27 +000093free copy of Visual C++ 2005 Express Edition.)
94
95On the Tools menu, click Attach to Process. Choose the Vim process.
96
97In Vim, reproduce the crash. A dialog will appear in Visual Studio, telling
98you about the unhandled exception in the Vim process. Click Break to break
99into the process.
100
101Visual Studio will pop up another dialog, telling you that no symbols are
102loaded and that the source code cannot be displayed. Click OK.
103
104Several windows will open. Right-click in the Call Stack window. Choose Load
105Symbols. The Find Symbols dialog will open, looking for (g)vim.pdb. Navigate
106to the directory where you have the PDB file and click Open.
107
108At this point, you should have a full call stack with vim function names and
109line numbers. Double-click one of the lines and the Find Source dialog will
110appear. Navigate to the directory where the Vim source is (if you have it.)
111
112If you don't know how to debug this any further, follow the instructions
113at ":help bug-reports". Paste the call stack into the bug report.
114
115If you have a non-free version of Visual Studio, you can save a minidump via
116the Debug menu and send it with the bug report. A minidump is a small file
117(<100KB), which contains information about the state of your process.
Bram Moolenaard68071d2006-05-02 22:08:30 +0000118Visual C++ 2005 Express Edition cannot save minidumps and it cannot be
119installed as a just-in-time debugger. Use WinDbg, |debug-windbg|, if you
120need to save minidumps or you want a just-in-time (postmortem) debugger.
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000121
Bram Moolenaard68071d2006-05-02 22:08:30 +0000122 *debug-windbg*
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +02001233.3 Debugging Vim crashes with WinDbg ~
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000124
Bram Moolenaard68071d2006-05-02 22:08:30 +0000125See |get-ms-debuggers| to obtain a copy of WinDbg.
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000126
Bram Moolenaard68071d2006-05-02 22:08:30 +0000127As with the Visual Studio IDE, you can attach WinDbg to a running Vim process.
128You can also have your system automatically invoke WinDbg as a postmortem
129debugger. To set WinDbg as your postmortem debugger, run "windbg -I".
Bram Moolenaare344bea2005-09-01 20:46:49 +0000130
Bram Moolenaard68071d2006-05-02 22:08:30 +0000131To attach WinDbg to a running Vim process, launch WinDbg. On the File menu,
132choose Attach to a Process. Select the Vim process and click OK.
133
134At this point, choose Symbol File Path on the File menu, and add the folder
135containing your Vim PDB to the sympath. If you have Vim source available,
136use Source File Path on the File menu. You can now open source files in WinDbg
137and set breakpoints, if you like. Reproduce your crash. WinDbg should open the
138source file at the point of the crash. Using the View menu, you can examine
139the call stack, local variables, watch windows, and so on.
140
141If WinDbg is your postmortem debugger, you do not need to attach WinDbg to
142your Vim process. Simply reproduce the crash and WinDbg will launch
143automatically. As above, set the Symbol File Path and the Source File Path.
144
145To save a minidump, type the following at the WinDbg command line: >
146 .dump vim.dmp
147<
148 *debug-minidump*
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +02001493.4 Opening a Minidump ~
Bram Moolenaard68071d2006-05-02 22:08:30 +0000150
151If you have a minidump file, you can open it in Visual Studio or in WinDbg.
152
153In Visual Studio 2005: on the File menu, choose Open, then Project/Solution.
154Navigate to the .dmp file and open it. Now press F5 to invoke the debugger.
155Follow the instructions in |debug-vs2005| to set the Symbol File Path.
156
157In WinDbg: choose Open Crash Dump on the File menu. Follow the instructions in
158|debug-windbg| to set the Symbol File Path.
159
160 *get-ms-debuggers*
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +02001613.5 Obtaining Microsoft Debugging Tools ~
Bram Moolenaard68071d2006-05-02 22:08:30 +0000162
163The Debugging Tools for Windows (including WinDbg) can be downloaded from
Bram Moolenaare344bea2005-09-01 20:46:49 +0000164 http://www.microsoft.com/whdc/devtools/debugging/default.mspx
165This includes the WinDbg debugger.
166
Bram Moolenaard68071d2006-05-02 22:08:30 +0000167Visual C++ 2005 Express Edition can be downloaded for free from:
168 http://msdn.microsoft.com/vstudio/express/visualC/default.aspx
Bram Moolenaare344bea2005-09-01 20:46:49 +0000169
170=========================================================================
Bram Moolenaar91f84f62018-07-29 15:07:52 +0200171 vim:tw=78:ts=8:noet:ft=help:norl: