annotate etc/DEBUG @ 43968:7ec801358b7e

(Qlocal, QCname, QCbuffer, QChost, QCservice, QCfamily) (QClocal, QCremote, QCserver, QCdatagram, QCnowait, QCnoquery,QCstop) (QCcoding, QCoptions, QCfilter, QCsentinel, QClog, QCfeature): New variables. (NETCONN1_P): New macro. (DATAGRAM_SOCKETS): New conditional symbol. (datagram_address): New array. (DATAGRAM_CONN_P, DATAGRAM_CHAN_P): New macros. (status_message): Use concat3. (Fprocess_status): Add `listen' status to doc string. Return `stop' for a stopped network process. (Fset_process_buffer): Update contact plist for network process. (Fset_process_filter): Ditto. Don't enable input for stopped network processes. Server must listen, even if filter is t. (Fset_process_query_on_exit_flag, Fprocess_query_on_exit_flag): New functions. (Fprocess_kill_without_query): Removed. Now defined in simple.el. (Fprocess_contact): Added KEY argument. Handle datagrams. (list_processes_1): Optionally show only processes with the query on exit flag set. Dynamically adjust column widths. Omit tty column if not needed. Report stopped network processes. Identify server and datagram network processes. (Flist_processes): New optional arg `query-only'. (conv_sockaddr_to_lisp, get_lisp_to_sockaddr_size) (conv_lisp_to_sockaddr, set_socket_options) (network_process_featurep, unwind_request_sigio): New helper functions. (Fprocess_datagram_address, Fset_process_datagram_address): (Fset_network_process_options): New lisp functions. (Fopen_network_stream): Removed. Now defined in simple.el. (Fmake_network_process): New lisp function. Code is based on previous Fopen_network_stream, but heavily reworked with new property list based argument list, support for datagrams, server processes, and local sockets in addition to old client-only functionality. (server_accept_connection): New function. (wait_reading_process_input): Use it to handle incoming connects. Do not enable input on a new connection if process is stopped. (read_process_output): Handle datagram sockets. Use 2k buffer for them. (send_process): Handle datagram sockets. (Fstop_process, Fcontinue_process): Apply to network processes. A stopped network process is indicated by setting command field to t . (Fprocess_send_eof): No-op if datagram connection. (Fstatus_notify): Don't read input for a stream server socket or a stopped network process. (init_process): Initialize datagram_address array. (syms_of_process): Intern and staticpro new variables, defsubr new functions.
author Kim F. Storm <storm@cua.dk>
date Sun, 17 Mar 2002 20:20:33 +0000
parents 7fe131ded6d9
children 927a6a3e6c8f
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
43432
7fe131ded6d9 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 43106
diff changeset
19 ** When you debug Emacs with GDB, you should start it in the directory
7fe131ded6d9 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 43106
diff changeset
20 where you built Emacs. That directory has a .gdbinit file that defines
7fe131ded6d9 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 43106
diff changeset
21 various "user-defined" commands for debugging Emacs.
7fe131ded6d9 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 43106
diff changeset
22
7fe131ded6d9 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 43106
diff changeset
23 ** It is a good idea to run Emacs under GDB (or some other suitable
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
24 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
25 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
26 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
27 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
28
43432
7fe131ded6d9 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 43106
diff changeset
29 ** If Emacs hangs, or seems to be stuck in some infinite loop, typing
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
30 "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
31 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
32
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
33 ** Getting control to the debugger
25853
Dave Love <fx@gnu.org>
parents:
diff changeset
34
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
35 `Fsignal' is a very useful place to put a breakpoint in.
25853
Dave Love <fx@gnu.org>
parents:
diff changeset
36 All Lisp errors go through there.
Dave Love <fx@gnu.org>
parents:
diff changeset
37
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
38 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
39 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
40 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
41 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
42 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
43
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
44 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
45 (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
46 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
47
43106
cd4549362019 Fix a typo in "handle SIGINT" command.
Eli Zaretskii <eliz@gnu.org>
parents: 41839
diff changeset
48 handle SIGINT stop nopass
35791
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 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
51 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
52 `nopass'.
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
53
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
54 A technique that can work when `handle SIGINT' does not is to store
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
55 the code for some character into the variable stop_character. Thus,
25853
Dave Love <fx@gnu.org>
parents:
diff changeset
56
Dave Love <fx@gnu.org>
parents:
diff changeset
57 set stop_character = 29
Dave Love <fx@gnu.org>
parents:
diff changeset
58
Dave Love <fx@gnu.org>
parents:
diff changeset
59 makes Control-] (decimal code 29) the stop character.
Dave Love <fx@gnu.org>
parents:
diff changeset
60 Typing Control-] will cause immediate stop. You cannot
Dave Love <fx@gnu.org>
parents:
diff changeset
61 use the set command until the inferior process has been started.
Dave Love <fx@gnu.org>
parents:
diff changeset
62 Put a breakpoint early in `main', or suspend the Emacs,
Dave Love <fx@gnu.org>
parents:
diff changeset
63 to get an opportunity to do the set command.
Dave Love <fx@gnu.org>
parents:
diff changeset
64
Dave Love <fx@gnu.org>
parents:
diff changeset
65 ** Examining Lisp object values.
Dave Love <fx@gnu.org>
parents:
diff changeset
66
Dave Love <fx@gnu.org>
parents:
diff changeset
67 When you have a live process to debug, and it has not encountered a
Dave Love <fx@gnu.org>
parents:
diff changeset
68 fatal error, you can use the GDB command `pr'. First print the value
Dave Love <fx@gnu.org>
parents:
diff changeset
69 in the ordinary way, with the `p' command. Then type `pr' with no
Dave Love <fx@gnu.org>
parents:
diff changeset
70 arguments. This calls a subroutine which uses the Lisp printer.
Dave Love <fx@gnu.org>
parents:
diff changeset
71
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
72 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
73 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
74 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
75 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
76 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
77 debugging the original problem.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
78
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
79 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
80 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
81 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
82 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
83 Emacs will be between instructions and capable of handling `pr'.
25853
Dave Love <fx@gnu.org>
parents:
diff changeset
84
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
85 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
86 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
87 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
88 the command that corresponds to that type. Here are these commands:
25853
Dave Love <fx@gnu.org>
parents:
diff changeset
89
Dave Love <fx@gnu.org>
parents:
diff changeset
90 xint xptr xwindow xmarker xoverlay xmiscfree xintfwd xboolfwd xobjfwd
Dave Love <fx@gnu.org>
parents:
diff changeset
91 xbufobjfwd xkbobjfwd xbuflocal xbuffer xsymbol xstring xvector xframe
Dave Love <fx@gnu.org>
parents:
diff changeset
92 xwinconfig xcompiled xcons xcar xcdr xsubr xprocess xfloat xscrollbar
Dave Love <fx@gnu.org>
parents:
diff changeset
93
Dave Love <fx@gnu.org>
parents:
diff changeset
94 Each one of them applies to a certain type or class of types.
Dave Love <fx@gnu.org>
parents:
diff changeset
95 (Some of these types are not visible in Lisp, because they exist only
Dave Love <fx@gnu.org>
parents:
diff changeset
96 internally.)
Dave Love <fx@gnu.org>
parents:
diff changeset
97
Dave Love <fx@gnu.org>
parents:
diff changeset
98 Each x... command prints some information about the value, and
Dave Love <fx@gnu.org>
parents:
diff changeset
99 produces a GDB value (subsequently available in $) through which you
Dave Love <fx@gnu.org>
parents:
diff changeset
100 can get at the rest of the contents.
Dave Love <fx@gnu.org>
parents:
diff changeset
101
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
102 In general, most of the rest of the contents will be additional Lisp
25853
Dave Love <fx@gnu.org>
parents:
diff changeset
103 objects which you can examine in turn with the x... commands.
Dave Love <fx@gnu.org>
parents:
diff changeset
104
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
105 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
106 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
107 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
108 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
109 xmenu.c:
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 buf.frame_or_window = frame;
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
112
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
113 First, use these commands:
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
114
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
115 cd src
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
116 gdb emacs
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
117 b xmenu.c:1296
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
118 r -q
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
119
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
120 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
121
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
122 (gdb) p frame
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
123 $1 = 1077872640
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
124 (gdb) xtype
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
125 Lisp_Vectorlike
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
126 PVEC_FRAME
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
127 (gdb) xframe
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
128 $2 = (struct frame *) 0x3f0800
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
129 (gdb) p *$
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
130 $3 = {
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
131 size = 536871989,
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
132 next = 0x366240,
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
133 name = 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 }
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
136 (gdb) p $3->name
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
137 $4 = 809661752
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
138
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
139 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
140
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
141 (gdb) pr
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
142 "emacs@steenrod.math.nwu.edu"
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 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
145 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
146 `add_command_key' from keyboard.c:
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
147
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
148 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
149
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
150 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
151 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
152
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
153 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
154 result. Here is how:
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
155
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
156 (gdb) p this_command_keys
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
157 $1 = 1078005760
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
158 (gdb) xvector
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
159 $2 = (struct Lisp_Vector *) 0x411000
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
160 0
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
161 (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
162 $3 = 1077872640
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
163 (gdb) p &$
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
164 $4 = (int *) 0x411008
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 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
167 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
168 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
169
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
170 p recent_keys
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
171 pr
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 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
174 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
175 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
176
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
177 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
178
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
179 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
180 are printed by
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 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
183
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
184 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
185
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
186 define xvector-elts
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
187 set $i = 0
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
188 p $arg0
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
189 xvector
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
190 set $foo = $
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
191 while $i < $arg2
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
192 p $foo->contents[$arg1-($i++)]
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
193 pr
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
194 end
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
195 document xvector-elts
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
196 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
197 xvector-elts v n i
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
198 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
199 end
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
200
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
201 ** 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
202
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
203 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
204 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
205
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
206 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
207 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
208 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
209 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
210 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
211
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
212 p *args
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
213 pr
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
214
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
215 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
216 of function calling.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
217
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
218 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
219 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
220
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
221 p args[1]
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
222 pr
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 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
225 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
226 conveniently. For example:
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
227
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
228 p *args
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
229 xtype
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 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
232
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
233 xsymbol
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 ** 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
236
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
237 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
238
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
239 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
240 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
241 breakpoints in it.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
242
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
243 ** Debugging `temacs'
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 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
246 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
247 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
248
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
249 ** If you encounter X protocol errors
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
250
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
251 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
252 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
253 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
254 which call really caused the error.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
255
36962
9c7eb7e6bf3e Document the use of -xrm to start EMacs in synchronous mode.
Eli Zaretskii <eliz@gnu.org>
parents: 36625
diff changeset
256 You can start Emacs in a synchronous mode by invoking it with the -xrm
9c7eb7e6bf3e Document the use of -xrm to start EMacs in synchronous mode.
Eli Zaretskii <eliz@gnu.org>
parents: 36625
diff changeset
257 option, like this:
9c7eb7e6bf3e Document the use of -xrm to start EMacs in synchronous mode.
Eli Zaretskii <eliz@gnu.org>
parents: 36625
diff changeset
258
37534
3ea5075dc420 Fix a typo in the "emacs -xrm" command line. Reported by Kenichi Handa.
Eli Zaretskii <eliz@gnu.org>
parents: 37509
diff changeset
259 emacs -xrm "emacs.synchronous: true"
36962
9c7eb7e6bf3e Document the use of -xrm to start EMacs in synchronous mode.
Eli Zaretskii <eliz@gnu.org>
parents: 36625
diff changeset
260
9c7eb7e6bf3e Document the use of -xrm to start EMacs in synchronous mode.
Eli Zaretskii <eliz@gnu.org>
parents: 36625
diff changeset
261 Setting a breakpoint in the function `x_error_quitter' and looking at
9c7eb7e6bf3e Document the use of -xrm to start EMacs in synchronous mode.
Eli Zaretskii <eliz@gnu.org>
parents: 36625
diff changeset
262 the backtrace when Emacs stops inside that function will show what
9c7eb7e6bf3e Document the use of -xrm to start EMacs in synchronous mode.
Eli Zaretskii <eliz@gnu.org>
parents: 36625
diff changeset
263 code causes the X protocol errors.
9c7eb7e6bf3e Document the use of -xrm to start EMacs in synchronous mode.
Eli Zaretskii <eliz@gnu.org>
parents: 36625
diff changeset
264
41839
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
265 Some bugs related to the X protocol disappear when Emacs runs in a
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
266 synchronous mode. To track down those bugs, we suggest the following
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
267 procedure:
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
268
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
269 - Run Emacs under a debugger and put a breakpoint inside the
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
270 primitive function which, when called from Lisp, triggers the X
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
271 protocol errors. For example, if the errors happen when you
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
272 delete a frame, put a breakpoint inside `Fdelete_frame'.
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
273
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
274 - When the breakpoint breaks, step through the code, looking for
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
275 calls to X functions (the ones whose names begin with "X" or
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
276 "Xt" or "Xm").
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
277
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
278 - Insert calls to `XSync' before and after each call to the X
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
279 functions, like this:
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
280
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
281 XSync (f->output_data.x->display_info->display, 0);
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
282
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
283 where `f' is the pointer to the `struct frame' of the selected
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
284 frame, normally available via XFRAME (selected_frame). (Most
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
285 functions which call X already have some variable that holds the
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
286 pointer to the frame, perhaps called `f' or `sf', so you shouldn't
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
287 need to compute it.)
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
288
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
289 If your debugger can call functions in the program being debugged,
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
290 you should be able to issue the calls to `XSync' without recompiling
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
291 Emacs. For example, with GDB, just type:
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
292
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
293 call XSync (f->output_data.x->display_info->display, 0)
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
294
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
295 before and immediately after the suspect X calls. If your
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
296 debugger does not support this, you will need to add these pairs
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
297 of calls in the source and rebuild Emacs.
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
298
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
299 Either way, systematically step through the code and issue these
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
300 calls until you find the first X function called by Emacs after
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
301 which a call to `XSync' winds up in the function
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
302 `x_error_quitter'. The first X function call for which this
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
303 happens is the one that generated the X protocol error.
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
304
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
305 - You should now look around this offending X call and try to figure
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
306 out what is wrong with it.
902e47b4907b Advice how to debug X protocol error which disappear in the
Eli Zaretskii <eliz@gnu.org>
parents: 40348
diff changeset
307
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
308 ** 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
309
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
310 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
311 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
312 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
313 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
314 `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
315 looping, `step' will return.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
316
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
317 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
318 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
319 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
320 what the arguments are.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
321
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
322 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
323 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
324 `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
325 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
326 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
327 just tried to finish.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
328
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
329 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
330 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
331 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
332 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
333 not exit when it should.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
334
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
335 ** 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
336 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
337
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
338 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
339 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
340 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
341
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
342 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
343 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
344 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
345
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
346 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
347 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
348 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
349
25853
Dave Love <fx@gnu.org>
parents:
diff changeset
350 ** If GDB does not run and your debuggers can't load Emacs.
Dave Love <fx@gnu.org>
parents:
diff changeset
351
Dave Love <fx@gnu.org>
parents:
diff changeset
352 On some systems, no debugger can load Emacs with a symbol table,
Dave Love <fx@gnu.org>
parents:
diff changeset
353 perhaps because they all have fixed limits on the number of symbols
Dave Love <fx@gnu.org>
parents:
diff changeset
354 and Emacs exceeds the limits. Here is a method that can be used
Dave Love <fx@gnu.org>
parents:
diff changeset
355 in such an extremity. Do
Dave Love <fx@gnu.org>
parents:
diff changeset
356
Dave Love <fx@gnu.org>
parents:
diff changeset
357 nm -n temacs > nmout
Dave Love <fx@gnu.org>
parents:
diff changeset
358 strip temacs
Dave Love <fx@gnu.org>
parents:
diff changeset
359 adb temacs
Dave Love <fx@gnu.org>
parents:
diff changeset
360 0xd:i
Dave Love <fx@gnu.org>
parents:
diff changeset
361 0xe:i
Dave Love <fx@gnu.org>
parents:
diff changeset
362 14:i
Dave Love <fx@gnu.org>
parents:
diff changeset
363 17:i
Dave Love <fx@gnu.org>
parents:
diff changeset
364 :r -l loadup (or whatever)
Dave Love <fx@gnu.org>
parents:
diff changeset
365
Dave Love <fx@gnu.org>
parents:
diff changeset
366 It is necessary to refer to the file `nmout' to convert
Dave Love <fx@gnu.org>
parents:
diff changeset
367 numeric addresses into symbols and vice versa.
Dave Love <fx@gnu.org>
parents:
diff changeset
368
Dave Love <fx@gnu.org>
parents:
diff changeset
369 It is useful to be running under a window system.
Dave Love <fx@gnu.org>
parents:
diff changeset
370 Then, if Emacs becomes hopelessly wedged, you can create
Dave Love <fx@gnu.org>
parents:
diff changeset
371 another window to do kill -9 in. kill -ILL is often
Dave Love <fx@gnu.org>
parents:
diff changeset
372 useful too, since that may make Emacs dump core or return
Dave Love <fx@gnu.org>
parents:
diff changeset
373 to adb.
Dave Love <fx@gnu.org>
parents:
diff changeset
374
Dave Love <fx@gnu.org>
parents:
diff changeset
375
Dave Love <fx@gnu.org>
parents:
diff changeset
376 ** Debugging incorrect screen updating.
Dave Love <fx@gnu.org>
parents:
diff changeset
377
Dave Love <fx@gnu.org>
parents:
diff changeset
378 To debug Emacs problems that update the screen wrong, it is useful
Dave Love <fx@gnu.org>
parents:
diff changeset
379 to have a record of what input you typed and what Emacs sent to the
Dave Love <fx@gnu.org>
parents:
diff changeset
380 screen. To make these records, do
Dave Love <fx@gnu.org>
parents:
diff changeset
381
Dave Love <fx@gnu.org>
parents:
diff changeset
382 (open-dribble-file "~/.dribble")
Dave Love <fx@gnu.org>
parents:
diff changeset
383 (open-termscript "~/.termscript")
Dave Love <fx@gnu.org>
parents:
diff changeset
384
Dave Love <fx@gnu.org>
parents:
diff changeset
385 The dribble file contains all characters read by Emacs from the
Dave Love <fx@gnu.org>
parents:
diff changeset
386 terminal, and the termscript file contains all characters it sent to
Dave Love <fx@gnu.org>
parents:
diff changeset
387 the terminal. The use of the directory `~/' prevents interference
Dave Love <fx@gnu.org>
parents:
diff changeset
388 with any other user.
Dave Love <fx@gnu.org>
parents:
diff changeset
389
Dave Love <fx@gnu.org>
parents:
diff changeset
390 If you have irreproducible display problems, put those two expressions
Dave Love <fx@gnu.org>
parents:
diff changeset
391 in your ~/.emacs file. When the problem happens, exit the Emacs that
Dave Love <fx@gnu.org>
parents:
diff changeset
392 you were running, kill it, and rename the two files. Then you can start
Dave Love <fx@gnu.org>
parents:
diff changeset
393 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
394
9b989029cccf Add note aboute using `inverse-video' to detect excessive screen redraw.
Miles Bader <miles@gnu.org>
parents: 32523
diff changeset
395 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
396 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
397 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
398 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
399
37509
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
400 The Emacs display code includes special debugging code, but it is
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
401 normally disabled. You can enable it by building Emacs with the
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
402 pre-processing symbol GLYPH_DEBUG defined. Here's one easy way,
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
403 suitable for Unix and GNU systems, to build such a debugging version:
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
404
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
405 MYCPPFLAGS='-DGLYPH_DEBUG=1' make
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
406
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
407 Building Emacs like that activates many assertions which scrutinize
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
408 display code operation more than Emacs does normally. (To see the
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
409 code which tests these assertions, look for calls to the `xassert'
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
410 macros.) Any assertion that is reported to fail should be
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
411 investigated.
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
412
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
413 Building with GLYPH_DEBUG defined also defines several helper
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
414 functions which can help debugging display code. One such function is
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
415 `dump_glyph_matrix'. If you run Emacs under GDB, you can print the
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
416 contents of any glyph matrix by just calling that function with the
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
417 matrix as its argument. For example, the following command will print
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
418 the contents of the current matrix of the window whose pointer is in
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
419 `w':
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
420
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
421 (gdb) p dump_glyph_matrix (w->current_matrix, 2)
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
422
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
423 (The second argument 2 tells dump_glyph_matrix to print the glyphs in
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
424 a long form.) You can dump the selected window's current glyph matrix
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
425 interactively with "M-x dump-glyph-matrix RET"; see the documentation
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
426 of this function for more details.
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
427
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
428 Several more functions for debugging display code are available in
37565
77f4666fdd04 Fix last change.
Eli Zaretskii <eliz@gnu.org>
parents: 37534
diff changeset
429 Emacs compiled with GLYPH_DEBUG defined; type "C-h f dump- TAB" and
77f4666fdd04 Fix last change.
Eli Zaretskii <eliz@gnu.org>
parents: 37534
diff changeset
430 "C-h f trace- TAB" to see the full list.
37509
ed5dca63a0ed Document some of the facilities for debugging display code, including
Eli Zaretskii <eliz@gnu.org>
parents: 37481
diff changeset
431
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
432
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
433 ** Debugging LessTif
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
434
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
435 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
436 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
437 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
438 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
439 For instance
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
440
36625
08aed53e171c DEBUGSOURCES should contain a list of files, separated by colons.
Gerd Moellmann <gerd@gnu.org>
parents: 35861
diff changeset
441 export DEBUGSOURCES="RowColumn.c:MenuShell.c:MenuUtil.c"
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
442 export DEBUG_FILE=/usr/tmp/LESSTIF_TRACE
35720
c6ae90d82552 Clarify the instructions for debugging LessTif.
Eli Zaretskii <eliz@gnu.org>
parents: 35655
diff changeset
443 emacs &
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
444
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
445 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
446 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
447 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
448 last line above.
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
449
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
450 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
451 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
452 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
453 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
454
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
455
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
456 ** Debugging problems which happen in GC
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
457
37015
f8dd0e40dc34 Make it clear that last_marked[] holds pointers to Lisp objects, not
Eli Zaretskii <eliz@gnu.org>
parents: 36962
diff changeset
458 The array `last_marked' (defined on alloc.c) can be used to display up
f8dd0e40dc34 Make it clear that last_marked[] holds pointers to Lisp objects, not
Eli Zaretskii <eliz@gnu.org>
parents: 36962
diff changeset
459 to 500 last objects marked by the garbage collection process.
37076
ec5579aad1bb Fix the wording in the last change.
Eli Zaretskii <eliz@gnu.org>
parents: 37015
diff changeset
460 Whenever the garbage collector marks a Lisp object, it records the
ec5579aad1bb Fix the wording in the last change.
Eli Zaretskii <eliz@gnu.org>
parents: 37015
diff changeset
461 pointer to that object in the `last_marked' array. The variable
37015
f8dd0e40dc34 Make it clear that last_marked[] holds pointers to Lisp objects, not
Eli Zaretskii <eliz@gnu.org>
parents: 36962
diff changeset
462 `last_marked_index' holds the index into the `last_marked' array one
f8dd0e40dc34 Make it clear that last_marked[] holds pointers to Lisp objects, not
Eli Zaretskii <eliz@gnu.org>
parents: 36962
diff changeset
463 place beyond where the pointer to the very last marked object is
f8dd0e40dc34 Make it clear that last_marked[] holds pointers to Lisp objects, not
Eli Zaretskii <eliz@gnu.org>
parents: 36962
diff changeset
464 stored.
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
465
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
466 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
467 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
468 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
469 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
470 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
471 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
472 that objects were marked.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
473
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
474 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
475 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
476 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
477
37481
7121f840504e Document byte-debug-flag.
Eli Zaretskii <eliz@gnu.org>
parents: 37333
diff changeset
478 ** Debugging problems with non-ASCII characters
7121f840504e Document byte-debug-flag.
Eli Zaretskii <eliz@gnu.org>
parents: 37333
diff changeset
479
7121f840504e Document byte-debug-flag.
Eli Zaretskii <eliz@gnu.org>
parents: 37333
diff changeset
480 If you experience problems which seem to be related to non-ASCII
7121f840504e Document byte-debug-flag.
Eli Zaretskii <eliz@gnu.org>
parents: 37333
diff changeset
481 characters, such as \201 characters appearing in the buffer or in your
7121f840504e Document byte-debug-flag.
Eli Zaretskii <eliz@gnu.org>
parents: 37333
diff changeset
482 files, set the variable byte-debug-flag to t. This causes Emacs to do
7121f840504e Document byte-debug-flag.
Eli Zaretskii <eliz@gnu.org>
parents: 37333
diff changeset
483 some extra checks, such as look for broken relations between byte and
7121f840504e Document byte-debug-flag.
Eli Zaretskii <eliz@gnu.org>
parents: 37333
diff changeset
484 character positions in buffers and strings; the resulting diagnostics
7121f840504e Document byte-debug-flag.
Eli Zaretskii <eliz@gnu.org>
parents: 37333
diff changeset
485 might pinpoint the cause of the problem.
7121f840504e Document byte-debug-flag.
Eli Zaretskii <eliz@gnu.org>
parents: 37333
diff changeset
486
40247
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
487 ** Debugging the TTY (non-windowed) version
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
488
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
489 The most convenient method of debugging the character-terminal display
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
490 is to do that on a window system such as X. Begin by starting an
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
491 xterm window, then type these commands inside that window:
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
492
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
493 $ tty
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
494 $ echo $TERM
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
495
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
496 Let's say these commands print "/dev/ttyp4" and "xterm", respectively.
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
497
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
498 Now start Emacs (the normal, windowed-display session, i.e. without
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
499 the `-nw' option), and invoke "M-x gdb RET emacs RET" from there. Now
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
500 type these commands at GDB's prompt:
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
501
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
502 (gdb) set args -nw -t /dev/ttyp4
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
503 (gdb) set environment TERM xterm
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
504 (gdb) run
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
505
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
506 The debugged Emacs should now start in no-window mode with its display
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
507 directed to the xterm window you opened above.
c824be0e27e2 Add information about debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 37586
diff changeset
508
40348
380d8f312f3a Mention that screen(1) can come in handy for debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 40247
diff changeset
509 Similar arrangement is possible on a character terminal by using the
380d8f312f3a Mention that screen(1) can come in handy for debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 40247
diff changeset
510 `screen' package.
380d8f312f3a Mention that screen(1) can come in handy for debugging the tty version.
Eli Zaretskii <eliz@gnu.org>
parents: 40247
diff changeset
511
37586
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
512 ** Running Emacs built with malloc debugging packages
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
513
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
514 If Emacs exhibits bugs that seem to be related to use of memory
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
515 allocated off the heap, it might be useful to link Emacs with a
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
516 special debugging library, such as Electric Fence (a.k.a. efence) or
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
517 GNU Checker, which helps find such problems.
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
518
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
519 Emacs compiled with such packages might not run without some hacking,
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
520 because Emacs replaces the system's memory allocation functions with
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
521 its own versions, and because the dumping process might be
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
522 incompatible with the way these packages use to track allocated
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
523 memory. Here are some of the changes you might find necessary
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
524 (SYSTEM-NAME and MACHINE-NAME are the names of your OS- and
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
525 CPU-specific headers in the subdirectories of `src'):
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
526
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
527 - In src/s/SYSTEM-NAME.h add "#define SYSTEM_MALLOC".
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
528
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
529 - In src/m/MACHINE-NAME.h add "#define CANNOT_DUMP" and
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
530 "#define CANNOT_UNEXEC".
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
531
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
532 - Configure with a different --prefix= option. If you use GCC,
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
533 version 2.7.2 is preferred, as some malloc debugging packages
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
534 work a lot better with it than with 2.95 or later versions.
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
535
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
536 - Type "make" then "make -k install".
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
537
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
538 - If required, invoke the package-specific command to prepare
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
539 src/temacs for execution.
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
540
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
541 - cd ..; src/temacs
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
542
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
543 (Note that this runs `temacs' instead of the usual `emacs' executable.
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
544 This avoids problems with dumping Emacs mentioned above.)
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
545
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
546 Some malloc debugging libraries might print lots of false alarms for
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
547 bitfields used by Emacs in some data structures. If you want to get
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
548 rid of the false alarms, you will have to hack the definitions of
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
549 these data structures on the respective headers to remove the `:N'
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
550 bitfield definitions (which will cause each such field to use a full
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
551 int).
c4354368031e Add hints for running Emacs with malloc debuggers.
Eli Zaretskii <eliz@gnu.org>
parents: 37565
diff changeset
552
35655
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
553 ** 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
554
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
555 (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
556
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
557 To debug Emacs with Microsoft Visual C++, you either start emacs from
37333
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
558 the debugger or attach the debugger to a running emacs process.
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
559
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
560 To start emacs from the debugger, you can use the file bin/debug.bat.
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
561 The Microsoft Developer studio will start and under Project, Settings,
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
562 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
563 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
564 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
565 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
566 soon as a breakpoint is hit.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
567
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
568 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
569 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
570 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
571 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
572 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
573 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
574 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
575 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
576 breakpoint is hit.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
577
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
578 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
579 '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
580 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
581 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
582 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
583 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
584 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
585 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
586 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
587 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
588 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
589 'debug_print'.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
590
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
591 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
592 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
593 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
594 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
595 `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
596 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
597 "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
598 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
599
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
600 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
601 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
602 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
603 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
604 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
605
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
606 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
607 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
608 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
609 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
610 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
611 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
612 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
613 threads.
c3ac662ac2a3 Expand and update, based on the instructions to
Eli Zaretskii <eliz@gnu.org>
parents: 34594
diff changeset
614
35791
7c5f4564ff27 Changes, clean-ups, and typo fixes from Richard Stallman.
Eli Zaretskii <eliz@gnu.org>
parents: 35720
diff changeset
615 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
616 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
617 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
618 watch (struct Lisp_Symbol *) (0xfffffff & args[0]).
37333
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
619
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
620 Optimizations often confuse the MS debugger. For example, the
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
621 debugger will sometimes report wrong line numbers, e.g., when it
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
622 prints the backtrace for a crash. It is usually best to look at the
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
623 disassembly to determine exactly what code is being run--the
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
624 disassembly will probably show several source lines followed by a
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
625 block of assembler for those lines. The actual point where Emacs
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
626 crashes will be one of those source lines, but not neccesarily the one
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
627 that the debugger reports.
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
628
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
629 Another problematic area with the MS debugger is with variables that
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
630 are stored in registers: it will sometimes display wrong values for
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
631 those variables. Usually you will not be able to see any value for a
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
632 register variable, but if it is only being stored in a register
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
633 temporarily, you will see an old value for it. Again, you need to
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
634 look at the disassembly to determine which registers are being used,
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
635 and look at those registers directly, to see the actual current values
54ec1bffae34 Document problems with MS debugger working on optimized code.
Eli Zaretskii <eliz@gnu.org>
parents: 37157
diff changeset
636 of these variables.