1 files changed, 170 insertions, 0 deletions
diff --git a/mnv/runtime/doc/debug.txt b/mnv/runtime/doc/debug.txt
new file mode 100644
index 0000000000..96861d564c
--- /dev/null
+++ b/mnv/runtime/doc/debug.txt
@@ -0,0 +1,170 @@
+*debug.txt*	For MNV version 10.0.  Last change: 2026 Feb 14
+
+
+		  MNV REFERENCE MANUAL	  by Bram Moolenaar
+
+
+Debugging MNV						*debug-mnv*
+
+This is for debugging MNV itself, when it doesn't work properly.
+For debugging MNV 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 MNV 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 MNV crashes.
+This also applies when using the MingW tools.
+
+1. Compile MNV 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 ../mnv
+	run -u unix.mnv -U NONE -s dotest.in test11.in
+
+3. Check where MNV 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 MNV is leaking memory and you are using Linux, the valgrind
+tool is very useful to pinpoint memory leaks.
+
+First of all, build MNV with EXITFREE defined.  Search for this in MAKEFILE
+and uncomment the line.
+
+Use this command to start MNV:
+>
+	valgrind --log-file=valgrind.log --leak-check=full ./mnv
+
+Note: MNV will run much slower.  If your .mnvrc is big or you have several
+plugins you need to be patient for startup, or run with the "--clean"
+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 MNV 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: gmnv.pdb
+for gmnv.exe, or mnv.pdb for mnv.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.
+
+If you have Visual Studio, use that instead of the VC Toolkit and WinDbg.
+
+For other compilers, you should always use the corresponding debugger: gdb
+(see above |debug-gcc|) for the Cygwin and MinGW compilers.
+
+
+								*debug-vs2005*
+3.2 Debugging MNV crashes with Visual Studio 2005/Visual C++ 2005 Express ~
+
+First launch mnv.exe or gmnv.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 MNV process.
+
+In MNV, reproduce the crash.  A dialog will appear in Visual Studio, telling
+you about the unhandled exception in the MNV 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)mnv.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 mnv function names and
+line numbers.  Double-click one of the lines and the Find Source dialog will
+appear.  Navigate to the directory where the MNV 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 MNV 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 MNV 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 MNV process, launch WinDbg.  On the File menu,
+choose Attach to a Process.  Select the MNV process and click OK.
+
+At this point, choose Symbol File Path on the File menu, and add the folder
+containing your MNV PDB to the sympath.  If you have MNV 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 MNV 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 mnv.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
+    https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/debugger-download-tools
+This includes the WinDbg debugger.
+
+Visual C++ 2005 Express Edition can be downloaded for free from:
+    https://visualstudio.microsoft.com/
+
+=========================================================================
+ mnv:tw=78:ts=8:noet:ft=help:norl: