annotate etc/DEBUG @ 36150:46e59561af4c

Display Vars node renamed Display Custom. Include info there about customizing cursor appearance. Clean up aggressive scrolling. Clarify horizontal scrolling discussion. Fix index entries for line number mode.
author Richard M. Stallman <rms@gnu.org>
date Sat, 17 Feb 2001 16:45:37 +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]).