| *debug.txt* For Vim version 7.4. Last change: 2012 Feb 11 |
| |
| |
| VIM REFERENCE MANUAL by Bram Moolenaar |
| |
| |
| Debugging Vim *debug-vim* |
| |
| This is for debugging Vim itself, when it doesn't work properly. |
| For debugging Vim scripts, functions, etc. see |debug-scripts| |
| |
| 1. Location of a crash, using gcc and gdb |debug-gcc| |
| 2. Locating memory leaks |debug-leaks| |
| 3. Windows Bug Reporting |debug-win32| |
| |
| ============================================================================== |
| |
| 1. Location of a crash, using gcc and gdb *debug-gcc* *gdb* |
| |
| When Vim crashes in one of the test files, and you are using gcc for |
| compilation, here is what you can do to find out exactly where Vim crashes. |
| This also applies when using the MingW tools. |
| |
| 1. Compile Vim with the "-g" option (there is a line in the src/Makefile for |
| this, which you can uncomment). Also make sure "strip" is disabled (do not |
| install it, or use the line "STRIP = /bin/true"). |
| |
| 2. Execute these commands (replace "11" with the test that fails): > |
| cd testdir |
| gdb ../vim |
| run -u unix.vim -U NONE -s dotest.in test11.in |
| |
| 3. Check where Vim crashes, gdb should give a message for this. |
| |
| 4. Get a stack trace from gdb with this command: > |
| where |
| < You can check out different places in the stack trace with: > |
| frame 3 |
| < Replace "3" with one of the numbers in the stack trace. |
| |
| ============================================================================== |
| |
| 2. Locating memory leaks *debug-leaks* *valgrind* |
| |
| If you suspect Vim is leaking memory and you are using Linux, the valgrind |
| tool is very useful to pinpoint memory leaks. |
| |
| First of all, build Vim with EXITFREE defined. Search for this in MAKEFILE |
| and uncomment the line. |
| |
| Use this command to start Vim: |
| > |
| valgrind --log-file=valgrind.log --leak-check=full ./vim |
| |
| Note: Vim will run much slower. If your .vimrc is big or you have several |
| plugins you need to be patient for startup, or run with the "-u NONE" |
| argument. |
| |
| There are often a few leaks from libraries, such as getpwuid() and |
| XtVaAppCreateShell(). Those are unavoidable. The number of bytes should be |
| very small a Kbyte or less. |
| |
| ============================================================================== |
| |
| 3. Windows Bug Reporting *debug-win32* |
| |
| If the Windows version of Vim crashes in a reproducible manner, you can take |
| some steps to provide a useful bug report. |
| |
| |
| 3.1 GENERIC ~ |
| |
| You must obtain the debugger symbols (PDB) file for your executable: gvim.pdb |
| for gvim.exe, or vim.pdb for vim.exe. The PDB should be available from the |
| same place that you obtained the executable. Be sure to use the PDB that |
| matches the EXE (same date). |
| |
| If you built the executable yourself with the Microsoft Visual C++ compiler, |
| then the PDB was built with the EXE. |
| |
| Alternatively, if you have the source files, you can import Make_ivc.mak into |
| Visual Studio as a workspace. Then select a debug configuration, build and |
| you can do all kinds of debugging (set breakpoints, watch variables, etc.). |
| |
| If you have Visual Studio, use that instead of the VC Toolkit and WinDbg. |
| |
| For other compilers, you should always use the corresponding debugger: TD for |
| a Vim executable compiled with the Borland compiler; gdb (see above |
| |debug-gcc|) for the Cygwin and MinGW compilers. |
| |
| |
| *debug-vs2005* |
| 3.2 Debugging Vim crashes with Visual Studio 2005/Visual C++ 2005 Express ~ |
| |
| First launch vim.exe or gvim.exe and then launch Visual Studio. (If you don't |
| have Visual Studio, follow the instructions at |get-ms-debuggers| to obtain a |
| free copy of Visual C++ 2005 Express Edition.) |
| |
| On the Tools menu, click Attach to Process. Choose the Vim process. |
| |
| In Vim, reproduce the crash. A dialog will appear in Visual Studio, telling |
| you about the unhandled exception in the Vim process. Click Break to break |
| into the process. |
| |
| Visual Studio will pop up another dialog, telling you that no symbols are |
| loaded and that the source code cannot be displayed. Click OK. |
| |
| Several windows will open. Right-click in the Call Stack window. Choose Load |
| Symbols. The Find Symbols dialog will open, looking for (g)vim.pdb. Navigate |
| to the directory where you have the PDB file and click Open. |
| |
| At this point, you should have a full call stack with vim function names and |
| line numbers. Double-click one of the lines and the Find Source dialog will |
| appear. Navigate to the directory where the Vim source is (if you have it.) |
| |
| If you don't know how to debug this any further, follow the instructions |
| at ":help bug-reports". Paste the call stack into the bug report. |
| |
| If you have a non-free version of Visual Studio, you can save a minidump via |
| the Debug menu and send it with the bug report. A minidump is a small file |
| (<100KB), which contains information about the state of your process. |
| Visual C++ 2005 Express Edition cannot save minidumps and it cannot be |
| installed as a just-in-time debugger. Use WinDbg, |debug-windbg|, if you |
| need to save minidumps or you want a just-in-time (postmortem) debugger. |
| |
| *debug-windbg* |
| 3.3 Debugging Vim crashes with WinDbg ~ |
| |
| See |get-ms-debuggers| to obtain a copy of WinDbg. |
| |
| As with the Visual Studio IDE, you can attach WinDbg to a running Vim process. |
| You can also have your system automatically invoke WinDbg as a postmortem |
| debugger. To set WinDbg as your postmortem debugger, run "windbg -I". |
| |
| To attach WinDbg to a running Vim process, launch WinDbg. On the File menu, |
| choose Attach to a Process. Select the Vim process and click OK. |
| |
| At this point, choose Symbol File Path on the File menu, and add the folder |
| containing your Vim PDB to the sympath. If you have Vim source available, |
| use Source File Path on the File menu. You can now open source files in WinDbg |
| and set breakpoints, if you like. Reproduce your crash. WinDbg should open the |
| source file at the point of the crash. Using the View menu, you can examine |
| the call stack, local variables, watch windows, and so on. |
| |
| If WinDbg is your postmortem debugger, you do not need to attach WinDbg to |
| your Vim process. Simply reproduce the crash and WinDbg will launch |
| automatically. As above, set the Symbol File Path and the Source File Path. |
| |
| To save a minidump, type the following at the WinDbg command line: > |
| .dump vim.dmp |
| < |
| *debug-minidump* |
| 3.4 Opening a Minidump ~ |
| |
| If you have a minidump file, you can open it in Visual Studio or in WinDbg. |
| |
| In Visual Studio 2005: on the File menu, choose Open, then Project/Solution. |
| Navigate to the .dmp file and open it. Now press F5 to invoke the debugger. |
| Follow the instructions in |debug-vs2005| to set the Symbol File Path. |
| |
| In WinDbg: choose Open Crash Dump on the File menu. Follow the instructions in |
| |debug-windbg| to set the Symbol File Path. |
| |
| *get-ms-debuggers* |
| 3.5 Obtaining Microsoft Debugging Tools ~ |
| |
| The Debugging Tools for Windows (including WinDbg) can be downloaded from |
| http://www.microsoft.com/whdc/devtools/debugging/default.mspx |
| This includes the WinDbg debugger. |
| |
| Visual C++ 2005 Express Edition can be downloaded for free from: |
| http://msdn.microsoft.com/vstudio/express/visualC/default.aspx |
| |
| ========================================================================= |
| vim:tw=78:ts=8:ft=help:norl: |