annotate etc/DEBUG @ 36583:adb23d572f63

*** empty log message ***
author Gerd Moellmann <gerd@gnu.org>
date Tue, 06 Mar 2001 14:04:15 +0000
parents 9cc9788cc61b
children 08aed53e171c
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
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
2 Copyright (c) 1985, 2000, 2001 Free Software Foundation, Inc.
25853
Dave Love <fx@gnu.org>
parents:
diff changeset
3
Dave Love <fx@gnu.org>
parents:
diff changeset
4 Permission is granted to anyone to make or distribute verbatim copies
Dave Love <fx@gnu.org>
parents:
diff changeset
5 of this document as received, in any medium, provided that the
Dave Love <fx@gnu.org>
parents:
diff changeset
6 copyright notice and permission notice are preserved,
Dave Love <fx@gnu.org>
parents:
diff changeset
7 and that the distributor grants the recipient permission
Dave Love <fx@gnu.org>
parents:
diff changeset
8 for further redistribution as permitted by this notice.
Dave Love <fx@gnu.org>
parents:
diff changeset
9
Dave Love <fx@gnu.org>
parents:
diff changeset
10 Permission is granted to distribute modified versions
Dave Love <fx@gnu.org>
parents:
diff changeset
11 of this document, or of portions of it,
Dave Love <fx@gnu.org>
parents:
diff changeset
12 under the above conditions, provided also that they
Dave Love <fx@gnu.org>
parents:
diff changeset
13 carry prominent notices stating who last changed them.
Dave Love <fx@gnu.org>
parents:
diff changeset
14
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
15 [People who debug Emacs on Windows using native Windows debuggers
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
16 should read the Windows-specific section near the end of this
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
17 document.]
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
18
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
19 It is a good idea to run Emacs under GDB (or some other suitable
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
20 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
21 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
22 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
23 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
24
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
25 If Emacs hangs, or seems to be stuck in some infinite loop, typing
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
26 "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
27 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
28
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
29 ** Getting control to the debugger
25853
Dave Love <fx@gnu.org>
parents:
diff changeset
30
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
31 `Fsignal' is a very useful place to put a breakpoint in.
25853
Dave Love <fx@gnu.org>
parents:
diff changeset
32 All Lisp errors go through there.
Dave Love <fx@gnu.org>
parents:
diff changeset
33
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
34 It is useful, when debugging, to have a guaranteed way to return to
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
35 the debugger at any time. When using X, this is easy: type C-c at the
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
36 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
37 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
38 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
39
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
40 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
41 (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
42 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
43
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
44 handle int stop nopass
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
45
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
46 After this `handle' command, SIGINT will return control to GDB. If
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
47 you want the C-g to cause a QUIT within Emacs as well, omit the
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
48 `nopass'.
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
49
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
50 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
51 the code for some character into the variable stop_character. Thus,
25853
Dave Love <fx@gnu.org>
parents:
diff changeset
52
Dave Love <fx@gnu.org>
parents:
diff changeset
53 set stop_character = 29
Dave Love <fx@gnu.org>
parents:
diff changeset
54
Dave Love <fx@gnu.org>
parents:
diff changeset
55 makes Control-] (decimal code 29) the stop character.
Dave Love <fx@gnu.org>
parents:
diff changeset
56 Typing Control-] will cause immediate stop. You cannot
Dave Love <fx@gnu.org>
parents:
diff changeset
57 use the set command until the inferior process has been started.
Dave Love <fx@gnu.org>
parents:
diff changeset
58 Put a breakpoint early in `main', or suspend the Emacs,
Dave Love <fx@gnu.org>
parents:
diff changeset
59 to get an opportunity to do the set command.
Dave Love <fx@gnu.org>
parents:
diff changeset
60
Dave Love <fx@gnu.org>
parents:
diff changeset
61 ** Examining Lisp object values.
Dave Love <fx@gnu.org>
parents:
diff changeset
62
Dave Love <fx@gnu.org>
parents:
diff changeset
63 When you have a live process to debug, and it has not encountered a
Dave Love <fx@gnu.org>
parents:
diff changeset
64 fatal error, you can use the GDB command `pr'. First print the value
Dave Love <fx@gnu.org>
parents:
diff changeset
65 in the ordinary way, with the `p' command. Then type `pr' with no
Dave Love <fx@gnu.org>
parents:
diff changeset
66 arguments. This calls a subroutine which uses the Lisp printer.
Dave Love <fx@gnu.org>
parents:
diff changeset
67
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
68 Note: It is not a good idea to try `pr' if you know that Emacs is in
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
69 deep trouble: its stack smashed (e.g., if it encountered SIGSEGV due
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
70 to stack overflow), or crucial data structures, such as `obarray',
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
71 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
72 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
73 debugging the original problem.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
74
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
75 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
76 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
77 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
78 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
79 Emacs will be between instructions and capable of handling `pr'.
25853
Dave Love <fx@gnu.org>
parents:
diff changeset
80
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
81 If you can't use `pr' command, for whatever reason, you can fall back
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
82 on lower-level commands. Use the `xtype' command to print out the
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
83 data type of the last data value. Once you know the data type, use
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
84 the command that corresponds to that type. Here are these commands:
25853
Dave Love <fx@gnu.org>
parents:
diff changeset
85
Dave Love <fx@gnu.org>
parents:
diff changeset
86 xint xptr xwindow xmarker xoverlay xmiscfree xintfwd xboolfwd xobjfwd
Dave Love <fx@gnu.org>
parents:
diff changeset
87 xbufobjfwd xkbobjfwd xbuflocal xbuffer xsymbol xstring xvector xframe
Dave Love <fx@gnu.org>
parents:
diff changeset
88 xwinconfig xcompiled xcons xcar xcdr xsubr xprocess xfloat xscrollbar
Dave Love <fx@gnu.org>
parents:
diff changeset
89
Dave Love <fx@gnu.org>
parents:
diff changeset
90 Each one of them applies to a certain type or class of types.
Dave Love <fx@gnu.org>
parents:
diff changeset
91 (Some of these types are not visible in Lisp, because they exist only
Dave Love <fx@gnu.org>
parents:
diff changeset
92 internally.)
Dave Love <fx@gnu.org>
parents:
diff changeset
93
Dave Love <fx@gnu.org>
parents:
diff changeset
94 Each x... command prints some information about the value, and
Dave Love <fx@gnu.org>
parents:
diff changeset
95 produces a GDB value (subsequently available in $) through which you
Dave Love <fx@gnu.org>
parents:
diff changeset
96 can get at the rest of the contents.
Dave Love <fx@gnu.org>
parents:
diff changeset
97
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
98 In general, most of the rest of the contents will be additional Lisp
25853
Dave Love <fx@gnu.org>
parents:
diff changeset
99 objects which you can examine in turn with the x... commands.
Dave Love <fx@gnu.org>
parents:
diff changeset
100
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
101 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
102 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
103 Here's an example using concepts explained in the node "Value History"
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
104 of the GDB manual to print the variable frame from this line in
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
105 xmenu.c:
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
106
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
107 buf.frame_or_window = frame;
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
108
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
109 First, use these commands:
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
110
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
111 cd src
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
112 gdb emacs
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
113 b xmenu.c:1296
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
114 r -q
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
115
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
116 Then type C-x 5 2 to create a new frame, and it hits the breakpoint:
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
117
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
118 (gdb) p frame
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
119 $1 = 1077872640
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
120 (gdb) xtype
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
121 Lisp_Vectorlike
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
122 PVEC_FRAME
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
123 (gdb) xframe
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
124 $2 = (struct frame *) 0x3f0800
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
125 (gdb) p *$
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
126 $3 = {
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
127 size = 536871989,
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
128 next = 0x366240,
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
129 name = 809661752,
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
130 [...]
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
131 }
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
132 (gdb) p $3->name
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
133 $4 = 809661752
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
134
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
135 Now we can use `pr' to print the name of the frame:
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
136
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
137 (gdb) pr
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
138 "emacs@steenrod.math.nwu.edu"
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
139
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
140 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
141 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
142 `add_command_key' from keyboard.c:
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
143
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
144 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
145
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
146 XVECTOR is a macro, and therefore GDB does not know about it.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
147 GDB cannot evaluate "p XVECTOR (this_command_keys)".
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
148
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
149 However, you can use the xvector command in GDB to get the same
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
150 result. Here is how:
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
151
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
152 (gdb) p this_command_keys
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
153 $1 = 1078005760
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
154 (gdb) xvector
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
155 $2 = (struct Lisp_Vector *) 0x411000
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
156 0
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
157 (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
158 $3 = 1077872640
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
159 (gdb) p &$
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
160 $4 = (int *) 0x411008
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
161
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
162 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
163 There are many Lisp vectors such as `recent_keys', which contains the
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
164 last 100 keystrokes. We can print this Lisp vector
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
165
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
166 p recent_keys
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
167 pr
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 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
170 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
171 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
172
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
173 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
174
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
175 So we define a GDB command `xvector-elts', so the last 10 keystrokes
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
176 are printed by
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
177
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
178 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
179
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
180 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
181
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
182 define xvector-elts
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
183 set $i = 0
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
184 p $arg0
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
185 xvector
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
186 set $foo = $
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
187 while $i < $arg2
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
188 p $foo->contents[$arg1-($i++)]
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
189 pr
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
190 end
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
191 document xvector-elts
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
192 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
193 xvector-elts v n i
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
194 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
195 end
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 ** 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
198
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
199 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
200 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
201
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
202 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
203 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
204 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
205 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
206 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
207
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
208 p *args
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
209 pr
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
210
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
211 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
212 of function calling.
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 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
215 values. Here's how to print the first argument:
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
216
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
217 p args[1]
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
218 pr
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
219
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
220 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
221 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
222 conveniently. For example:
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
223
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
224 p *args
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
225 xtype
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
226
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
227 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
228
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
229 xsymbol
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 ** 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
232
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
233 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
234
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
235 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
236 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
237 breakpoints in it.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
238
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
239 ** Debugging `temacs'
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 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
242 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
243 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
244
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
245 ** If you encounter X protocol errors
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
246
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
247 Try evaluating (x-synchronize t). That puts Emacs into synchronous
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
248 mode, where each Xlib call checks for errors before it returns. This
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
249 mode is much slower, but when you get an error, you will see exactly
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
250 which call really caused the error.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
251
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
252 ** 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
253
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
254 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
255 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
256 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
257 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
258 `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
259 looping, `step' will return.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
260
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
261 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
262 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
263 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
264 what the arguments are.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
265
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
266 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
267 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
268 `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
269 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
270 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
271 just tried to finish.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
272
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
273 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
274 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
275 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
276 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
277 not exit when it should.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
278
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
279 ** 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
280 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
281
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
282 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
283 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
284 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
285
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
286 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
287 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
288 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
289
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
290 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
291 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
292 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
293
25853
Dave Love <fx@gnu.org>
parents:
diff changeset
294 ** If GDB does not run and your debuggers can't load Emacs.
Dave Love <fx@gnu.org>
parents:
diff changeset
295
Dave Love <fx@gnu.org>
parents:
diff changeset
296 On some systems, no debugger can load Emacs with a symbol table,
Dave Love <fx@gnu.org>
parents:
diff changeset
297 perhaps because they all have fixed limits on the number of symbols
Dave Love <fx@gnu.org>
parents:
diff changeset
298 and Emacs exceeds the limits. Here is a method that can be used
Dave Love <fx@gnu.org>
parents:
diff changeset
299 in such an extremity. Do
Dave Love <fx@gnu.org>
parents:
diff changeset
300
Dave Love <fx@gnu.org>
parents:
diff changeset
301 nm -n temacs > nmout
Dave Love <fx@gnu.org>
parents:
diff changeset
302 strip temacs
Dave Love <fx@gnu.org>
parents:
diff changeset
303 adb temacs
Dave Love <fx@gnu.org>
parents:
diff changeset
304 0xd:i
Dave Love <fx@gnu.org>
parents:
diff changeset
305 0xe:i
Dave Love <fx@gnu.org>
parents:
diff changeset
306 14:i
Dave Love <fx@gnu.org>
parents:
diff changeset
307 17:i
Dave Love <fx@gnu.org>
parents:
diff changeset
308 :r -l loadup (or whatever)
Dave Love <fx@gnu.org>
parents:
diff changeset
309
Dave Love <fx@gnu.org>
parents:
diff changeset
310 It is necessary to refer to the file `nmout' to convert
Dave Love <fx@gnu.org>
parents:
diff changeset
311 numeric addresses into symbols and vice versa.
Dave Love <fx@gnu.org>
parents:
diff changeset
312
Dave Love <fx@gnu.org>
parents:
diff changeset
313 It is useful to be running under a window system.
Dave Love <fx@gnu.org>
parents:
diff changeset
314 Then, if Emacs becomes hopelessly wedged, you can create
Dave Love <fx@gnu.org>
parents:
diff changeset
315 another window to do kill -9 in. kill -ILL is often
Dave Love <fx@gnu.org>
parents:
diff changeset
316 useful too, since that may make Emacs dump core or return
Dave Love <fx@gnu.org>
parents:
diff changeset
317 to adb.
Dave Love <fx@gnu.org>
parents:
diff changeset
318
Dave Love <fx@gnu.org>
parents:
diff changeset
319
Dave Love <fx@gnu.org>
parents:
diff changeset
320 ** Debugging incorrect screen updating.
Dave Love <fx@gnu.org>
parents:
diff changeset
321
Dave Love <fx@gnu.org>
parents:
diff changeset
322 To debug Emacs problems that update the screen wrong, it is useful
Dave Love <fx@gnu.org>
parents:
diff changeset
323 to have a record of what input you typed and what Emacs sent to the
Dave Love <fx@gnu.org>
parents:
diff changeset
324 screen. To make these records, do
Dave Love <fx@gnu.org>
parents:
diff changeset
325
Dave Love <fx@gnu.org>
parents:
diff changeset
326 (open-dribble-file "~/.dribble")
Dave Love <fx@gnu.org>
parents:
diff changeset
327 (open-termscript "~/.termscript")
Dave Love <fx@gnu.org>
parents:
diff changeset
328
Dave Love <fx@gnu.org>
parents:
diff changeset
329 The dribble file contains all characters read by Emacs from the
Dave Love <fx@gnu.org>
parents:
diff changeset
330 terminal, and the termscript file contains all characters it sent to
Dave Love <fx@gnu.org>
parents:
diff changeset
331 the terminal. The use of the directory `~/' prevents interference
Dave Love <fx@gnu.org>
parents:
diff changeset
332 with any other user.
Dave Love <fx@gnu.org>
parents:
diff changeset
333
Dave Love <fx@gnu.org>
parents:
diff changeset
334 If you have irreproducible display problems, put those two expressions
Dave Love <fx@gnu.org>
parents:
diff changeset
335 in your ~/.emacs file. When the problem happens, exit the Emacs that
Dave Love <fx@gnu.org>
parents:
diff changeset
336 you were running, kill it, and rename the two files. Then you can start
Dave Love <fx@gnu.org>
parents:
diff changeset
337 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
338
9b989029cccf Add note aboute using `inverse-video' to detect excessive screen redraw.
Miles Bader <miles@gnu.org>
parents: 32523
diff changeset
339 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
340 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
341 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
342 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
343
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
344
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
345 ** Debugging LessTif
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
346
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
347 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
348 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
349 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
350 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
351 For instance
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
352
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
353 export DEBUGSOURCES="RowColumn.c MenuShell.c MenuUtil.c"
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
354 export DEBUG_FILE=/usr/tmp/LESSTIF_TRACE
35720
c6ae90d82552 Clarify the instructions for debugging LessTif.
Eli Zaretskii <eliz@gnu.org>
parents: 35655
diff changeset
355 emacs &
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
356
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
357 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
358 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
359 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
360 last line above.
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
361
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
362 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
363 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
364 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
365 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
366
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
367
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
368 ** Running Emacs with Purify
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
369
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
370 Some people who are willing to use non-free software use Purify. We
35861
9cc9788cc61b Fix a couple of typos.
Eli Zaretskii <eliz@gnu.org>
parents: 35791
diff changeset
371 can't ethically ask you to become a Purify user; but if you have it,
9cc9788cc61b Fix a couple of typos.
Eli Zaretskii <eliz@gnu.org>
parents: 35791
diff changeset
372 and you test Emacs with it, we will not refuse to look at the results
9cc9788cc61b Fix a couple of typos.
Eli Zaretskii <eliz@gnu.org>
parents: 35791
diff changeset
373 you find.
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
374
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
375 Emacs compiled with Purify won't run without some hacking. Here are
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
376 some of the changes you might find necessary (SYSTEM-NAME and
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
377 MACHINE-NAME are the names of your OS- and CPU-specific headers in the
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
378 subdirectories of `src'):
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
379
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
380 - In src/s/SYSTEM-NAME.h add "#define SYSTEM_MALLOC".
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
381
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
382 - In src/m/MACHINE-NAME.h add "#define CANNOT_DUMP" and
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
383 "#define CANNOT_UNEXEC".
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
384
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
385 - Configure with a different --prefix= option. If you use GCC,
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
386 version 2.7.2 is preferred, as Purify works a lot better with it
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
387 than with 2.95 or later versions.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
388
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
389 - Type "make" then "make -k install". You might need to run
35861
9cc9788cc61b Fix a couple of typos.
Eli Zaretskii <eliz@gnu.org>
parents: 35791
diff changeset
390 "make -k install" twice.
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
391
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
392 - cd src; purify -chain-length=40 gcc <link command line for temacs>
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
393
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
394 - cd ..; src/temacs
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 Note that Purify might print lots of false alarms for bitfields used
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
397 by Emacs in some data structures. If you want to get rid of the false
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
398 alarms, you will have to hack the definitions of these data structures
35861
9cc9788cc61b Fix a couple of typos.
Eli Zaretskii <eliz@gnu.org>
parents: 35791
diff changeset
399 on the respective headers to remove the `:N' bitfield definitions
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
400 (which will cause each such field to use a full int).
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
401
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
402 ** Debugging problems which happen in GC
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
403
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
404 The array `last_marked' (defined on alloc.c) can be used to display
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
405 up to 500 last objects marked by the garbage collection process. The
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
406 variable `last_marked_index' holds the index into the `last_marked'
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
407 array one place beyond where the very last marked object is stored.
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 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
410 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
411 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
412 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
413 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
414 Use the `last_marked' array and the source to reconstruct the sequence
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
415 that objects were marked.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
416
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
417 Once you discover the corrupted Lisp object or data structure, it is
35861
9cc9788cc61b Fix a couple of typos.
Eli Zaretskii <eliz@gnu.org>
parents: 35791
diff changeset
418 useful to look at it in a fresh Emacs session and compare its contents
9cc9788cc61b Fix a couple of typos.
Eli Zaretskii <eliz@gnu.org>
parents: 35791
diff changeset
419 with a session that you are debugging.
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
420
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
421 ** 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
422
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
423 (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
424
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
425 To debug Emacs with Microsoft Visual C++, you either start emacs from
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
426 the debugger or attach the debugger to a running emacs process. To
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
427 start emacs from the debugger, you can use the file bin/debug.bat. The
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
428 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
429 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
430 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
431 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
432 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
433 soon as a breakpoint is hit.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
434
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
435 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
436 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
437 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
438 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
439 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
440 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
441 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
442 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
443 breakpoint is hit.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
444
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
445 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
446 '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
447 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
448 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
449 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
450 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
451 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
452 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
453 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
454 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
455 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
456 'debug_print'.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
457
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
458 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
459 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
460 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
461 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
462 `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
463 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
464 "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
465 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
466
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
467 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
468 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
469 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
470 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
471 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
472
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
473 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
474 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
475 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
476 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
477 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
478 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
479 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
480 threads.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
481
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
482 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
483 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
484 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
485 watch (struct Lisp_Symbol *) (0xfffffff & args[0]).