+ CFLAGS='-O0 -g3' ./configure --enable-checking='yes,glyphs' --enable-check-lisp-object-type
+
+The CFLAGS value is important: debugging optimized code can be very
+hard. (If the problem only happens with optimized code, you may need
+to enable optimizations. If that happens, try using -Og first,
+instead of -O2, as the former will disable some optimizations that
+make debugging some code exceptionally hard.)
+
+Modern versions of GCC support more elaborate debug info that is
+available by just using the -g3 compiler switch. Try using -gdwarf-4
+in addition to -g3, and if that fails, try -gdwarf-3. This is
+especially important if you have to debug optimized code. More info
+about this is available below; search for "analyze failed assertions".
+
+The 2 --enable-* switches are optional. They don't have any effect on
+debugging with GDB, but will compile additional code that might catch
+the problem you are debugging much earlier, in the form of assertion
+violation. The --enable-checking option also enables additional
+functionality useful for debugging display problems; see more about
+this below under "Debugging Emacs redisplay problems".
+
+Emacs needs not be installed to be debugged, you can debug the binary
+created in the 'src' directory.
+
+*** Configuring GDB
+
+When you debug Emacs with GDB, you should start GDB in the directory
+where the Emacs executable was made (the 'src' directory in the Emacs
+source tree). That directory has a .gdbinit file that defines various
+"user-defined" commands for debugging Emacs. (These commands are
+described below under "Examining Lisp object values" and "Debugging
+Emacs Redisplay problems".)
+
+Starting the debugger from Emacs, via the "M-x gdb" command (described
+below), when the current buffer visits one of the Emacs C source files
+will automatically start GDB in the 'src' directory.
+
+Some GDB versions by default do not automatically load .gdbinit files
+in the directory where you invoke GDB. With those versions of GDB,
+you will see a warning when GDB starts, like this:
+
+ warning: File ".../src/.gdbinit" auto-loading has been declined by your `auto-load safe-path' set to "$debugdir:$datadir/auto-load".
+
+The simplest way to fix this is to add the following line to your
+~/.gdbinit file:
+
+ add-auto-load-safe-path /path/to/emacs/src/.gdbinit
+
+There are other ways to overcome that difficulty, they are all
+described in the node "Auto-loading safe path" in the GDB user manual.
+If nothing else helps, type "source /path/to/.gdbinit RET" at the GDB
+prompt, to unconditionally load the GDB init file.
+
+*** Use the Emacs GDB UI front-end
+
+We recommend using the GUI front-end for GDB provided by Emacs. With
+it, you can start GDB by typing "M-x gdb RET". This will suggest the
+file name of the default binary to debug; if the suggested default is
+not the Emacs binary you want to debug, change the file name as
+needed. Alternatively, if you want to attach the debugger to an
+already running Emacs process, change the GDB command shown in the
+minibuffer to say this:
+
+ gdb -i=mi -p PID
+
+where PID is the numerical process ID of the running Emacs process,
+displayed by system utilities such as 'top' or 'ps' on Posix hosts and
+Task Manager on MS-Windows.
+
+Once the debugger starts, open the additional windows provided by the
+GDB UI, by typing "M-x gdb-many-windows RET". (Alternatively, click
+Gud->GDB-MI->Display Other Windows" from the menu bar.) At this
+point, make your frame large enough (or full-screen) such that the
+windows you just opened have enough space to show the content without
+horizontal scrolling.
+
+You can later restore your window configuration with the companion
+command "M-x gdb-restore-windows RET", or by deselecting "Display
+Other Windows" from the menu bar.
+
+*** Setting initial breakpoints
+
+Before you let Emacs run, you should now set breakpoints in the code
+which you want to debug, so that Emacs stops there and lets GDB take
+control. If the code which you want to debug is executed under some
+rare conditions, or only when a certain Emacs command is manually
+invoked, then just set your breakpoint there, let Emacs run, and
+trigger the breakpoint by invoking that command or reproducing those
+rare conditions.
+
+If you are less lucky, and the code in question is run very
+frequently, you will have to find some way of avoiding triggering your
+breakpoint when the conditions for the buggy behavior did not yet
+happen. There's no single recipe for this, you will have to be
+creative and study the code to see what's appropriate. Some useful
+tricks for that:
+
+ . Make your breakpoint conditional on certain buffer or string
+ position. For example:
+
+ (gdb) break foo.c:1234 if PT >= 9876
+
+ . Set a break point in some rarely called function, then create the
+ conditions for the bug, call that rare function, and when GDB gets
+ control, set the breakpoint in the buggy code, knowing that it
+ will now be called when the bug happens.
+
+ . If the bug manifests itself as an error message, set a breakpoint
+ in Fsignal, and when it breaks, look at the backtrace to see what
+ triggers the error.
+
+Some additional techniques are described below under "Getting control
+to the debugger".
+
+You are now ready to start your debugging session.
+
+If you are starting a new Emacs session, type "run", followed by any
+command-line arguments (e.g., "-Q") into the *gud-emacs* buffer and
+press RET.
+
+If you attached the debugger to a running Emacs, type "continue" into
+the *gud-emacs* buffer and press RET.
+
+Many variables you will encounter while debugging are Lisp objects.
+These are displayed as integer values (or structures, if you used the
+"--enable-check-lisp-object-type" option at configure time) that are
+hard to interpret, especially if they represent long lists. You can
+use the 'pp' command to display them in their Lisp form. That command
+displays its output on the standard error stream, which you
+can redirect to a file using "M-x redirect-debugging-output".
+This means that if you attach GDB to a running Emacs that was invoked
+from a desktop icon, chances are you will not see the output at all,
+or it will wind up in an obscure place (check the documentation of
+your desktop environment).
+
+Additional information about displaying Lisp objects can be found
+under "Examining Lisp object values" below.
+
+The rest of this document describes specific useful techniques for
+debugging Emacs; we suggest reading it in its entirety the first time
+you are about to debug Emacs, then look up your specific issues
+whenever you need.
+
+Good luck!
+
+** When you are trying to analyze failed assertions or backtraces, it
+is essential to compile Emacs with flags suitable for debugging.
+With GCC 4.8 or later, you can invoke 'make' with CFLAGS="-Og -g3".
+With older GCC or non-GCC compilers, you can use CFLAGS="-O0 -g3".
+With GCC and higher optimization levels such as -O2, the
+-fno-omit-frame-pointer and -fno-crossjumping options are often
+essential. The latter prevents GCC from using the same abort call for
+all assertions in a given function, rendering the stack backtrace
+useless for identifying the specific failed assertion.
+Some versions of GCC support recent versions of the DWARF standard for
+debugging info, but default to older versions; for example, they could
+support -gdwarf-4 compiler option (for DWARF v4), but default to
+version 2 of the DWARF standard. For best results in debugging
+abilities, find out the highest version of DWARF your GCC can support,
+and use the corresponding -gdwarf-N switch instead of just -g (you
+will still need -g3, as in "-gdwarf-4 -g3").