Mercurial > vim
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 |
| rev | line source |
|---|---|
| 18879 | 1 *debug.txt* For Vim version 8.2. Last change: 2019 May 07 |
| 502 | 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. | |
| 606 | 10 For debugging Vim scripts, functions, etc. see |debug-scripts| |
| 502 | 11 |
| 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 | 15 |
| 16 ============================================================================== | |
| 17 | |
| 3356 | 18 1. Location of a crash, using gcc and gdb *debug-gcc* *gdb* |
| 502 | 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 | |
| 2681 | 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 | |
| 2581 | 26 install it, or use the line "STRIP = /bin/true"). |
| 502 | 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 | |
|
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 | 66 |
| 842 | 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 | |
| 502 | 70 |
| 2581 | 71 3.1 GENERIC ~ |
| 842 | 72 |
| 73 You must obtain the debugger symbols (PDB) file for your executable: gvim.pdb | |
| 857 | 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). | |
| 502 | 77 |
| 78 If you built the executable yourself with the Microsoft Visual C++ compiler, | |
| 79 then the PDB was built with the EXE. | |
| 80 | |
| 842 | 81 If you have Visual Studio, use that instead of the VC Toolkit and WinDbg. |
| 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 | 85 |
| 86 | |
| 857 | 87 *debug-vs2005* |
| 2581 | 88 3.2 Debugging Vim crashes with Visual Studio 2005/Visual C++ 2005 Express ~ |
| 842 | 89 |
| 90 First launch vim.exe or gvim.exe and then launch Visual Studio. (If you don't | |
| 857 | 91 have Visual Studio, follow the instructions at |get-ms-debuggers| to obtain a |
| 842 | 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. | |
| 857 | 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. | |
| 842 | 120 |
| 857 | 121 *debug-windbg* |
| 2581 | 122 3.3 Debugging Vim crashes with WinDbg ~ |
| 857 | 123 |
| 124 See |get-ms-debuggers| to obtain a copy of WinDbg. | |
| 842 | 125 |
| 857 | 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 WinDbg | |
| 136 and set breakpoints, if you like. Reproduce your crash. WinDbg should open the | |
| 137 source file at the point of the crash. Using the View menu, you can examine | |
| 138 the call stack, local variables, watch windows, and so on. | |
| 842 | 139 |
| 857 | 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* | |
| 2581 | 148 3.4 Opening a Minidump ~ |
| 857 | 149 |
| 150 If you have a minidump file, you can open it in Visual Studio or in WinDbg. | |
| 502 | 151 |
| 857 | 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 in | |
| 157 |debug-windbg| to set the Symbol File Path. | |
| 158 | |
| 159 *get-ms-debuggers* | |
| 2581 | 160 3.5 Obtaining Microsoft Debugging Tools ~ |
| 857 | 161 |
| 162 The Debugging Tools for Windows (including WinDbg) can be downloaded from | |
| 502 | 163 http://www.microsoft.com/whdc/devtools/debugging/default.mspx |
| 164 This includes the WinDbg debugger. | |
| 165 | |
| 857 | 166 Visual C++ 2005 Express Edition can be downloaded for free from: |
| 167 http://msdn.microsoft.com/vstudio/express/visualC/default.aspx | |
| 502 | 168 |
| 169 ========================================================================= | |
| 14421 | 170 vim:tw=78:ts=8:noet:ft=help:norl: |