annotate runtime/doc/debug.txt @ 19574:d4deb2e50667

Update runtime files Commit: https://github.com/vim/vim/commit/eab6dff19f387469a200011bc6cf3508f5e43a4a Author: Bram Moolenaar <Bram@vim.org> Date: Sun Mar 1 19:06:45 2020 +0100 Update runtime files
author Bram Moolenaar <Bram@vim.org>
date Sun, 01 Mar 2020 19:15:04 +0100
parents af69c9335223
children f8116058ca76
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
18879
af69c9335223 Vim 8.2 release
Bram Moolenaar <Bram@vim.org>
parents: 16610
diff changeset
1 *debug.txt* For Vim version 8.2. Last change: 2019 May 07
502
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
2
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
3
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
4 VIM REFERENCE MANUAL by Bram Moolenaar
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
5
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
6
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
7 Debugging Vim *debug-vim*
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
8
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
9 This is for debugging Vim itself, when it doesn't work properly.
606
aa08661abaf7 updated for version 7.0172
vimboss
parents: 502
diff changeset
10 For debugging Vim scripts, functions, etc. see |debug-scripts|
502
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
11
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
12 1. Location of a crash, using gcc and gdb |debug-gcc|
2033
de5a43c5eedc Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents: 1702
diff changeset
13 2. Locating memory leaks |debug-leaks|
de5a43c5eedc Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents: 1702
diff changeset
14 3. Windows Bug Reporting |debug-win32|
502
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
15
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
16 ==============================================================================
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
17
3356
b37888de599c Update runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2681
diff changeset
18 1. Location of a crash, using gcc and gdb *debug-gcc* *gdb*
502
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
19
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
20 When Vim crashes in one of the test files, and you are using gcc for
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
21 compilation, here is what you can do to find out exactly where Vim crashes.
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
22 This also applies when using the MingW tools.
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
23
2681
85c5a72551e2 Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2581
diff changeset
24 1. Compile Vim with the "-g" option (there is a line in the src/Makefile for
85c5a72551e2 Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2581
diff changeset
25 this, which you can uncomment). Also make sure "strip" is disabled (do not
2581
e8a482a7fa6c Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2577
diff changeset
26 install it, or use the line "STRIP = /bin/true").
502
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
27
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
28 2. Execute these commands (replace "11" with the test that fails): >
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
29 cd testdir
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
30 gdb ../vim
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
31 run -u unix.vim -U NONE -s dotest.in test11.in
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
32
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
33 3. Check where Vim crashes, gdb should give a message for this.
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
34
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
35 4. Get a stack trace from gdb with this command: >
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
36 where
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
37 < You can check out different places in the stack trace with: >
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
38 frame 3
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
39 < Replace "3" with one of the numbers in the stack trace.
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
40
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
41 ==============================================================================
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
42
2309
543ea69d037f Add clipboard support in Mac console. (Bjorn Winckler)
Bram Moolenaar <bram@vim.org>
parents: 2154
diff changeset
43 2. Locating memory leaks *debug-leaks* *valgrind*
2033
de5a43c5eedc Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents: 1702
diff changeset
44
de5a43c5eedc Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents: 1702
diff changeset
45 If you suspect Vim is leaking memory and you are using Linux, the valgrind
de5a43c5eedc Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents: 1702
diff changeset
46 tool is very useful to pinpoint memory leaks.
de5a43c5eedc Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents: 1702
diff changeset
47
de5a43c5eedc Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents: 1702
diff changeset
48 First of all, build Vim with EXITFREE defined. Search for this in MAKEFILE
de5a43c5eedc Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents: 1702
diff changeset
49 and uncomment the line.
de5a43c5eedc Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents: 1702
diff changeset
50
2309
543ea69d037f Add clipboard support in Mac console. (Bjorn Winckler)
Bram Moolenaar <bram@vim.org>
parents: 2154
diff changeset
51 Use this command to start Vim:
2033
de5a43c5eedc Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents: 1702
diff changeset
52 >
2309
543ea69d037f Add clipboard support in Mac console. (Bjorn Winckler)
Bram Moolenaar <bram@vim.org>
parents: 2154
diff changeset
53 valgrind --log-file=valgrind.log --leak-check=full ./vim
2033
de5a43c5eedc Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents: 1702
diff changeset
54
de5a43c5eedc Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents: 1702
diff changeset
55 Note: Vim will run much slower. If your .vimrc is big or you have several
11666
5cd9ba96561d patch 8.0.0716: not easy to start Vim cleanly
Christian Brabandt <cb@256bit.org>
parents: 10198
diff changeset
56 plugins you need to be patient for startup, or run with the "--clean"
2033
de5a43c5eedc Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents: 1702
diff changeset
57 argument.
de5a43c5eedc Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents: 1702
diff changeset
58
2309
543ea69d037f Add clipboard support in Mac console. (Bjorn Winckler)
Bram Moolenaar <bram@vim.org>
parents: 2154
diff changeset
59 There are often a few leaks from libraries, such as getpwuid() and
543ea69d037f Add clipboard support in Mac console. (Bjorn Winckler)
Bram Moolenaar <bram@vim.org>
parents: 2154
diff changeset
60 XtVaAppCreateShell(). Those are unavoidable. The number of bytes should be
543ea69d037f Add clipboard support in Mac console. (Bjorn Winckler)
Bram Moolenaar <bram@vim.org>
parents: 2154
diff changeset
61 very small a Kbyte or less.
543ea69d037f Add clipboard support in Mac console. (Bjorn Winckler)
Bram Moolenaar <bram@vim.org>
parents: 2154
diff changeset
62
2033
de5a43c5eedc Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents: 1702
diff changeset
63 ==============================================================================
de5a43c5eedc Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents: 1702
diff changeset
64
de5a43c5eedc Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents: 1702
diff changeset
65 3. Windows Bug Reporting *debug-win32*
502
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
66
842
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
67 If the Windows version of Vim crashes in a reproducible manner, you can take
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
68 some steps to provide a useful bug report.
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
69
502
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
70
2581
e8a482a7fa6c Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2577
diff changeset
71 3.1 GENERIC ~
842
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
72
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
73 You must obtain the debugger symbols (PDB) file for your executable: gvim.pdb
857
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
74 for gvim.exe, or vim.pdb for vim.exe. The PDB should be available from the
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
75 same place that you obtained the executable. Be sure to use the PDB that
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
76 matches the EXE (same date).
502
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
77
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
78 If you built the executable yourself with the Microsoft Visual C++ compiler,
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
79 then the PDB was built with the EXE.
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
80
842
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
81 If you have Visual Studio, use that instead of the VC Toolkit and WinDbg.
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
82
16606
7e733046db1d patch 8.1.1306: Borland support is outdated and doesn't work
Bram Moolenaar <Bram@vim.org>
parents: 16580
diff changeset
83 For other compilers, you should always use the corresponding debugger: gdb
7e733046db1d patch 8.1.1306: Borland support is outdated and doesn't work
Bram Moolenaar <Bram@vim.org>
parents: 16580
diff changeset
84 (see above |debug-gcc|) for the Cygwin and MinGW compilers.
842
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
85
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
86
857
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
87 *debug-vs2005*
2581
e8a482a7fa6c Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2577
diff changeset
88 3.2 Debugging Vim crashes with Visual Studio 2005/Visual C++ 2005 Express ~
842
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
89
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
90 First launch vim.exe or gvim.exe and then launch Visual Studio. (If you don't
857
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
91 have Visual Studio, follow the instructions at |get-ms-debuggers| to obtain a
842
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
92 free copy of Visual C++ 2005 Express Edition.)
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
93
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
94 On the Tools menu, click Attach to Process. Choose the Vim process.
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
95
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
96 In Vim, reproduce the crash. A dialog will appear in Visual Studio, telling
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
97 you about the unhandled exception in the Vim process. Click Break to break
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
98 into the process.
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
99
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
100 Visual Studio will pop up another dialog, telling you that no symbols are
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
101 loaded and that the source code cannot be displayed. Click OK.
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
102
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
103 Several windows will open. Right-click in the Call Stack window. Choose Load
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
104 Symbols. The Find Symbols dialog will open, looking for (g)vim.pdb. Navigate
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
105 to the directory where you have the PDB file and click Open.
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
106
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
107 At this point, you should have a full call stack with vim function names and
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
108 line numbers. Double-click one of the lines and the Find Source dialog will
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
109 appear. Navigate to the directory where the Vim source is (if you have it.)
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
110
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
111 If you don't know how to debug this any further, follow the instructions
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
112 at ":help bug-reports". Paste the call stack into the bug report.
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
113
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
114 If you have a non-free version of Visual Studio, you can save a minidump via
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
115 the Debug menu and send it with the bug report. A minidump is a small file
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
116 (<100KB), which contains information about the state of your process.
857
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
117 Visual C++ 2005 Express Edition cannot save minidumps and it cannot be
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
118 installed as a just-in-time debugger. Use WinDbg, |debug-windbg|, if you
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
119 need to save minidumps or you want a just-in-time (postmortem) debugger.
842
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
120
857
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
121 *debug-windbg*
2581
e8a482a7fa6c Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2577
diff changeset
122 3.3 Debugging Vim crashes with WinDbg ~
857
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
123
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
124 See |get-ms-debuggers| to obtain a copy of WinDbg.
842
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
125
857
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
126 As with the Visual Studio IDE, you can attach WinDbg to a running Vim process.
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
127 You can also have your system automatically invoke WinDbg as a postmortem
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
128 debugger. To set WinDbg as your postmortem debugger, run "windbg -I".
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
129
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
130 To attach WinDbg to a running Vim process, launch WinDbg. On the File menu,
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
131 choose Attach to a Process. Select the Vim process and click OK.
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
132
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
133 At this point, choose Symbol File Path on the File menu, and add the folder
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
134 containing your Vim PDB to the sympath. If you have Vim source available,
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
135 use Source File Path on the File menu. You can now open source files in WinDbg
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
136 and set breakpoints, if you like. Reproduce your crash. WinDbg should open the
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
137 source file at the point of the crash. Using the View menu, you can examine
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
138 the call stack, local variables, watch windows, and so on.
842
a209672376fd updated for version 7.0f
vimboss
parents: 834
diff changeset
139
857
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
140 If WinDbg is your postmortem debugger, you do not need to attach WinDbg to
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
141 your Vim process. Simply reproduce the crash and WinDbg will launch
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
142 automatically. As above, set the Symbol File Path and the Source File Path.
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
143
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
144 To save a minidump, type the following at the WinDbg command line: >
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
145 .dump vim.dmp
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
146 <
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
147 *debug-minidump*
2581
e8a482a7fa6c Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2577
diff changeset
148 3.4 Opening a Minidump ~
857
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
149
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
150 If you have a minidump file, you can open it in Visual Studio or in WinDbg.
502
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
151
857
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
152 In Visual Studio 2005: on the File menu, choose Open, then Project/Solution.
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
153 Navigate to the .dmp file and open it. Now press F5 to invoke the debugger.
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
154 Follow the instructions in |debug-vs2005| to set the Symbol File Path.
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
155
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
156 In WinDbg: choose Open Crash Dump on the File menu. Follow the instructions in
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
157 |debug-windbg| to set the Symbol File Path.
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
158
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
159 *get-ms-debuggers*
2581
e8a482a7fa6c Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2577
diff changeset
160 3.5 Obtaining Microsoft Debugging Tools ~
857
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
161
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
162 The Debugging Tools for Windows (including WinDbg) can be downloaded from
502
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
163 http://www.microsoft.com/whdc/devtools/debugging/default.mspx
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
164 This includes the WinDbg debugger.
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
165
857
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
166 Visual C++ 2005 Express Edition can be downloaded for free from:
b933657f7c9d updated for version 7.0g01
vimboss
parents: 856
diff changeset
167 http://msdn.microsoft.com/vstudio/express/visualC/default.aspx
502
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
168
52e76e2b5b65 updated for version 7.0140
vimboss
parents:
diff changeset
169 =========================================================================
14421
2f7e67dd088c Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
170 vim:tw=78:ts=8:noet:ft=help:norl: