-* If you use X windows, it is a good idea to run Emacs under GDB (or
-some other suitable debugger) *all the time*, at least while
-pretesting.
-
-Then, when Emacs crashes, you will be able to debug the live process,
-not just a core dump. The `pr' command defined in src/.gdbinit is very
-useful in this case for examining Lisp_Object values as they would
-appear in Lisp.
-
-If you can't use `pr' because Emacs has got a fault already, or
-because you have only a core dump, you can use `xtype' to look at the
-type of a value, and then choose one of the other commands `xsymbol',
-`xstring', `xcons', `xvector' and so on to examine the contents.
-
-I myself *always* run Emacs under GDB so that I can debug conveniently
-if the occasion arises.
-
-* To get Lisp-level backtrace information within GDB,
-look for stack frames that call Ffuncall. Select them one by one in GDB
-and type this:
-
- p *args
- pr
-
-This will print the name of the Lisp function called by that level
-of function calling.
-
-By printing the remaining elements of args, you can see the argument
-values. Here's how to print the first argument:
-
- p args[1]
- pr
-
-If you do not have a live process, you can use xtype and the other
-x... commands such as xsymbol to get such information, albeit less
-conveniently.
-
-* Even with a live process, these x... commands are useful for
-examining the fields in a buffer, window, process, frame or marker.
-Here's an example using concepts explained in the node "Value History"
-of the GDB manual to print the variable frame from this line in
-xmenu.c:
-
- buf.frame_or_window = Fcons (frame, prefix);
-
-First, use these commands:
-
- cd src
- gdb emacs
- b xmenu.c:1209
- r -q
-
-Then type C-x 5 2 to create a new frame, and it hits the breakpoint:
-
- (gdb) p frame
- $1 = 1077872640
- (gdb) xtype
- Lisp_Vectorlike
- PVEC_FRAME
- (gdb) xframe
- $2 = (struct frame *) 0x3f0800
- (gdb) p *$
- $3 = {
- size = 536871989,
- next = 0x366240,
- name = 809661752,
- [...]
- }
- (gdb) p $3->name
- $4 = 809661752
-
-Now we can use `pr' to print the name of the frame:
-
- (gdb) pr
- "emacs@steenrod.math.nwu.edu"
-
-* The Emacs C code heavily uses macros defined in lisp.h. So suppose
-we want the address of the l-value expression near the bottom of
-`kbd_buffer_store_event' from keyboard.c:
-
- XVECTOR (kbd_buffer_frame_or_window)->contents[kbd_store_ptr
- - kbd_buffer]
- = event->frame_or_window);
-
-XVECTOR is a macro, and therefore GDB does not know about it.
-GDB cannot evaluate p XVECTOR (kbd_buffer_frame_or_window).
-
-However, you can use the xvector command in GDB to get the same
-result. Here is how:
-
- (gdb) p kbd_buffer_frame_or_window
- $1 = 1078005760
- (gdb) xvector
- $2 = (struct Lisp_Vector *) 0x411000
- 0
- (gdb) p $->contents[kbd_store_ptr - kbd_buffer]
- $3 = 1077872640
- (gdb) p &$
- $4 = (int *) 0x411008
-
-* Here's a related example of macros and the GDB `define' command.
-There are many Lisp vectors such as `recent_keys', which contains the
-last 100 keystrokes. We can print this Lisp vector
-
-p recent_keys
-pr
-
-But this may be inconvenient, since `recent_keys' is much more verbose
-than `C-h l'. We might want to print only the last 10 elements of
-this vector. `recent_keys' is updated in keyboard.c by the command
-
- XVECTOR (recent_keys)->contents[recent_keys_index] = c;
-
-So we define a GDB command `xvector-elts', so the last 10 keystrokes
-are printed by
-
- xvector-elts recent_keys recent_keys_index 10
-
-where you can define xvector-elts as follows:
-
- define xvector-elts
- set $i = 0
- p $arg0
- xvector
- set $foo = $
- while $i < $arg2
- p $foo->contents[$arg1-($i++)]
- pr
- end
- document xvector-elts
- Prints a range of elements of a Lisp vector.
- xvector-elts v n i
- prints `i' elements of the vector `v' ending at the index `n'.
- end
-
-* To debug what happens while preloading and dumping Emacs,
-do `gdb temacs' and start it with `r -batch -l loadup dump'.
-
-If temacs actually succeeds when running under GDB in this way, do not
-try to run the dumped Emacs, because it was dumped with the GDB
-breakpoints in it.
-
-* If you encounter X protocol errors, try evaluating (x-synchronize t).
-That puts Emacs into synchronous mode, where each Xlib call checks for
-errors before it returns. This mode is much slower, but when you get
-an error, you will see exactly which call really caused the error.
-
-* If the symptom of the bug is that Emacs fails to respond, don't
-assume Emacs is `hung'--it may instead be in an infinite loop. To
-find out which, make the problem happen under GDB and stop Emacs once
-it is not responding. (If Emacs is using X Windows directly, you can
-stop Emacs by typing C-z at the GDB job.) Then try stepping with
-`step'. If Emacs is hung, the `step' command won't return. If it is
-looping, `step' will return.
-
-If this shows Emacs is hung in a system call, stop it again and
-examine the arguments of the call. In your bug report, state exactly
-where in the source the system call is, and what the arguments are.
-
-If Emacs is in an infinite loop, please determine where the loop
-starts and ends. The easiest way to do this is to use the GDB command
-`finish'. Each time you use it, Emacs resumes execution until it
-exits one stack frame. Keep typing `finish' until it doesn't
-return--that means the infinite loop is in the stack frame which you
-just tried to finish.
-
-Stop Emacs again, and use `finish' repeatedly again until you get back
-to that frame. Then use `next' to step through that frame. By
-stepping, you will see where the loop starts and ends. Also please
-examine the data being used in the loop and try to determine why the
-loop does not exit when it should. Include all of this information in
-your bug report.
-
-* If certain operations in Emacs are slower than they used to be, here
-is some advice for how to find out why.
-
-Stop Emacs repeatedly during the slow operation, and make a backtrace
-each time. Compare the backtraces looking for a pattern--a specific
-function that shows up more often than you'd expect.
-
-If you don't see a pattern in the C backtraces, get some Lisp
-backtrace information by looking at Ffuncall frames (see above), and
-again look for a pattern.
-
-When using X, you can stop Emacs at any time by typing C-z at GDB.
-When not using X, you can do this with C-g.
-