+
+An easy way to see if too much text is being redrawn on a terminal is to
+evaluate `(setq inverse-video t)' before you try the operation you think
+will cause too much redrawing. This doesn't refresh the screen, so only
+newly drawn text is in inverse video.
+
+The Emacs display code includes special debugging code, but it is
+normally disabled. You can enable it by building Emacs with the
+pre-processing symbol GLYPH_DEBUG defined. Here's one easy way,
+suitable for Unix and GNU systems, to build such a debugging version:
+
+ MYCPPFLAGS='-DGLYPH_DEBUG=1' make
+
+Building Emacs like that activates many assertions which scrutinize
+display code operation more than Emacs does normally. (To see the
+code which tests these assertions, look for calls to the `xassert'
+macros.) Any assertion that is reported to fail should be
+investigated.
+
+Building with GLYPH_DEBUG defined also defines several helper
+functions which can help debugging display code. One such function is
+`dump_glyph_matrix'. If you run Emacs under GDB, you can print the
+contents of any glyph matrix by just calling that function with the
+matrix as its argument. For example, the following command will print
+the contents of the current matrix of the window whose pointer is in
+`w':
+
+ (gdb) p dump_glyph_matrix (w->current_matrix, 2)
+
+(The second argument 2 tells dump_glyph_matrix to print the glyphs in
+a long form.) You can dump the selected window's current glyph matrix
+interactively with "M-x dump-glyph-matrix RET"; see the documentation
+of this function for more details.
+
+Several more functions for debugging display code are available in
+Emacs compiled with GLYPH_DEBUG defined; type "C-h f dump- TAB" and
+"C-h f trace- TAB" to see the full list.
+
+When you debug display problems running emacs under X, you can use
+the `ff' command to flush all pending display updates to the screen.
+
+
+** Debugging LessTif
+
+If you encounter bugs whereby Emacs built with LessTif grabs all mouse
+and keyboard events, or LessTif menus behave weirdly, it might be
+helpful to set the `DEBUGSOURCES' and `DEBUG_FILE' environment
+variables, so that one can see what LessTif was doing at this point.
+For instance
+
+ export DEBUGSOURCES="RowColumn.c:MenuShell.c:MenuUtil.c"
+ export DEBUG_FILE=/usr/tmp/LESSTIF_TRACE
+ emacs &
+
+causes LessTif to print traces from the three named source files to a
+file in `/usr/tmp' (that file can get pretty large). The above should
+be typed at the shell prompt before invoking Emacs, as shown by the
+last line above.
+
+Running GDB from another terminal could also help with such problems.
+You can arrange for GDB to run on one machine, with the Emacs display
+appearing on another. Then, when the bug happens, you can go back to
+the machine where you started GDB and use the debugger from there.
+
+
+** Debugging problems which happen in GC
+
+The array `last_marked' (defined on alloc.c) can be used to display up
+to 500 last objects marked by the garbage collection process.
+Whenever the garbage collector marks a Lisp object, it records the
+pointer to that object in the `last_marked' array. The variable
+`last_marked_index' holds the index into the `last_marked' array one
+place beyond where the pointer to the very last marked object is
+stored.
+
+The single most important goal in debugging GC problems is to find the
+Lisp data structure that got corrupted. This is not easy since GC
+changes the tag bits and relocates strings which make it hard to look
+at Lisp objects with commands such as `pr'. It is sometimes necessary
+to convert Lisp_Object variables into pointers to C struct's manually.
+Use the `last_marked' array and the source to reconstruct the sequence
+that objects were marked.
+
+Once you discover the corrupted Lisp object or data structure, it is
+useful to look at it in a fresh Emacs session and compare its contents
+with a session that you are debugging.
+
+** Debugging problems with non-ASCII characters
+
+If you experience problems which seem to be related to non-ASCII
+characters, such as \201 characters appearing in the buffer or in your
+files, set the variable byte-debug-flag to t. This causes Emacs to do
+some extra checks, such as look for broken relations between byte and
+character positions in buffers and strings; the resulting diagnostics
+might pinpoint the cause of the problem.
+
+** Debugging the TTY (non-windowed) version
+
+The most convenient method of debugging the character-terminal display
+is to do that on a window system such as X. Begin by starting an
+xterm window, then type these commands inside that window:
+
+ $ tty
+ $ echo $TERM
+
+Let's say these commands print "/dev/ttyp4" and "xterm", respectively.
+
+Now start Emacs (the normal, windowed-display session, i.e. without
+the `-nw' option), and invoke "M-x gdb RET emacs RET" from there. Now
+type these commands at GDB's prompt:
+
+ (gdb) set args -nw -t /dev/ttyp4
+ (gdb) set environment TERM xterm
+ (gdb) run
+
+The debugged Emacs should now start in no-window mode with its display
+directed to the xterm window you opened above.
+
+Similar arrangement is possible on a character terminal by using the
+`screen' package.
+
+** Running Emacs built with malloc debugging packages
+
+If Emacs exhibits bugs that seem to be related to use of memory
+allocated off the heap, it might be useful to link Emacs with a
+special debugging library, such as Electric Fence (a.k.a. efence) or
+GNU Checker, which helps find such problems.
+
+Emacs compiled with such packages might not run without some hacking,
+because Emacs replaces the system's memory allocation functions with
+its own versions, and because the dumping process might be
+incompatible with the way these packages use to track allocated
+memory. Here are some of the changes you might find necessary
+(SYSTEM-NAME and MACHINE-NAME are the names of your OS- and
+CPU-specific headers in the subdirectories of `src'):
+
+ - In src/s/SYSTEM-NAME.h add "#define SYSTEM_MALLOC".
+
+ - In src/m/MACHINE-NAME.h add "#define CANNOT_DUMP" and
+ "#define CANNOT_UNEXEC".
+
+ - Configure with a different --prefix= option. If you use GCC,
+ version 2.7.2 is preferred, as some malloc debugging packages
+ work a lot better with it than with 2.95 or later versions.
+
+ - Type "make" then "make -k install".
+
+ - If required, invoke the package-specific command to prepare
+ src/temacs for execution.
+
+ - cd ..; src/temacs
+
+(Note that this runs `temacs' instead of the usual `emacs' executable.
+This avoids problems with dumping Emacs mentioned above.)
+
+Some malloc debugging libraries might print lots of false alarms for
+bitfields used by Emacs in some data structures. If you want to get
+rid of the false alarms, you will have to hack the definitions of
+these data structures on the respective headers to remove the `:N'
+bitfield definitions (which will cause each such field to use a full
+int).
+
+** How to recover buffer contents from an Emacs core dump file
+
+The file etc/emacs-buffer.gdb defines a set of GDB commands for
+recovering the contents of Emacs buffers from a core dump file. You
+might also find those commands useful for displaying the list of
+buffers in human-readable format from within the debugger.
+
+** Some suggestions for debugging on MS Windows:
+
+ (written by Marc Fleischeuers, Geoff Voelker and Andrew Innes)
+
+To debug Emacs with Microsoft Visual C++, you either start emacs from
+the debugger or attach the debugger to a running emacs process.
+
+To start emacs from the debugger, you can use the file bin/debug.bat.
+The Microsoft Developer studio will start and under Project, Settings,
+Debug, General you can set the command-line arguments and Emacs's
+startup directory. Set breakpoints (Edit, Breakpoints) at Fsignal and
+other functions that you want to examine. Run the program (Build,
+Start debug). Emacs will start and the debugger will take control as
+soon as a breakpoint is hit.
+
+You can also attach the debugger to an already running Emacs process.
+To do this, start up the Microsoft Developer studio and select Build,
+Start debug, Attach to process. Choose the Emacs process from the
+list. Send a break to the running process (Debug, Break) and you will
+find that execution is halted somewhere in user32.dll. Open the stack
+trace window and go up the stack to w32_msg_pump. Now you can set
+breakpoints in Emacs (Edit, Breakpoints). Continue the running Emacs
+process (Debug, Step out) and control will return to Emacs, until a
+breakpoint is hit.
+
+To examine the contents of a Lisp variable, you can use the function
+'debug_print'. Right-click on a variable, select QuickWatch (it has
+an eyeglass symbol on its button in the toolbar), and in the text
+field at the top of the window, place 'debug_print(' and ')' around
+the expression. Press 'Recalculate' and the output is sent to stderr,
+and to the debugger via the OutputDebugString routine. The output
+sent to stderr should be displayed in the console window that was
+opened when the emacs.exe executable was started. The output sent to
+the debugger should be displayed in the 'Debug' pane in the Output
+window. If Emacs was started from the debugger, a console window was
+opened at Emacs' startup; this console window also shows the output of
+'debug_print'.
+
+For example, start and run Emacs in the debugger until it is waiting
+for user input. Then click on the `Break' button in the debugger to
+halt execution. Emacs should halt in `ZwUserGetMessage' waiting for
+an input event. Use the `Call Stack' window to select the procedure
+`w32_msp_pump' up the call stack (see below for why you have to do
+this). Open the QuickWatch window and enter
+"debug_print(Vexec_path)". Evaluating this expression will then print
+out the contents of the Lisp variable `exec-path'.
+
+If QuickWatch reports that the symbol is unknown, then check the call
+stack in the `Call Stack' window. If the selected frame in the call
+stack is not an Emacs procedure, then the debugger won't recognize
+Emacs symbols. Instead, select a frame that is inside an Emacs
+procedure and try using `debug_print' again.
+
+If QuickWatch invokes debug_print but nothing happens, then check the
+thread that is selected in the debugger. If the selected thread is
+not the last thread to run (the "current" thread), then it cannot be
+used to execute debug_print. Use the Debug menu to select the current
+thread and try using debug_print again. Note that the debugger halts
+execution (e.g., due to a breakpoint) in the context of the current
+thread, so this should only be a problem if you've explicitly switched
+threads.
+
+It is also possible to keep appropriately masked and typecast Lisp
+symbols in the Watch window, this is more convenient when steeping
+though the code. For instance, on entering apply_lambda, you can
+watch (struct Lisp_Symbol *) (0xfffffff & args[0]).
+
+Optimizations often confuse the MS debugger. For example, the
+debugger will sometimes report wrong line numbers, e.g., when it
+prints the backtrace for a crash. It is usually best to look at the
+disassembly to determine exactly what code is being run--the
+disassembly will probably show several source lines followed by a
+block of assembler for those lines. The actual point where Emacs
+crashes will be one of those source lines, but not neccesarily the one
+that the debugger reports.
+
+Another problematic area with the MS debugger is with variables that
+are stored in registers: it will sometimes display wrong values for
+those variables. Usually you will not be able to see any value for a
+register variable, but if it is only being stored in a register
+temporarily, you will see an old value for it. Again, you need to
+look at the disassembly to determine which registers are being used,
+and look at those registers directly, to see the actual current values
+of these variables.
+
+;;; arch-tag: fbf32980-e35d-481f-8e4c-a2eca2586e6b