annotate etc/DEBUG @ 111686:e8049570c647

* lisp/eshell/: Use with-silent-modifications. * lisp/eshell/esh-cmd.el (eshell-parse-command): * lisp/eshell/esh-arg.el (eshell-parse-arguments): * lisp/eshell/em-script.el (eshell-source-file): Use with-silent-modifications.
author Stefan Monnier <monnier@iro.umontreal.ca>
date Tue, 23 Nov 2010 12:36:15 -0500
parents 6799ec1a7188
children 417b1e4d63cd
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
25853
Dave Love <fx@gnu.org>
parents:
diff changeset
1 Debugging GNU Emacs
75774
dc23aaa67696 Switch to standard GPL text for license.
Glenn Morris <rgm@gnu.org>
parents: 75348
diff changeset
2
106815
1d1d5d9bd884 Add 2010 to copyright years.
Glenn Morris <rgm@gnu.org>
parents: 100972
diff changeset
3 Copyright (C) 1985, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
1d1d5d9bd884 Add 2010 to copyright years.
Glenn Morris <rgm@gnu.org>
parents: 100972
diff changeset
4 2008, 2009, 2010 Free Software Foundation, Inc.
75774
dc23aaa67696 Switch to standard GPL text for license.
Glenn Morris <rgm@gnu.org>
parents: 75348
diff changeset
5 See the end of the file for license conditions.
25853
Dave Love <fx@gnu.org>
parents:
diff changeset
6
Dave Love <fx@gnu.org>
parents:
diff changeset
7
109073
6799ec1a7188 Remove some cpp that is internal to configure.in.
Glenn Morris <rgm@gnu.org>
parents: 108619
diff changeset
8 [People who debug Emacs on Windows using Microsoft debuggers should
6799ec1a7188 Remove some cpp that is internal to configure.in.
Glenn Morris <rgm@gnu.org>
parents: 108619
diff changeset
9 read the Windows-specific section near the end of this document.]
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
10
43432
7fe131ded6d9 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 43106
diff changeset
11 ** When you debug Emacs with GDB, you should start it in the directory
59939
b9511a236e82 Minor clarification.
Richard M. Stallman <rms@gnu.org>
parents: 59613
diff changeset
12 where the executable was made. That directory has a .gdbinit file
b9511a236e82 Minor clarification.
Richard M. Stallman <rms@gnu.org>
parents: 59613
diff changeset
13 that defines various "user-defined" commands for debugging Emacs.
71448
8c249825e7f3 Add reference to description of .gdbinit commands.
Eli Zaretskii <eliz@gnu.org>
parents: 71445
diff changeset
14 (These commands are described below under "Examining Lisp object
8c249825e7f3 Add reference to description of .gdbinit commands.
Eli Zaretskii <eliz@gnu.org>
parents: 71445
diff changeset
15 values" and "Debugging Emacs Redisplay problems".)
43432
7fe131ded6d9 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 43106
diff changeset
16
60334
ec7a860cdd57 Add information about `-fno-crossjumping' for GCC.
David Kastrup <dak@gnu.org>
parents: 59939
diff changeset
17 ** When you are trying to analyze failed assertions, it will be
ec7a860cdd57 Add information about `-fno-crossjumping' for GCC.
David Kastrup <dak@gnu.org>
parents: 59939
diff changeset
18 essential to compile Emacs either completely without optimizations or
ec7a860cdd57 Add information about `-fno-crossjumping' for GCC.
David Kastrup <dak@gnu.org>
parents: 59939
diff changeset
19 at least (when using GCC) with the -fno-crossjumping option. Failure
ec7a860cdd57 Add information about `-fno-crossjumping' for GCC.
David Kastrup <dak@gnu.org>
parents: 59939
diff changeset
20 to do so may make the compiler recycle the same abort call for all
ec7a860cdd57 Add information about `-fno-crossjumping' for GCC.
David Kastrup <dak@gnu.org>
parents: 59939
diff changeset
21 assertions in a given function, rendering the stack backtrace useless
ec7a860cdd57 Add information about `-fno-crossjumping' for GCC.
David Kastrup <dak@gnu.org>
parents: 59939
diff changeset
22 for identifying the specific failed assertion.
ec7a860cdd57 Add information about `-fno-crossjumping' for GCC.
David Kastrup <dak@gnu.org>
parents: 59939
diff changeset
23
43432
7fe131ded6d9 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 43106
diff changeset
24 ** It is a good idea to run Emacs under GDB (or some other suitable
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
25 debugger) *all the time*. Then, when Emacs crashes, you will be able
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
26 to debug the live process, not just a core dump. (This is especially
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
27 important on systems which don't support core files, and instead print
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
28 just the registers and some stack addresses.)
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
29
43432
7fe131ded6d9 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 43106
diff changeset
30 ** If Emacs hangs, or seems to be stuck in some infinite loop, typing
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
31 "kill -TSTP PID", where PID is the Emacs process ID, will cause GDB to
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
32 kick in, provided that you run under GDB.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
33
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
34 ** Getting control to the debugger
25853
Dave Love <fx@gnu.org>
parents:
diff changeset
35
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
36 `Fsignal' is a very useful place to put a breakpoint in.
25853
Dave Love <fx@gnu.org>
parents:
diff changeset
37 All Lisp errors go through there.
Dave Love <fx@gnu.org>
parents:
diff changeset
38
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
39 It is useful, when debugging, to have a guaranteed way to return to
44813
927a6a3e6c8f Tell them to use C-z, not C-c, to stop Emacs under X.
Eli Zaretskii <eliz@gnu.org>
parents: 43432
diff changeset
40 the debugger at any time. When using X, this is easy: type C-z at the
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
41 window where Emacs is running under GDB, and it will stop Emacs just
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
42 as it would stop any ordinary program. When Emacs is running in a
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
43 terminal, things are not so easy.
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
44
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
45 The src/.gdbinit file in the Emacs distribution arranges for SIGINT
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
46 (C-g in Emacs) to be passed to Emacs and not give control back to GDB.
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
47 On modern POSIX systems, you can override that with this command:
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
48
43106
cd4549362019 Fix a typo in "handle SIGINT" command.
Eli Zaretskii <eliz@gnu.org>
parents: 41839
diff changeset
49 handle SIGINT stop nopass
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
50
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
51 After this `handle' command, SIGINT will return control to GDB. If
109073
6799ec1a7188 Remove some cpp that is internal to configure.in.
Glenn Morris <rgm@gnu.org>
parents: 108619
diff changeset
52 you want the C-g to cause a QUIT within Emacs as well, omit the `nopass'.
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
53
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
54 A technique that can work when `handle SIGINT' does not is to store
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
55 the code for some character into the variable stop_character. Thus,
25853
Dave Love <fx@gnu.org>
parents:
diff changeset
56
Dave Love <fx@gnu.org>
parents:
diff changeset
57 set stop_character = 29
Dave Love <fx@gnu.org>
parents:
diff changeset
58
Dave Love <fx@gnu.org>
parents:
diff changeset
59 makes Control-] (decimal code 29) the stop character.
Dave Love <fx@gnu.org>
parents:
diff changeset
60 Typing Control-] will cause immediate stop. You cannot
Dave Love <fx@gnu.org>
parents:
diff changeset
61 use the set command until the inferior process has been started.
Dave Love <fx@gnu.org>
parents:
diff changeset
62 Put a breakpoint early in `main', or suspend the Emacs,
Dave Love <fx@gnu.org>
parents:
diff changeset
63 to get an opportunity to do the set command.
Dave Love <fx@gnu.org>
parents:
diff changeset
64
80897
5ba6d7571941 Qualify using a separate terminal for debugging.
Nick Roberts <nickrob@snap.net.nz>
parents: 77156
diff changeset
65 When Emacs is running in a terminal, it is sometimes useful to use a separate
5ba6d7571941 Qualify using a separate terminal for debugging.
Nick Roberts <nickrob@snap.net.nz>
parents: 77156
diff changeset
66 terminal for the debug session. This can be done by starting Emacs as usual,
5ba6d7571941 Qualify using a separate terminal for debugging.
Nick Roberts <nickrob@snap.net.nz>
parents: 77156
diff changeset
67 then attaching to it from gdb with the `attach' command which is explained in
5ba6d7571941 Qualify using a separate terminal for debugging.
Nick Roberts <nickrob@snap.net.nz>
parents: 77156
diff changeset
68 the node "Attach" of the GDB manual.
59613
1c3d052ef4bf Suggest separate terminal for debug session.
Nick Roberts <nickrob@snap.net.nz>
parents: 58969
diff changeset
69
25853
Dave Love <fx@gnu.org>
parents:
diff changeset
70 ** Examining Lisp object values.
Dave Love <fx@gnu.org>
parents:
diff changeset
71
Dave Love <fx@gnu.org>
parents:
diff changeset
72 When you have a live process to debug, and it has not encountered a
Dave Love <fx@gnu.org>
parents:
diff changeset
73 fatal error, you can use the GDB command `pr'. First print the value
Dave Love <fx@gnu.org>
parents:
diff changeset
74 in the ordinary way, with the `p' command. Then type `pr' with no
Dave Love <fx@gnu.org>
parents:
diff changeset
75 arguments. This calls a subroutine which uses the Lisp printer.
Dave Love <fx@gnu.org>
parents:
diff changeset
76
57307
7e6072c66e67 Mention pp and ff commands.
Kim F. Storm <storm@cua.dk>
parents: 52401
diff changeset
77 You can also use `pp value' to print the emacs value directly.
7e6072c66e67 Mention pp and ff commands.
Kim F. Storm <storm@cua.dk>
parents: 52401
diff changeset
78
71445
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
79 To see the current value of a Lisp Variable, use `pv variable'.
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
80
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
81 Note: It is not a good idea to try `pr', `pp', or `pv' if you know that Emacs
57307
7e6072c66e67 Mention pp and ff commands.
Kim F. Storm <storm@cua.dk>
parents: 52401
diff changeset
82 is in deep trouble: its stack smashed (e.g., if it encountered SIGSEGV
7e6072c66e67 Mention pp and ff commands.
Kim F. Storm <storm@cua.dk>
parents: 52401
diff changeset
83 due to stack overflow), or crucial data structures, such as `obarray',
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
84 corrupted, etc. In such cases, the Emacs subroutine called by `pr'
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
85 might make more damage, like overwrite some data that is important for
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
86 debugging the original problem.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
87
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
88 Also, on some systems it is impossible to use `pr' if you stopped
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
89 Emacs while it was inside `select'. This is in fact what happens if
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
90 you stop Emacs while it is waiting. In such a situation, don't try to
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
91 use `pr'. Instead, use `s' to step out of the system call. Then
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
92 Emacs will be between instructions and capable of handling `pr'.
25853
Dave Love <fx@gnu.org>
parents:
diff changeset
93
71445
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
94 If you can't use `pr' command, for whatever reason, you can use the
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
95 `xpr' command to print out the data type and value of the last data
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
96 value, For example:
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
97
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
98 p it->object
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
99 xpr
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
100
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
101 You may also analyze data values using lower-level commands. Use the
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
102 `xtype' command to print out the data type of the last data value.
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
103 Once you know the data type, use the command that corresponds to that
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
104 type. Here are these commands:
25853
Dave Love <fx@gnu.org>
parents:
diff changeset
105
Dave Love <fx@gnu.org>
parents:
diff changeset
106 xint xptr xwindow xmarker xoverlay xmiscfree xintfwd xboolfwd xobjfwd
Dave Love <fx@gnu.org>
parents:
diff changeset
107 xbufobjfwd xkbobjfwd xbuflocal xbuffer xsymbol xstring xvector xframe
Dave Love <fx@gnu.org>
parents:
diff changeset
108 xwinconfig xcompiled xcons xcar xcdr xsubr xprocess xfloat xscrollbar
Dave Love <fx@gnu.org>
parents:
diff changeset
109
Dave Love <fx@gnu.org>
parents:
diff changeset
110 Each one of them applies to a certain type or class of types.
Dave Love <fx@gnu.org>
parents:
diff changeset
111 (Some of these types are not visible in Lisp, because they exist only
Dave Love <fx@gnu.org>
parents:
diff changeset
112 internally.)
Dave Love <fx@gnu.org>
parents:
diff changeset
113
Dave Love <fx@gnu.org>
parents:
diff changeset
114 Each x... command prints some information about the value, and
Dave Love <fx@gnu.org>
parents:
diff changeset
115 produces a GDB value (subsequently available in $) through which you
Dave Love <fx@gnu.org>
parents:
diff changeset
116 can get at the rest of the contents.
Dave Love <fx@gnu.org>
parents:
diff changeset
117
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
118 In general, most of the rest of the contents will be additional Lisp
25853
Dave Love <fx@gnu.org>
parents:
diff changeset
119 objects which you can examine in turn with the x... commands.
Dave Love <fx@gnu.org>
parents:
diff changeset
120
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
121 Even with a live process, these x... commands are useful for
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
122 examining the fields in a buffer, window, process, frame or marker.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
123 Here's an example using concepts explained in the node "Value History"
58969
eae7969f1b06 Change printing example to break on a procedure name.
Nick Roberts <nickrob@snap.net.nz>
parents: 57307
diff changeset
124 of the GDB manual to print values associated with the variable
eae7969f1b06 Change printing example to break on a procedure name.
Nick Roberts <nickrob@snap.net.nz>
parents: 57307
diff changeset
125 called frame. First, use these commands:
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
126
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
127 cd src
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
128 gdb emacs
58969
eae7969f1b06 Change printing example to break on a procedure name.
Nick Roberts <nickrob@snap.net.nz>
parents: 57307
diff changeset
129 b set_frame_buffer_list
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 49489
diff changeset
130 r -q
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
131
59613
1c3d052ef4bf Suggest separate terminal for debug session.
Nick Roberts <nickrob@snap.net.nz>
parents: 58969
diff changeset
132 Then Emacs hits the breakpoint:
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
133
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
134 (gdb) p frame
58969
eae7969f1b06 Change printing example to break on a procedure name.
Nick Roberts <nickrob@snap.net.nz>
parents: 57307
diff changeset
135 $1 = 139854428
71445
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
136 (gdb) xpr
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
137 Lisp_Vectorlike
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
138 PVEC_FRAME
58969
eae7969f1b06 Change printing example to break on a procedure name.
Nick Roberts <nickrob@snap.net.nz>
parents: 57307
diff changeset
139 $2 = (struct frame *) 0x8560258
71445
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
140 "emacs@localhost"
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
141 (gdb) p *$
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
142 $3 = {
58969
eae7969f1b06 Change printing example to break on a procedure name.
Nick Roberts <nickrob@snap.net.nz>
parents: 57307
diff changeset
143 size = 1073742931,
eae7969f1b06 Change printing example to break on a procedure name.
Nick Roberts <nickrob@snap.net.nz>
parents: 57307
diff changeset
144 next = 0x85dfe58,
eae7969f1b06 Change printing example to break on a procedure name.
Nick Roberts <nickrob@snap.net.nz>
parents: 57307
diff changeset
145 name = 140615219,
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
146 [...]
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
147 }
71445
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
148
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
149 Now we can use `pr' to print the frame parameters:
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
150
71445
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
151 (gdb) pp $->param_alist
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
152 ((background-mode . light) (display-type . color) [...])
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
153
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
154
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
155 The Emacs C code heavily uses macros defined in lisp.h. So suppose
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
156 we want the address of the l-value expression near the bottom of
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
157 `add_command_key' from keyboard.c:
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
158
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
159 XVECTOR (this_command_keys)->contents[this_command_key_count++] = key;
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
160
66719
c0eb744f79f7 Describe how to provide preprocessor macro information.
Nick Roberts <nickrob@snap.net.nz>
parents: 66645
diff changeset
161 XVECTOR is a macro, so GDB only knows about it if Emacs has been compiled with
c0eb744f79f7 Describe how to provide preprocessor macro information.
Nick Roberts <nickrob@snap.net.nz>
parents: 66645
diff changeset
162 preprocessor macro information. GCC provides this if you specify the options
c0eb744f79f7 Describe how to provide preprocessor macro information.
Nick Roberts <nickrob@snap.net.nz>
parents: 66645
diff changeset
163 `-gdwarf-2' and `-g3'. In this case, GDB can evaluate expressions like
c0eb744f79f7 Describe how to provide preprocessor macro information.
Nick Roberts <nickrob@snap.net.nz>
parents: 66645
diff changeset
164 "p XVECTOR (this_command_keys)".
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
165
66719
c0eb744f79f7 Describe how to provide preprocessor macro information.
Nick Roberts <nickrob@snap.net.nz>
parents: 66645
diff changeset
166 When this information isn't available, you can use the xvector command in GDB
c0eb744f79f7 Describe how to provide preprocessor macro information.
Nick Roberts <nickrob@snap.net.nz>
parents: 66645
diff changeset
167 to get the same result. Here is how:
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
168
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
169 (gdb) p this_command_keys
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
170 $1 = 1078005760
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
171 (gdb) xvector
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
172 $2 = (struct Lisp_Vector *) 0x411000
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
173 0
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
174 (gdb) p $->contents[this_command_key_count]
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
175 $3 = 1077872640
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
176 (gdb) p &$
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
177 $4 = (int *) 0x411008
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
178
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
179 Here's a related example of macros and the GDB `define' command.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
180 There are many Lisp vectors such as `recent_keys', which contains the
98620
9c8d02adc5c4 `recent_keys' now holds last 300 keystrokes, not 100.
Romain Francoise <romain@orebokech.com>
parents: 95004
diff changeset
181 last 300 keystrokes. We can print this Lisp vector
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
182
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
183 p recent_keys
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
184 pr
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
185
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
186 But this may be inconvenient, since `recent_keys' is much more verbose
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
187 than `C-h l'. We might want to print only the last 10 elements of
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
188 this vector. `recent_keys' is updated in keyboard.c by the command
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
189
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
190 XVECTOR (recent_keys)->contents[recent_keys_index] = c;
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
191
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
192 So we define a GDB command `xvector-elts', so the last 10 keystrokes
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 49489
diff changeset
193 are printed by
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
194
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
195 xvector-elts recent_keys recent_keys_index 10
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
196
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
197 where you can define xvector-elts as follows:
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
198
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
199 define xvector-elts
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
200 set $i = 0
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
201 p $arg0
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
202 xvector
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
203 set $foo = $
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
204 while $i < $arg2
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 49489
diff changeset
205 p $foo->contents[$arg1-($i++)]
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
206 pr
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
207 end
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
208 document xvector-elts
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
209 Prints a range of elements of a Lisp vector.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
210 xvector-elts v n i
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
211 prints `i' elements of the vector `v' ending at the index `n'.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
212 end
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
213
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
214 ** Getting Lisp-level backtrace information within GDB
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
215
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
216 The most convenient way is to use the `xbacktrace' command. This
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
217 shows the names of the Lisp functions that are currently active.
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
218
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
219 If that doesn't work (e.g., because the `backtrace_list' structure is
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
220 corrupted), type "bt" at the GDB prompt, to produce the C-level
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
221 backtrace, and look for stack frames that call Ffuncall. Select them
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
222 one by one in GDB, by typing "up N", where N is the appropriate number
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
223 of frames to go up, and in each frame that calls Ffuncall type this:
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
224
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
225 p *args
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
226 pr
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
227
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
228 This will print the name of the Lisp function called by that level
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
229 of function calling.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
230
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
231 By printing the remaining elements of args, you can see the argument
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
232 values. Here's how to print the first argument:
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 49489
diff changeset
233
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
234 p args[1]
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
235 pr
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
236
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
237 If you do not have a live process, you can use xtype and the other
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
238 x... commands such as xsymbol to get such information, albeit less
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
239 conveniently. For example:
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
240
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
241 p *args
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
242 xtype
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
243
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
244 and, assuming that "xtype" says that args[0] is a symbol:
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
245
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 49489
diff changeset
246 xsymbol
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
247
71445
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
248 ** Debugging Emacs Redisplay problems
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
249
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
250 The src/.gdbinit file defines many useful commands for dumping redisplay
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
251 related data structures in a terse and user-friendly format:
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
252
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
253 `ppt' prints value of PT, narrowing, and gap in current buffer.
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
254 `pit' dumps the current display iterator `it'.
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
255 `pwin' dumps the current window 'win'.
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
256 `prow' dumps the current glyph_row `row'.
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
257 `pg' dumps the current glyph `glyph'.
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
258 `pgi' dumps the next glyph.
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
259 `pgrow' dumps all glyphs in current glyph_row `row'.
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
260 `pcursor' dumps current output_cursor.
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
261
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
262 The above commands also exist in a version with an `x' suffix which
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
263 takes an object of the relevant type as argument.
241a58942caf Mention `pv variable' to print value of Lisp variables.
Kim F. Storm <storm@cua.dk>
parents: 69558
diff changeset
264
72293
2fef1488c1d0 (Note): Add note about ollowing a longjmp call.
Nick Roberts <nickrob@snap.net.nz>
parents: 71448
diff changeset
265 ** Following longjmp call.
2fef1488c1d0 (Note): Add note about ollowing a longjmp call.
Nick Roberts <nickrob@snap.net.nz>
parents: 71448
diff changeset
266
2fef1488c1d0 (Note): Add note about ollowing a longjmp call.
Nick Roberts <nickrob@snap.net.nz>
parents: 71448
diff changeset
267 Recent versions of glibc (2.4+?) encrypt stored values for setjmp/longjmp which
2fef1488c1d0 (Note): Add note about ollowing a longjmp call.
Nick Roberts <nickrob@snap.net.nz>
parents: 71448
diff changeset
268 prevents GDB from being able to follow a longjmp call using `next'. To
2fef1488c1d0 (Note): Add note about ollowing a longjmp call.
Nick Roberts <nickrob@snap.net.nz>
parents: 71448
diff changeset
269 disable this protection you need to set the environment variable
2fef1488c1d0 (Note): Add note about ollowing a longjmp call.
Nick Roberts <nickrob@snap.net.nz>
parents: 71448
diff changeset
270 LD_POINTER_GUARD to 0.
2fef1488c1d0 (Note): Add note about ollowing a longjmp call.
Nick Roberts <nickrob@snap.net.nz>
parents: 71448
diff changeset
271
69477
4a8aa0c1f128 (Note): Describe features for debugging with GDB in Emacs.
Nick Roberts <nickrob@snap.net.nz>
parents: 68640
diff changeset
272 ** Using GDB in Emacs
4a8aa0c1f128 (Note): Describe features for debugging with GDB in Emacs.
Nick Roberts <nickrob@snap.net.nz>
parents: 68640
diff changeset
273
4a8aa0c1f128 (Note): Describe features for debugging with GDB in Emacs.
Nick Roberts <nickrob@snap.net.nz>
parents: 68640
diff changeset
274 Debugging with GDB in Emacs offers some advantages over the command line (See
4a8aa0c1f128 (Note): Describe features for debugging with GDB in Emacs.
Nick Roberts <nickrob@snap.net.nz>
parents: 68640
diff changeset
275 the GDB Graphical Interface node of the Emacs manual). There are also some
4a8aa0c1f128 (Note): Describe features for debugging with GDB in Emacs.
Nick Roberts <nickrob@snap.net.nz>
parents: 68640
diff changeset
276 features available just for debugging Emacs:
4a8aa0c1f128 (Note): Describe features for debugging with GDB in Emacs.
Nick Roberts <nickrob@snap.net.nz>
parents: 68640
diff changeset
277
71448
8c249825e7f3 Add reference to description of .gdbinit commands.
Eli Zaretskii <eliz@gnu.org>
parents: 71445
diff changeset
278 1) The command gud-pp is available on the tool bar (the `pp' icon) and
8c249825e7f3 Add reference to description of .gdbinit commands.
Eli Zaretskii <eliz@gnu.org>
parents: 71445
diff changeset
279 allows the user to print the s-expression of the variable at point,
8c249825e7f3 Add reference to description of .gdbinit commands.
Eli Zaretskii <eliz@gnu.org>
parents: 71445
diff changeset
280 in the GUD buffer.
69477
4a8aa0c1f128 (Note): Describe features for debugging with GDB in Emacs.
Nick Roberts <nickrob@snap.net.nz>
parents: 68640
diff changeset
281
4a8aa0c1f128 (Note): Describe features for debugging with GDB in Emacs.
Nick Roberts <nickrob@snap.net.nz>
parents: 68640
diff changeset
282 2) Pressing `p' on a component of a watch expression that is a lisp object
4a8aa0c1f128 (Note): Describe features for debugging with GDB in Emacs.
Nick Roberts <nickrob@snap.net.nz>
parents: 68640
diff changeset
283 in the speedbar prints its s-expression in the GUD buffer.
4a8aa0c1f128 (Note): Describe features for debugging with GDB in Emacs.
Nick Roberts <nickrob@snap.net.nz>
parents: 68640
diff changeset
284
4a8aa0c1f128 (Note): Describe features for debugging with GDB in Emacs.
Nick Roberts <nickrob@snap.net.nz>
parents: 68640
diff changeset
285 3) The STOP button on the tool bar is adjusted so that it sends SIGTSTP
4a8aa0c1f128 (Note): Describe features for debugging with GDB in Emacs.
Nick Roberts <nickrob@snap.net.nz>
parents: 68640
diff changeset
286 instead of the usual SIGINT.
4a8aa0c1f128 (Note): Describe features for debugging with GDB in Emacs.
Nick Roberts <nickrob@snap.net.nz>
parents: 68640
diff changeset
287
4a8aa0c1f128 (Note): Describe features for debugging with GDB in Emacs.
Nick Roberts <nickrob@snap.net.nz>
parents: 68640
diff changeset
288 4) The command gud-pv has the global binding 'C-x C-a C-v' and prints the
4a8aa0c1f128 (Note): Describe features for debugging with GDB in Emacs.
Nick Roberts <nickrob@snap.net.nz>
parents: 68640
diff changeset
289 value of the lisp variable at point.
4a8aa0c1f128 (Note): Describe features for debugging with GDB in Emacs.
Nick Roberts <nickrob@snap.net.nz>
parents: 68640
diff changeset
290
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
291 ** Debugging what happens while preloading and dumping Emacs
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
292
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
293 Type `gdb temacs' and start it with `r -batch -l loadup dump'.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
294
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
295 If temacs actually succeeds when running under GDB in this way, do not
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
296 try to run the dumped Emacs, because it was dumped with the GDB
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
297 breakpoints in it.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
298
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
299 ** Debugging `temacs'
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
300
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
301 Debugging `temacs' is useful when you want to establish whether a
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
302 problem happens in an undumped Emacs. To run `temacs' under a
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
303 debugger, type "gdb temacs", then start it with `r -batch -l loadup'.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
304
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
305 ** If you encounter X protocol errors
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
306
76739
e4f81c51941e Explain reason for X protocol error recommendations.
Richard M. Stallman <rms@gnu.org>
parents: 75774
diff changeset
307 The X server normally reports protocol errors asynchronously,
e4f81c51941e Explain reason for X protocol error recommendations.
Richard M. Stallman <rms@gnu.org>
parents: 75774
diff changeset
308 so you find out about them long after the primitive which caused
e4f81c51941e Explain reason for X protocol error recommendations.
Richard M. Stallman <rms@gnu.org>
parents: 75774
diff changeset
309 the error has returned.
e4f81c51941e Explain reason for X protocol error recommendations.
Richard M. Stallman <rms@gnu.org>
parents: 75774
diff changeset
310
e4f81c51941e Explain reason for X protocol error recommendations.
Richard M. Stallman <rms@gnu.org>
parents: 75774
diff changeset
311 To get clear information about the cause of an error, try evaluating
e4f81c51941e Explain reason for X protocol error recommendations.
Richard M. Stallman <rms@gnu.org>
parents: 75774
diff changeset
312 (x-synchronize t). That puts Emacs into synchronous mode, where each
e4f81c51941e Explain reason for X protocol error recommendations.
Richard M. Stallman <rms@gnu.org>
parents: 75774
diff changeset
313 Xlib call checks for errors before it returns. This mode is much
e4f81c51941e Explain reason for X protocol error recommendations.
Richard M. Stallman <rms@gnu.org>
parents: 75774
diff changeset
314 slower, but when you get an error, you will see exactly which call
e4f81c51941e Explain reason for X protocol error recommendations.
Richard M. Stallman <rms@gnu.org>
parents: 75774
diff changeset
315 really caused the error.
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
316
36962
9c7eb7e6bf3e Document the use of -xrm to start EMacs in synchronous mode.
Eli Zaretskii <eliz@gnu.org>
parents: 36625
diff changeset
317 You can start Emacs in a synchronous mode by invoking it with the -xrm
9c7eb7e6bf3e Document the use of -xrm to start EMacs in synchronous mode.
Eli Zaretskii <eliz@gnu.org>
parents: 36625
diff changeset
318 option, like this:
9c7eb7e6bf3e Document the use of -xrm to start EMacs in synchronous mode.
Eli Zaretskii <eliz@gnu.org>
parents: 36625
diff changeset
319
37534
3ea5075dc420 Fix a typo in the "emacs -xrm" command line. Reported by Kenichi Handa.
Eli Zaretskii <eliz@gnu.org>
parents: 37509
diff changeset
320 emacs -xrm "emacs.synchronous: true"
36962
9c7eb7e6bf3e Document the use of -xrm to start EMacs in synchronous mode.
Eli Zaretskii <eliz@gnu.org>
parents: 36625
diff changeset
321
9c7eb7e6bf3e Document the use of -xrm to start EMacs in synchronous mode.
Eli Zaretskii <eliz@gnu.org>
parents: 36625
diff changeset
322 Setting a breakpoint in the function `x_error_quitter' and looking at
9c7eb7e6bf3e Document the use of -xrm to start EMacs in synchronous mode.
Eli Zaretskii <eliz@gnu.org>
parents: 36625
diff changeset
323 the backtrace when Emacs stops inside that function will show what
9c7eb7e6bf3e Document the use of -xrm to start EMacs in synchronous mode.
Eli Zaretskii <eliz@gnu.org>
parents: 36625
diff changeset
324 code causes the X protocol errors.
9c7eb7e6bf3e Document the use of -xrm to start EMacs in synchronous mode.
Eli Zaretskii <eliz@gnu.org>
parents: 36625
diff changeset
325
41839
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
326 Some bugs related to the X protocol disappear when Emacs runs in a
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
327 synchronous mode. To track down those bugs, we suggest the following
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
328 procedure:
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
329
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
330 - Run Emacs under a debugger and put a breakpoint inside the
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
331 primitive function which, when called from Lisp, triggers the X
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
332 protocol errors. For example, if the errors happen when you
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
333 delete a frame, put a breakpoint inside `Fdelete_frame'.
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
334
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
335 - When the breakpoint breaks, step through the code, looking for
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
336 calls to X functions (the ones whose names begin with "X" or
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
337 "Xt" or "Xm").
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
338
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
339 - Insert calls to `XSync' before and after each call to the X
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
340 functions, like this:
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
341
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
342 XSync (f->output_data.x->display_info->display, 0);
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
343
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
344 where `f' is the pointer to the `struct frame' of the selected
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
345 frame, normally available via XFRAME (selected_frame). (Most
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
346 functions which call X already have some variable that holds the
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
347 pointer to the frame, perhaps called `f' or `sf', so you shouldn't
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
348 need to compute it.)
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
349
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
350 If your debugger can call functions in the program being debugged,
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
351 you should be able to issue the calls to `XSync' without recompiling
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
352 Emacs. For example, with GDB, just type:
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
353
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
354 call XSync (f->output_data.x->display_info->display, 0)
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
355
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
356 before and immediately after the suspect X calls. If your
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
357 debugger does not support this, you will need to add these pairs
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
358 of calls in the source and rebuild Emacs.
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
359
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
360 Either way, systematically step through the code and issue these
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
361 calls until you find the first X function called by Emacs after
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
362 which a call to `XSync' winds up in the function
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
363 `x_error_quitter'. The first X function call for which this
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
364 happens is the one that generated the X protocol error.
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
365
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
366 - You should now look around this offending X call and try to figure
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
367 out what is wrong with it.
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
368
49489
e0ff22ddc744 Added note about xmon.
Jan Djärv <jan.h.d@swipnet.se>
parents: 44813
diff changeset
369 ** If Emacs causes errors or memory leaks in your X server
e0ff22ddc744 Added note about xmon.
Jan Djärv <jan.h.d@swipnet.se>
parents: 44813
diff changeset
370
e0ff22ddc744 Added note about xmon.
Jan Djärv <jan.h.d@swipnet.se>
parents: 44813
diff changeset
371 You can trace the traffic between Emacs and your X server with a tool
e0ff22ddc744 Added note about xmon.
Jan Djärv <jan.h.d@swipnet.se>
parents: 44813
diff changeset
372 like xmon, available at ftp://ftp.x.org/contrib/devel_tools/.
e0ff22ddc744 Added note about xmon.
Jan Djärv <jan.h.d@swipnet.se>
parents: 44813
diff changeset
373
e0ff22ddc744 Added note about xmon.
Jan Djärv <jan.h.d@swipnet.se>
parents: 44813
diff changeset
374 Xmon can be used to see exactly what Emacs sends when X protocol errors
e0ff22ddc744 Added note about xmon.
Jan Djärv <jan.h.d@swipnet.se>
parents: 44813
diff changeset
375 happen. If Emacs causes the X server memory usage to increase you can
e0ff22ddc744 Added note about xmon.
Jan Djärv <jan.h.d@swipnet.se>
parents: 44813
diff changeset
376 use xmon to see what items Emacs creates in the server (windows,
e0ff22ddc744 Added note about xmon.
Jan Djärv <jan.h.d@swipnet.se>
parents: 44813
diff changeset
377 graphical contexts, pixmaps) and what items Emacs delete. If there
e0ff22ddc744 Added note about xmon.
Jan Djärv <jan.h.d@swipnet.se>
parents: 44813
diff changeset
378 are consistently more creations than deletions, the type of item
e0ff22ddc744 Added note about xmon.
Jan Djärv <jan.h.d@swipnet.se>
parents: 44813
diff changeset
379 and the activity you do when the items get created can give a hint where
e0ff22ddc744 Added note about xmon.
Jan Djärv <jan.h.d@swipnet.se>
parents: 44813
diff changeset
380 to start debugging.
e0ff22ddc744 Added note about xmon.
Jan Djärv <jan.h.d@swipnet.se>
parents: 44813
diff changeset
381
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
382 ** If the symptom of the bug is that Emacs fails to respond
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
383
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
384 Don't assume Emacs is `hung'--it may instead be in an infinite loop.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
385 To find out which, make the problem happen under GDB and stop Emacs
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
386 once it is not responding. (If Emacs is using X Windows directly, you
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
387 can stop Emacs by typing C-z at the GDB job.) Then try stepping with
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
388 `step'. If Emacs is hung, the `step' command won't return. If it is
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
389 looping, `step' will return.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
390
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
391 If this shows Emacs is hung in a system call, stop it again and
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
392 examine the arguments of the call. If you report the bug, it is very
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
393 important to state exactly where in the source the system call is, and
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
394 what the arguments are.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
395
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
396 If Emacs is in an infinite loop, try to determine where the loop
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
397 starts and ends. The easiest way to do this is to use the GDB command
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
398 `finish'. Each time you use it, Emacs resumes execution until it
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
399 exits one stack frame. Keep typing `finish' until it doesn't
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
400 return--that means the infinite loop is in the stack frame which you
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
401 just tried to finish.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
402
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
403 Stop Emacs again, and use `finish' repeatedly again until you get back
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
404 to that frame. Then use `next' to step through that frame. By
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
405 stepping, you will see where the loop starts and ends. Also, examine
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
406 the data being used in the loop and try to determine why the loop does
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
407 not exit when it should.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
408
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
409 ** If certain operations in Emacs are slower than they used to be, here
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
410 is some advice for how to find out why.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
411
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
412 Stop Emacs repeatedly during the slow operation, and make a backtrace
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
413 each time. Compare the backtraces looking for a pattern--a specific
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
414 function that shows up more often than you'd expect.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
415
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
416 If you don't see a pattern in the C backtraces, get some Lisp
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
417 backtrace information by typing "xbacktrace" or by looking at Ffuncall
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
418 frames (see above), and again look for a pattern.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
419
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
420 When using X, you can stop Emacs at any time by typing C-z at GDB.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
421 When not using X, you can do this with C-g. On non-Unix platforms,
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
422 such as MS-DOS, you might need to press C-BREAK instead.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
423
25853
Dave Love <fx@gnu.org>
parents:
diff changeset
424 ** If GDB does not run and your debuggers can't load Emacs.
Dave Love <fx@gnu.org>
parents:
diff changeset
425
Dave Love <fx@gnu.org>
parents:
diff changeset
426 On some systems, no debugger can load Emacs with a symbol table,
Dave Love <fx@gnu.org>
parents:
diff changeset
427 perhaps because they all have fixed limits on the number of symbols
Dave Love <fx@gnu.org>
parents:
diff changeset
428 and Emacs exceeds the limits. Here is a method that can be used
Dave Love <fx@gnu.org>
parents:
diff changeset
429 in such an extremity. Do
Dave Love <fx@gnu.org>
parents:
diff changeset
430
Dave Love <fx@gnu.org>
parents:
diff changeset
431 nm -n temacs > nmout
Dave Love <fx@gnu.org>
parents:
diff changeset
432 strip temacs
Dave Love <fx@gnu.org>
parents:
diff changeset
433 adb temacs
Dave Love <fx@gnu.org>
parents:
diff changeset
434 0xd:i
Dave Love <fx@gnu.org>
parents:
diff changeset
435 0xe:i
Dave Love <fx@gnu.org>
parents:
diff changeset
436 14:i
Dave Love <fx@gnu.org>
parents:
diff changeset
437 17:i
Dave Love <fx@gnu.org>
parents:
diff changeset
438 :r -l loadup (or whatever)
Dave Love <fx@gnu.org>
parents:
diff changeset
439
Dave Love <fx@gnu.org>
parents:
diff changeset
440 It is necessary to refer to the file `nmout' to convert
Dave Love <fx@gnu.org>
parents:
diff changeset
441 numeric addresses into symbols and vice versa.
Dave Love <fx@gnu.org>
parents:
diff changeset
442
Dave Love <fx@gnu.org>
parents:
diff changeset
443 It is useful to be running under a window system.
109073
6799ec1a7188 Remove some cpp that is internal to configure.in.
Glenn Morris <rgm@gnu.org>
parents: 108619
diff changeset
444 Then, if Emacs becomes hopelessly wedged, you can create another
6799ec1a7188 Remove some cpp that is internal to configure.in.
Glenn Morris <rgm@gnu.org>
parents: 108619
diff changeset
445 window to do kill -9 in. kill -ILL is often useful too, since that
6799ec1a7188 Remove some cpp that is internal to configure.in.
Glenn Morris <rgm@gnu.org>
parents: 108619
diff changeset
446 may make Emacs dump core or return to adb.
25853
Dave Love <fx@gnu.org>
parents:
diff changeset
447
Dave Love <fx@gnu.org>
parents:
diff changeset
448
Dave Love <fx@gnu.org>
parents:
diff changeset
449 ** Debugging incorrect screen updating.
Dave Love <fx@gnu.org>
parents:
diff changeset
450
Dave Love <fx@gnu.org>
parents:
diff changeset
451 To debug Emacs problems that update the screen wrong, it is useful
Dave Love <fx@gnu.org>
parents:
diff changeset
452 to have a record of what input you typed and what Emacs sent to the
Dave Love <fx@gnu.org>
parents:
diff changeset
453 screen. To make these records, do
Dave Love <fx@gnu.org>
parents:
diff changeset
454
Dave Love <fx@gnu.org>
parents:
diff changeset
455 (open-dribble-file "~/.dribble")
Dave Love <fx@gnu.org>
parents:
diff changeset
456 (open-termscript "~/.termscript")
Dave Love <fx@gnu.org>
parents:
diff changeset
457
Dave Love <fx@gnu.org>
parents:
diff changeset
458 The dribble file contains all characters read by Emacs from the
Dave Love <fx@gnu.org>
parents:
diff changeset
459 terminal, and the termscript file contains all characters it sent to
Dave Love <fx@gnu.org>
parents:
diff changeset
460 the terminal. The use of the directory `~/' prevents interference
Dave Love <fx@gnu.org>
parents:
diff changeset
461 with any other user.
Dave Love <fx@gnu.org>
parents:
diff changeset
462
Dave Love <fx@gnu.org>
parents:
diff changeset
463 If you have irreproducible display problems, put those two expressions
Dave Love <fx@gnu.org>
parents:
diff changeset
464 in your ~/.emacs file. When the problem happens, exit the Emacs that
Dave Love <fx@gnu.org>
parents:
diff changeset
465 you were running, kill it, and rename the two files. Then you can start
Dave Love <fx@gnu.org>
parents:
diff changeset
466 another Emacs without clobbering those files, and use it to examine them.
34594
9b989029cccf Add note aboute using `inverse-video' to detect excessive screen redraw.
Miles Bader <miles@gnu.org>
parents: 32523
diff changeset
467
9b989029cccf Add note aboute using `inverse-video' to detect excessive screen redraw.
Miles Bader <miles@gnu.org>
parents: 32523
diff changeset
468 An easy way to see if too much text is being redrawn on a terminal is to
9b989029cccf Add note aboute using `inverse-video' to detect excessive screen redraw.
Miles Bader <miles@gnu.org>
parents: 32523
diff changeset
469 evaluate `(setq inverse-video t)' before you try the operation you think
9b989029cccf Add note aboute using `inverse-video' to detect excessive screen redraw.
Miles Bader <miles@gnu.org>
parents: 32523
diff changeset
470 will cause too much redrawing. This doesn't refresh the screen, so only
9b989029cccf Add note aboute using `inverse-video' to detect excessive screen redraw.
Miles Bader <miles@gnu.org>
parents: 32523
diff changeset
471 newly drawn text is in inverse video.
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
472
37509
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
473 The Emacs display code includes special debugging code, but it is
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
474 normally disabled. You can enable it by building Emacs with the
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
475 pre-processing symbol GLYPH_DEBUG defined. Here's one easy way,
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
476 suitable for Unix and GNU systems, to build such a debugging version:
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
477
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
478 MYCPPFLAGS='-DGLYPH_DEBUG=1' make
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
479
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
480 Building Emacs like that activates many assertions which scrutinize
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
481 display code operation more than Emacs does normally. (To see the
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
482 code which tests these assertions, look for calls to the `xassert'
109073
6799ec1a7188 Remove some cpp that is internal to configure.in.
Glenn Morris <rgm@gnu.org>
parents: 108619
diff changeset
483 macros.) Any assertion that is reported to fail should be investigated.
37509
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
484
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
485 Building with GLYPH_DEBUG defined also defines several helper
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
486 functions which can help debugging display code. One such function is
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
487 `dump_glyph_matrix'. If you run Emacs under GDB, you can print the
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
488 contents of any glyph matrix by just calling that function with the
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
489 matrix as its argument. For example, the following command will print
109073
6799ec1a7188 Remove some cpp that is internal to configure.in.
Glenn Morris <rgm@gnu.org>
parents: 108619
diff changeset
490 the contents of the current matrix of the window whose pointer is in `w':
37509
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
491
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
492 (gdb) p dump_glyph_matrix (w->current_matrix, 2)
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
493
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
494 (The second argument 2 tells dump_glyph_matrix to print the glyphs in
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
495 a long form.) You can dump the selected window's current glyph matrix
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
496 interactively with "M-x dump-glyph-matrix RET"; see the documentation
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
497 of this function for more details.
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
498
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
499 Several more functions for debugging display code are available in
37565
77f4666fdd04 Fix last change.
Eli Zaretskii <eliz@gnu.org>
parents: 37534
diff changeset
500 Emacs compiled with GLYPH_DEBUG defined; type "C-h f dump- TAB" and
77f4666fdd04 Fix last change.
Eli Zaretskii <eliz@gnu.org>
parents: 37534
diff changeset
501 "C-h f trace- TAB" to see the full list.
37509
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
502
57307
7e6072c66e67 Mention pp and ff commands.
Kim F. Storm <storm@cua.dk>
parents: 52401
diff changeset
503 When you debug display problems running emacs under X, you can use
7e6072c66e67 Mention pp and ff commands.
Kim F. Storm <storm@cua.dk>
parents: 52401
diff changeset
504 the `ff' command to flush all pending display updates to the screen.
7e6072c66e67 Mention pp and ff commands.
Kim F. Storm <storm@cua.dk>
parents: 52401
diff changeset
505
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
506
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
507 ** Debugging LessTif
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
508
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
509 If you encounter bugs whereby Emacs built with LessTif grabs all mouse
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
510 and keyboard events, or LessTif menus behave weirdly, it might be
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
511 helpful to set the `DEBUGSOURCES' and `DEBUG_FILE' environment
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
512 variables, so that one can see what LessTif was doing at this point.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
513 For instance
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 49489
diff changeset
514
36625
08aed53e171c DEBUGSOURCES should contain a list of files, separated by colons.
Gerd Moellmann <gerd@gnu.org>
parents: 35861
diff changeset
515 export DEBUGSOURCES="RowColumn.c:MenuShell.c:MenuUtil.c"
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
516 export DEBUG_FILE=/usr/tmp/LESSTIF_TRACE
35720
c6ae90d82552 Clarify the instructions for debugging LessTif.
Eli Zaretskii <eliz@gnu.org>
parents: 35655
diff changeset
517 emacs &
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
518
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
519 causes LessTif to print traces from the three named source files to a
35720
c6ae90d82552 Clarify the instructions for debugging LessTif.
Eli Zaretskii <eliz@gnu.org>
parents: 35655
diff changeset
520 file in `/usr/tmp' (that file can get pretty large). The above should
c6ae90d82552 Clarify the instructions for debugging LessTif.
Eli Zaretskii <eliz@gnu.org>
parents: 35655
diff changeset
521 be typed at the shell prompt before invoking Emacs, as shown by the
c6ae90d82552 Clarify the instructions for debugging LessTif.
Eli Zaretskii <eliz@gnu.org>
parents: 35655
diff changeset
522 last line above.
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
523
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
524 Running GDB from another terminal could also help with such problems.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
525 You can arrange for GDB to run on one machine, with the Emacs display
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
526 appearing on another. Then, when the bug happens, you can go back to
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
527 the machine where you started GDB and use the debugger from there.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
528
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
529
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
530 ** Debugging problems which happen in GC
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
531
37015
f8dd0e40dc34 Make it clear that last_marked[] holds pointers to Lisp objects, not
Eli Zaretskii <eliz@gnu.org>
parents: 36962
diff changeset
532 The array `last_marked' (defined on alloc.c) can be used to display up
f8dd0e40dc34 Make it clear that last_marked[] holds pointers to Lisp objects, not
Eli Zaretskii <eliz@gnu.org>
parents: 36962
diff changeset
533 to 500 last objects marked by the garbage collection process.
37076
ec5579aad1bb Fix the wording in the last change.
Eli Zaretskii <eliz@gnu.org>
parents: 37015
diff changeset
534 Whenever the garbage collector marks a Lisp object, it records the
69558
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
535 pointer to that object in the `last_marked' array, which is maintained
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
536 as a circular buffer. The variable `last_marked_index' holds the
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
537 index into the `last_marked' array one place beyond where the pointer
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
538 to the very last marked object is stored.
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
539
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
540 The single most important goal in debugging GC problems is to find the
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
541 Lisp data structure that got corrupted. This is not easy since GC
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
542 changes the tag bits and relocates strings which make it hard to look
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
543 at Lisp objects with commands such as `pr'. It is sometimes necessary
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
544 to convert Lisp_Object variables into pointers to C struct's manually.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
545
69558
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
546 Use the `last_marked' array and the source to reconstruct the sequence
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
547 that objects were marked. In general, you need to correlate the
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
548 values recorded in the `last_marked' array with the corresponding
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
549 stack frames in the backtrace, beginning with the innermost frame.
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
550 Some subroutines of `mark_object' are invoked recursively, others loop
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
551 over portions of the data structure and mark them as they go. By
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
552 looking at the code of those routines and comparing the frames in the
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
553 backtrace with the values in `last_marked', you will be able to find
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
554 connections between the values in `last_marked'. E.g., when GC finds
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
555 a cons cell, it recursively marks its car and its cdr. Similar things
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
556 happen with properties of symbols, elements of vectors, etc. Use
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
557 these connections to reconstruct the data structure that was being
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
558 marked, paying special attention to the strings and names of symbols
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
559 that you encounter: these strings and symbol names can be used to grep
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
560 the sources to find out what high-level symbols and global variables
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
561 are involved in the crash.
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
562
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
563 Once you discover the corrupted Lisp object or data structure, grep
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
564 the sources for its uses and try to figure out what could cause the
77156
563a04f93ea0 Fix typos.
Glenn Morris <rgm@gnu.org>
parents: 76739
diff changeset
565 corruption. If looking at the sources doesn't help, you could try
69558
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
566 setting a watchpoint on the corrupted data, and see what code modifies
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
567 it in some invalid way. (Obviously, this technique is only useful for
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
568 data that is modified only very rarely.)
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
569
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
570 It is also useful to look at the corrupted object or data structure in
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
571 a fresh Emacs session and compare its contents with a session that you
aed02e3a8c0f Elaborate on debugging GC crashes.
Eli Zaretskii <eliz@gnu.org>
parents: 69477
diff changeset
572 are debugging.
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
573
37481
7121f840504e Document byte-debug-flag.
Eli Zaretskii <eliz@gnu.org>
parents: 37333
diff changeset
574 ** Debugging problems with non-ASCII characters
7121f840504e Document byte-debug-flag.
Eli Zaretskii <eliz@gnu.org>
parents: 37333
diff changeset
575
7121f840504e Document byte-debug-flag.
Eli Zaretskii <eliz@gnu.org>
parents: 37333
diff changeset
576 If you experience problems which seem to be related to non-ASCII
7121f840504e Document byte-debug-flag.
Eli Zaretskii <eliz@gnu.org>
parents: 37333
diff changeset
577 characters, such as \201 characters appearing in the buffer or in your
7121f840504e Document byte-debug-flag.
Eli Zaretskii <eliz@gnu.org>
parents: 37333
diff changeset
578 files, set the variable byte-debug-flag to t. This causes Emacs to do
7121f840504e Document byte-debug-flag.
Eli Zaretskii <eliz@gnu.org>
parents: 37333
diff changeset
579 some extra checks, such as look for broken relations between byte and
7121f840504e Document byte-debug-flag.
Eli Zaretskii <eliz@gnu.org>
parents: 37333
diff changeset
580 character positions in buffers and strings; the resulting diagnostics
7121f840504e Document byte-debug-flag.
Eli Zaretskii <eliz@gnu.org>
parents: 37333
diff changeset
581 might pinpoint the cause of the problem.
7121f840504e Document byte-debug-flag.
Eli Zaretskii <eliz@gnu.org>
parents: 37333
diff changeset
582
40247
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
583 ** Debugging the TTY (non-windowed) version
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
584
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
585 The most convenient method of debugging the character-terminal display
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
586 is to do that on a window system such as X. Begin by starting an
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
587 xterm window, then type these commands inside that window:
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
588
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
589 $ tty
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
590 $ echo $TERM
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
591
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
592 Let's say these commands print "/dev/ttyp4" and "xterm", respectively.
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
593
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
594 Now start Emacs (the normal, windowed-display session, i.e. without
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
595 the `-nw' option), and invoke "M-x gdb RET emacs RET" from there. Now
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
596 type these commands at GDB's prompt:
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
597
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
598 (gdb) set args -nw -t /dev/ttyp4
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
599 (gdb) set environment TERM xterm
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
600 (gdb) run
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
601
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
602 The debugged Emacs should now start in no-window mode with its display
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
603 directed to the xterm window you opened above.
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
604
40348
380d8f312f3a Mention that screen(1) can come in handy for debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 40247
diff changeset
605 Similar arrangement is possible on a character terminal by using the
380d8f312f3a Mention that screen(1) can come in handy for debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 40247
diff changeset
606 `screen' package.
380d8f312f3a Mention that screen(1) can come in handy for debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 40247
diff changeset
607
37586
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
608 ** Running Emacs built with malloc debugging packages
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
609
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
610 If Emacs exhibits bugs that seem to be related to use of memory
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
611 allocated off the heap, it might be useful to link Emacs with a
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
612 special debugging library, such as Electric Fence (a.k.a. efence) or
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
613 GNU Checker, which helps find such problems.
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
614
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
615 Emacs compiled with such packages might not run without some hacking,
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
616 because Emacs replaces the system's memory allocation functions with
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
617 its own versions, and because the dumping process might be
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
618 incompatible with the way these packages use to track allocated
109073
6799ec1a7188 Remove some cpp that is internal to configure.in.
Glenn Morris <rgm@gnu.org>
parents: 108619
diff changeset
619 memory. Here are some of the changes you might find necessary:
37586
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
620
109073
6799ec1a7188 Remove some cpp that is internal to configure.in.
Glenn Morris <rgm@gnu.org>
parents: 108619
diff changeset
621 - Edit configure, to set system_malloc and CANNOT_DUMP to "yes".
37586
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
622
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
623 - Configure with a different --prefix= option. If you use GCC,
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
624 version 2.7.2 is preferred, as some malloc debugging packages
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
625 work a lot better with it than with 2.95 or later versions.
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
626
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
627 - Type "make" then "make -k install".
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
628
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
629 - If required, invoke the package-specific command to prepare
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
630 src/temacs for execution.
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
631
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
632 - cd ..; src/temacs
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
633
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
634 (Note that this runs `temacs' instead of the usual `emacs' executable.
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
635 This avoids problems with dumping Emacs mentioned above.)
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
636
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
637 Some malloc debugging libraries might print lots of false alarms for
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
638 bitfields used by Emacs in some data structures. If you want to get
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
639 rid of the false alarms, you will have to hack the definitions of
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
640 these data structures on the respective headers to remove the `:N'
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
641 bitfield definitions (which will cause each such field to use a full
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
642 int).
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
643
63310
58942e3c1b56 Mention emacs-buffer.gdb.
Eli Zaretskii <eliz@gnu.org>
parents: 60334
diff changeset
644 ** How to recover buffer contents from an Emacs core dump file
58942e3c1b56 Mention emacs-buffer.gdb.
Eli Zaretskii <eliz@gnu.org>
parents: 60334
diff changeset
645
58942e3c1b56 Mention emacs-buffer.gdb.
Eli Zaretskii <eliz@gnu.org>
parents: 60334
diff changeset
646 The file etc/emacs-buffer.gdb defines a set of GDB commands for
58942e3c1b56 Mention emacs-buffer.gdb.
Eli Zaretskii <eliz@gnu.org>
parents: 60334
diff changeset
647 recovering the contents of Emacs buffers from a core dump file. You
58942e3c1b56 Mention emacs-buffer.gdb.
Eli Zaretskii <eliz@gnu.org>
parents: 60334
diff changeset
648 might also find those commands useful for displaying the list of
58942e3c1b56 Mention emacs-buffer.gdb.
Eli Zaretskii <eliz@gnu.org>
parents: 60334
diff changeset
649 buffers in human-readable format from within the debugger.
58942e3c1b56 Mention emacs-buffer.gdb.
Eli Zaretskii <eliz@gnu.org>
parents: 60334
diff changeset
650
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
651 ** Some suggestions for debugging on MS Windows:
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
652
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
653 (written by Marc Fleischeuers, Geoff Voelker and Andrew Innes)
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
654
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
655 To debug Emacs with Microsoft Visual C++, you either start emacs from
37333
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
656 the debugger or attach the debugger to a running emacs process.
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
657
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
658 To start emacs from the debugger, you can use the file bin/debug.bat.
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
659 The Microsoft Developer studio will start and under Project, Settings,
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
660 Debug, General you can set the command-line arguments and Emacs's
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
661 startup directory. Set breakpoints (Edit, Breakpoints) at Fsignal and
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
662 other functions that you want to examine. Run the program (Build,
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
663 Start debug). Emacs will start and the debugger will take control as
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
664 soon as a breakpoint is hit.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
665
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
666 You can also attach the debugger to an already running Emacs process.
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
667 To do this, start up the Microsoft Developer studio and select Build,
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
668 Start debug, Attach to process. Choose the Emacs process from the
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
669 list. Send a break to the running process (Debug, Break) and you will
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
670 find that execution is halted somewhere in user32.dll. Open the stack
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
671 trace window and go up the stack to w32_msg_pump. Now you can set
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
672 breakpoints in Emacs (Edit, Breakpoints). Continue the running Emacs
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
673 process (Debug, Step out) and control will return to Emacs, until a
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
674 breakpoint is hit.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
675
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
676 To examine the contents of a Lisp variable, you can use the function
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
677 'debug_print'. Right-click on a variable, select QuickWatch (it has
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
678 an eyeglass symbol on its button in the toolbar), and in the text
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
679 field at the top of the window, place 'debug_print(' and ')' around
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
680 the expression. Press 'Recalculate' and the output is sent to stderr,
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
681 and to the debugger via the OutputDebugString routine. The output
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
682 sent to stderr should be displayed in the console window that was
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
683 opened when the emacs.exe executable was started. The output sent to
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
684 the debugger should be displayed in the 'Debug' pane in the Output
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
685 window. If Emacs was started from the debugger, a console window was
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
686 opened at Emacs' startup; this console window also shows the output of
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
687 'debug_print'.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
688
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
689 For example, start and run Emacs in the debugger until it is waiting
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
690 for user input. Then click on the `Break' button in the debugger to
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
691 halt execution. Emacs should halt in `ZwUserGetMessage' waiting for
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
692 an input event. Use the `Call Stack' window to select the procedure
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
693 `w32_msp_pump' up the call stack (see below for why you have to do
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
694 this). Open the QuickWatch window and enter
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
695 "debug_print(Vexec_path)". Evaluating this expression will then print
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
696 out the contents of the Lisp variable `exec-path'.
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
697
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
698 If QuickWatch reports that the symbol is unknown, then check the call
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
699 stack in the `Call Stack' window. If the selected frame in the call
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
700 stack is not an Emacs procedure, then the debugger won't recognize
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
701 Emacs symbols. Instead, select a frame that is inside an Emacs
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
702 procedure and try using `debug_print' again.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
703
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
704 If QuickWatch invokes debug_print but nothing happens, then check the
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
705 thread that is selected in the debugger. If the selected thread is
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
706 not the last thread to run (the "current" thread), then it cannot be
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
707 used to execute debug_print. Use the Debug menu to select the current
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
708 thread and try using debug_print again. Note that the debugger halts
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
709 execution (e.g., due to a breakpoint) in the context of the current
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
710 thread, so this should only be a problem if you've explicitly switched
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
711 threads.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
712
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
713 It is also possible to keep appropriately masked and typecast Lisp
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
714 symbols in the Watch window, this is more convenient when steeping
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
715 though the code. For instance, on entering apply_lambda, you can
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
716 watch (struct Lisp_Symbol *) (0xfffffff & args[0]).
37333
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
717
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
718 Optimizations often confuse the MS debugger. For example, the
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
719 debugger will sometimes report wrong line numbers, e.g., when it
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
720 prints the backtrace for a crash. It is usually best to look at the
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
721 disassembly to determine exactly what code is being run--the
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
722 disassembly will probably show several source lines followed by a
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
723 block of assembler for those lines. The actual point where Emacs
77156
563a04f93ea0 Fix typos.
Glenn Morris <rgm@gnu.org>
parents: 76739
diff changeset
724 crashes will be one of those source lines, but not necessarily the one
37333
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
725 that the debugger reports.
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
726
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
727 Another problematic area with the MS debugger is with variables that
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
728 are stored in registers: it will sometimes display wrong values for
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
729 those variables. Usually you will not be able to see any value for a
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
730 register variable, but if it is only being stored in a register
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
731 temporarily, you will see an old value for it. Again, you need to
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
732 look at the disassembly to determine which registers are being used,
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
733 and look at those registers directly, to see the actual current values
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
734 of these variables.
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49600
diff changeset
735
72294
23bdb18ffccf *** empty log message ***
Nick Roberts <nickrob@snap.net.nz>
parents: 72293
diff changeset
736
75774
dc23aaa67696 Switch to standard GPL text for license.
Glenn Morris <rgm@gnu.org>
parents: 75348
diff changeset
737 This file is part of GNU Emacs.
dc23aaa67696 Switch to standard GPL text for license.
Glenn Morris <rgm@gnu.org>
parents: 75348
diff changeset
738
95004
cbf5528cf447 Switch to recommended form of GPLv3 permissions notice.
Glenn Morris <rgm@gnu.org>
parents: 92360
diff changeset
739 GNU Emacs is free software: you can redistribute it and/or modify
75774
dc23aaa67696 Switch to standard GPL text for license.
Glenn Morris <rgm@gnu.org>
parents: 75348
diff changeset
740 it under the terms of the GNU General Public License as published by
95004
cbf5528cf447 Switch to recommended form of GPLv3 permissions notice.
Glenn Morris <rgm@gnu.org>
parents: 92360
diff changeset
741 the Free Software Foundation, either version 3 of the License, or
cbf5528cf447 Switch to recommended form of GPLv3 permissions notice.
Glenn Morris <rgm@gnu.org>
parents: 92360
diff changeset
742 (at your option) any later version.
75774
dc23aaa67696 Switch to standard GPL text for license.
Glenn Morris <rgm@gnu.org>
parents: 75348
diff changeset
743
dc23aaa67696 Switch to standard GPL text for license.
Glenn Morris <rgm@gnu.org>
parents: 75348
diff changeset
744 GNU Emacs is distributed in the hope that it will be useful,
dc23aaa67696 Switch to standard GPL text for license.
Glenn Morris <rgm@gnu.org>
parents: 75348
diff changeset
745 but WITHOUT ANY WARRANTY; without even the implied warranty of
dc23aaa67696 Switch to standard GPL text for license.
Glenn Morris <rgm@gnu.org>
parents: 75348
diff changeset
746 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
dc23aaa67696 Switch to standard GPL text for license.
Glenn Morris <rgm@gnu.org>
parents: 75348
diff changeset
747 GNU General Public License for more details.
dc23aaa67696 Switch to standard GPL text for license.
Glenn Morris <rgm@gnu.org>
parents: 75348
diff changeset
748
dc23aaa67696 Switch to standard GPL text for license.
Glenn Morris <rgm@gnu.org>
parents: 75348
diff changeset
749 You should have received a copy of the GNU General Public License
95004
cbf5528cf447 Switch to recommended form of GPLv3 permissions notice.
Glenn Morris <rgm@gnu.org>
parents: 92360
diff changeset
750 along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
75774
dc23aaa67696 Switch to standard GPL text for license.
Glenn Morris <rgm@gnu.org>
parents: 75348
diff changeset
751
dc23aaa67696 Switch to standard GPL text for license.
Glenn Morris <rgm@gnu.org>
parents: 75348
diff changeset
752
72294
23bdb18ffccf *** empty log message ***
Nick Roberts <nickrob@snap.net.nz>
parents: 72293
diff changeset
753 Local variables:
23bdb18ffccf *** empty log message ***
Nick Roberts <nickrob@snap.net.nz>
parents: 72293
diff changeset
754 mode: outline
23bdb18ffccf *** empty log message ***
Nick Roberts <nickrob@snap.net.nz>
parents: 72293
diff changeset
755 paragraph-separate: "[ ]*$"
23bdb18ffccf *** empty log message ***
Nick Roberts <nickrob@snap.net.nz>
parents: 72293
diff changeset
756 end:
23bdb18ffccf *** empty log message ***
Nick Roberts <nickrob@snap.net.nz>
parents: 72293
diff changeset
757
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49600
diff changeset
758 ;;; arch-tag: fbf32980-e35d-481f-8e4c-a2eca2586e6b