Commit | Line | Data |
---|---|---|
6bf7aab6 | 1 | @c This is part of the Emacs manual. |
ba318903 | 2 | @c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2014 Free Software |
ab422c4d | 3 | @c Foundation, Inc. |
6bf7aab6 DL |
4 | @c See file emacs.texi for copying conditions. |
5 | @iftex | |
6 | @chapter Dealing with Common Problems | |
7 | ||
8 | If you type an Emacs command you did not intend, the results are often | |
9 | mysterious. This chapter tells what you can do to cancel your mistake or | |
10 | recover from a mysterious situation. Emacs bugs and system crashes are | |
11 | also considered. | |
12 | @end iftex | |
13 | ||
0d6e9754 LT |
14 | @ifnottex |
15 | @raisesections | |
16 | @end ifnottex | |
17 | ||
d43f5a42 | 18 | @node Quitting |
6bf7aab6 DL |
19 | @section Quitting and Aborting |
20 | @cindex quitting | |
21 | ||
22 | @table @kbd | |
23 | @item C-g | |
d7e9a7f8 | 24 | @itemx C-@key{Break} @r{(MS-DOS only)} |
ab26d9a1 | 25 | Quit: cancel running or partially typed command. |
6bf7aab6 DL |
26 | @item C-] |
27 | Abort innermost recursive editing level and cancel the command which | |
28 | invoked it (@code{abort-recursive-edit}). | |
29 | @item @key{ESC} @key{ESC} @key{ESC} | |
30 | Either quit or abort, whichever makes sense (@code{keyboard-escape-quit}). | |
31 | @item M-x top-level | |
32 | Abort all recursive editing levels that are currently executing. | |
b2a42eb7 CY |
33 | @item C-/ |
34 | @itemx C-x u | |
35 | @itemx C-_ | |
6bf7aab6 DL |
36 | Cancel a previously made change in the buffer contents (@code{undo}). |
37 | @end table | |
38 | ||
21c80203 RS |
39 | There are two ways of canceling a command before it has finished: |
40 | @dfn{quitting} with @kbd{C-g}, and @dfn{aborting} with @kbd{C-]} or | |
41 | @kbd{M-x top-level}. Quitting cancels a partially typed command, or | |
42 | one which is still running. Aborting exits a recursive editing level | |
c61ab18c CY |
43 | and cancels the command that invoked the recursive edit |
44 | (@pxref{Recursive Edit}). | |
6bf7aab6 DL |
45 | |
46 | @cindex quitting | |
47 | @kindex C-g | |
21c80203 | 48 | Quitting with @kbd{C-g} is the way to get rid of a partially typed |
3afc838f CY |
49 | command, or a numeric argument that you don't want. Furthermore, if |
50 | you are in the middle of a command that is running, @kbd{C-g} stops | |
51 | the command in a relatively safe way. For example, if you quit out of | |
52 | a kill command that is taking a long time, either your text will | |
53 | @emph{all} still be in the buffer, or it will @emph{all} be in the | |
54 | kill ring, or maybe both. If the region is active, @kbd{C-g} | |
55 | deactivates the mark, unless Transient Mark mode is off | |
e1a3f5b1 | 56 | (@pxref{Disabled Transient Mark}). If you are in the middle of an |
c61ab18c | 57 | incremental search, @kbd{C-g} behaves specially; it may take two |
e1a3f5b1 CY |
58 | successive @kbd{C-g} characters to get out of a search. |
59 | @xref{Incremental Search}, for details. | |
6bf7aab6 | 60 | |
d7e9a7f8 | 61 | On MS-DOS, the character @kbd{C-@key{Break}} serves as a quit character |
6bf7aab6 DL |
62 | like @kbd{C-g}. The reason is that it is not feasible, on MS-DOS, to |
63 | recognize @kbd{C-g} while a command is running, between interactions | |
64 | with the user. By contrast, it @emph{is} feasible to recognize | |
d7e9a7f8 | 65 | @kbd{C-@key{Break}} at all times. |
92d05762 EZ |
66 | @iftex |
67 | @xref{MS-DOS Keyboard,,,emacs-xtra, Specialized Emacs Features}. | |
68 | @end iftex | |
69 | @ifnottex | |
70 | @xref{MS-DOS Keyboard}. | |
71 | @end ifnottex | |
72 | ||
ab26d9a1 | 73 | @findex keyboard-quit |
6bf7aab6 DL |
74 | @kbd{C-g} works by setting the variable @code{quit-flag} to @code{t} |
75 | the instant @kbd{C-g} is typed; Emacs Lisp checks this variable | |
21c80203 | 76 | frequently, and quits if it is non-@code{nil}. @kbd{C-g} is only |
6bf7aab6 | 77 | actually executed as a command if you type it while Emacs is waiting for |
ab26d9a1 | 78 | input. In that case, the command it runs is @code{keyboard-quit}. |
6bf7aab6 | 79 | |
3b6f40c5 RS |
80 | On a text terminal, if you quit with @kbd{C-g} a second time before |
81 | the first @kbd{C-g} is recognized, you activate the ``emergency | |
82 | escape'' feature and return to the shell. @xref{Emergency Escape}. | |
6bf7aab6 DL |
83 | |
84 | @cindex NFS and quitting | |
21c80203 RS |
85 | There are some situations where you cannot quit. When Emacs is |
86 | waiting for the operating system to do something, quitting is | |
87 | impossible unless special pains are taken for the particular system | |
88 | call within Emacs where the waiting occurs. We have done this for the | |
89 | system calls that users are likely to want to quit from, but it's | |
a80859d4 | 90 | possible you will encounter a case not handled. In one very common |
21c80203 RS |
91 | case---waiting for file input or output using NFS---Emacs itself knows |
92 | how to quit, but many NFS implementations simply do not allow user | |
93 | programs to stop waiting for NFS when the NFS server is hung. | |
6bf7aab6 DL |
94 | |
95 | @cindex aborting recursive edit | |
96 | @findex abort-recursive-edit | |
97 | @kindex C-] | |
98 | Aborting with @kbd{C-]} (@code{abort-recursive-edit}) is used to get | |
99 | out of a recursive editing level and cancel the command which invoked | |
100 | it. Quitting with @kbd{C-g} does not do this, and could not do this, | |
101 | because it is used to cancel a partially typed command @emph{within} the | |
102 | recursive editing level. Both operations are useful. For example, if | |
103 | you are in a recursive edit and type @kbd{C-u 8} to enter a numeric | |
104 | argument, you can cancel that argument with @kbd{C-g} and remain in the | |
105 | recursive edit. | |
106 | ||
107 | @findex keyboard-escape-quit | |
108 | @kindex ESC ESC ESC | |
21c80203 RS |
109 | The sequence @kbd{@key{ESC} @key{ESC} @key{ESC}} |
110 | (@code{keyboard-escape-quit}) can either quit or abort. (We defined | |
111 | it this way because @key{ESC} means ``get out'' in many PC programs.) | |
112 | It can cancel a prefix argument, clear a selected region, or get out | |
113 | of a Query Replace, like @kbd{C-g}. It can get out of the minibuffer | |
114 | or a recursive edit, like @kbd{C-]}. It can also get out of splitting | |
115 | the frame into multiple windows, as with @kbd{C-x 1}. One thing it | |
116 | cannot do, however, is stop a command that is running. That's because | |
117 | it executes as an ordinary command, and Emacs doesn't notice it until | |
118 | it is ready for the next command. | |
6bf7aab6 DL |
119 | |
120 | @findex top-level | |
2e606829 CY |
121 | The command @kbd{M-x top-level} is equivalent to ``enough'' |
122 | @kbd{C-]} commands to get you out of all the levels of recursive edits | |
123 | that you are in; it also exits the minibuffer if it is active. | |
124 | @kbd{C-]} gets you out one level at a time, but @kbd{M-x top-level} | |
125 | goes out all levels at once. Both @kbd{C-]} and @kbd{M-x top-level} | |
126 | are like all other commands, and unlike @kbd{C-g}, in that they take | |
127 | effect only when Emacs is ready for a command. @kbd{C-]} is an | |
128 | ordinary key and has its meaning only because of its binding in the | |
6bf7aab6 DL |
129 | keymap. @xref{Recursive Edit}. |
130 | ||
b2a42eb7 | 131 | @kbd{C-/} (@code{undo}) is not strictly speaking a way of canceling |
6bf7aab6 | 132 | a command, but you can think of it as canceling a command that already |
b2a42eb7 CY |
133 | finished executing. @xref{Undo}, for more information about the undo |
134 | facility. | |
6bf7aab6 | 135 | |
abb9615e | 136 | @node Lossage |
6bf7aab6 | 137 | @section Dealing with Emacs Trouble |
a419eaa7 | 138 | @cindex troubleshooting Emacs |
6bf7aab6 | 139 | |
c61ab18c CY |
140 | This section describes how to recognize and deal with situations in |
141 | which Emacs does not work as you expect, such as keyboard code mixups, | |
142 | garbled displays, running out of memory, and crashes and hangs. | |
143 | ||
144 | @xref{Bugs}, for what to do when you think you have found a bug in | |
145 | Emacs. | |
6bf7aab6 DL |
146 | |
147 | @menu | |
84c1f5fe | 148 | * DEL Does Not Delete:: What to do if @key{DEL} doesn't delete. |
82f6ab38 EZ |
149 | * Stuck Recursive:: `[...]' in mode line around the parentheses. |
150 | * Screen Garbled:: Garbage on the screen. | |
151 | * Text Garbled:: Garbage in the text. | |
82f6ab38 | 152 | * Memory Full:: How to cope when you run out of memory. |
cf29dd84 | 153 | * Crashing:: What Emacs does when it crashes. |
82f6ab38 | 154 | * After a Crash:: Recovering editing in an Emacs session that crashed. |
c61ab18c | 155 | * Emergency Escape:: What to do if Emacs stops responding. |
6bf7aab6 DL |
156 | @end menu |
157 | ||
82f6ab38 | 158 | @node DEL Does Not Delete |
6bf7aab6 | 159 | @subsection If @key{DEL} Fails to Delete |
7be352a8 RS |
160 | @cindex @key{DEL} vs @key{BACKSPACE} |
161 | @cindex @key{BACKSPACE} vs @key{DEL} | |
a419eaa7 | 162 | @cindex @key{DEL} does not delete |
7be352a8 | 163 | |
d7e9a7f8 | 164 | Every keyboard has a large key, usually labeled @key{BACKSPACE}, |
b2a42eb7 | 165 | which is ordinarily used to erase the last character that you typed. |
c61ab18c | 166 | In Emacs, this key is supposed to be equivalent to @key{DEL}. |
7be352a8 | 167 | |
aa929821 | 168 | When Emacs starts up on a graphical display, it determines |
b2a42eb7 | 169 | automatically which key should be @key{DEL}. In some unusual cases, |
d7e9a7f8 | 170 | Emacs gets the wrong information from the system, and @key{BACKSPACE} |
c61ab18c | 171 | ends up deleting forwards instead of backwards. |
7be352a8 | 172 | |
b2a42eb7 | 173 | Some keyboards also have a @key{Delete} key, which is ordinarily |
522ddc9f JB |
174 | used to delete forwards. If this key deletes backward in Emacs, that |
175 | too suggests Emacs got the wrong information---but in the opposite | |
176 | sense. | |
cdf648ca | 177 | |
d7e9a7f8 | 178 | On a text terminal, if you find that @key{BACKSPACE} prompts for a |
0be641c0 | 179 | Help command, like @kbd{Control-h}, instead of deleting a character, |
d7e9a7f8 | 180 | it means that key is actually sending the @samp{BS} character. Emacs |
0be641c0 | 181 | ought to be treating @key{BS} as @key{DEL}, but it isn't. |
7be352a8 | 182 | |
c61ab18c | 183 | @findex normal-erase-is-backspace-mode |
7be352a8 | 184 | In all of those cases, the immediate remedy is the same: use the |
405d5e63 RS |
185 | command @kbd{M-x normal-erase-is-backspace-mode}. This toggles |
186 | between the two modes that Emacs supports for handling @key{DEL}, so | |
21c80203 | 187 | if Emacs starts in the wrong mode, this should switch to the right |
0be641c0 CY |
188 | mode. On a text terminal, if you want to ask for help when @key{BS} |
189 | is treated as @key{DEL}, use @key{F1}; @kbd{C-?} may also work, if it | |
190 | sends character code 127. | |
7be352a8 | 191 | |
c61ab18c CY |
192 | To fix the problem in every Emacs session, put one of the following |
193 | lines into your initialization file (@pxref{Init File}). For the | |
d7e9a7f8 EZ |
194 | first case above, where @key{BACKSPACE} deletes forwards instead of |
195 | backwards, use this line to make @key{BACKSPACE} act as @key{DEL}: | |
7be352a8 RS |
196 | |
197 | @lisp | |
198 | (normal-erase-is-backspace-mode 0) | |
199 | @end lisp | |
200 | ||
201 | @noindent | |
b2a42eb7 | 202 | For the other two cases, use this line: |
7be352a8 RS |
203 | |
204 | @lisp | |
205 | (normal-erase-is-backspace-mode 1) | |
206 | @end lisp | |
207 | ||
208 | @vindex normal-erase-is-backspace | |
209 | Another way to fix the problem for every Emacs session is to | |
210 | customize the variable @code{normal-erase-is-backspace}: the value | |
211 | @code{t} specifies the mode where @key{BS} or @key{BACKSPACE} is | |
212 | @key{DEL}, and @code{nil} specifies the other mode. @xref{Easy | |
213 | Customization}. | |
6bf7aab6 DL |
214 | |
215 | @node Stuck Recursive | |
216 | @subsection Recursive Editing Levels | |
a419eaa7 EZ |
217 | @cindex stuck in recursive editing |
218 | @cindex recursive editing, cannot exit | |
6bf7aab6 DL |
219 | |
220 | Recursive editing levels are important and useful features of Emacs, but | |
aa929821 | 221 | they can seem like malfunctions if you do not understand them. |
6bf7aab6 | 222 | |
c61ab18c CY |
223 | If the mode line has square brackets @samp{[@dots{}]} around the |
224 | parentheses that contain the names of the major and minor modes, you | |
225 | have entered a recursive editing level. If you did not do this on | |
226 | purpose, or if you don't understand what that means, you should just | |
227 | get out of the recursive editing level. To do so, type @kbd{M-x | |
228 | top-level}. @xref{Recursive Edit}. | |
6bf7aab6 DL |
229 | |
230 | @node Screen Garbled | |
231 | @subsection Garbage on the Screen | |
a419eaa7 EZ |
232 | @cindex garbled display |
233 | @cindex display, incorrect | |
234 | @cindex screen display, wrong | |
6bf7aab6 | 235 | |
3b6f40c5 RS |
236 | If the text on a text terminal looks wrong, the first thing to do is |
237 | see whether it is wrong in the buffer. Type @kbd{C-l} to redisplay | |
238 | the entire screen. If the screen appears correct after this, the | |
239 | problem was entirely in the previous screen update. (Otherwise, see | |
240 | the following section.) | |
6bf7aab6 | 241 | |
21c80203 RS |
242 | Display updating problems often result from an incorrect terminfo |
243 | entry for the terminal you are using. The file @file{etc/TERMS} in | |
244 | the Emacs distribution gives the fixes for known problems of this | |
245 | sort. @file{INSTALL} contains general advice for these problems in | |
c61ab18c CY |
246 | one of its sections. If you seem to be using the right terminfo |
247 | entry, it is possible that there is a bug in the terminfo entry, or a | |
248 | bug in Emacs that appears for certain terminal types. | |
6bf7aab6 DL |
249 | |
250 | @node Text Garbled | |
251 | @subsection Garbage in the Text | |
a419eaa7 EZ |
252 | @cindex garbled text |
253 | @cindex buffer text garbled | |
6bf7aab6 | 254 | |
21c80203 RS |
255 | If @kbd{C-l} shows that the text is wrong, first type @kbd{C-h l} to |
256 | see what commands you typed to produce the observed results. Then try | |
257 | undoing the changes step by step using @kbd{C-x u}, until it gets back | |
258 | to a state you consider correct. | |
6bf7aab6 DL |
259 | |
260 | If a large portion of text appears to be missing at the beginning or | |
261 | end of the buffer, check for the word @samp{Narrow} in the mode line. | |
262 | If it appears, the text you don't see is probably still present, but | |
263 | temporarily off-limits. To make it accessible again, type @kbd{C-x n | |
264 | w}. @xref{Narrowing}. | |
265 | ||
6bf7aab6 DL |
266 | @node Memory Full |
267 | @subsection Running out of Memory | |
268 | @cindex memory full | |
269 | @cindex out of memory | |
270 | ||
180ff2e5 RS |
271 | If you get the error message @samp{Virtual memory exceeded}, save |
272 | your modified buffers with @kbd{C-x s}. This method of saving them | |
273 | has the smallest need for additional memory. Emacs keeps a reserve of | |
274 | memory which it makes available when this error happens; that should | |
275 | be enough to enable @kbd{C-x s} to complete its work. When the | |
276 | reserve has been used, @samp{!MEM FULL!} appears at the beginning of | |
277 | the mode line, indicating there is no more reserve. | |
278 | ||
279 | Once you have saved your modified buffers, you can exit this Emacs | |
280 | session and start another, or you can use @kbd{M-x kill-some-buffers} | |
281 | to free space in the current Emacs job. If this frees up sufficient | |
282 | space, Emacs will refill its memory reserve, and @samp{!MEM FULL!} | |
283 | will disappear from the mode line. That means you can safely go on | |
284 | editing in the same Emacs session. | |
6bf7aab6 DL |
285 | |
286 | Do not use @kbd{M-x buffer-menu} to save or kill buffers when you run | |
cce0aa5a | 287 | out of memory, because the Buffer Menu needs a fair amount of memory |
6bf7aab6 DL |
288 | itself, and the reserve supply may not be enough. |
289 | ||
cf29dd84 PE |
290 | @node Crashing |
291 | @subsection When Emacs Crashes | |
292 | ||
4c1f6a5b | 293 | @cindex crash report |
a33da68b EZ |
294 | @cindex backtrace |
295 | @cindex @file{emacs_backtrace.txt} file, MS-Windows | |
4c1f6a5b CY |
296 | Emacs is not supposed to crash, but if it does, it produces a |
297 | @dfn{crash report} prior to exiting. The crash report is printed to | |
298 | the standard error stream. If Emacs was started from a graphical | |
a33da68b EZ |
299 | desktop on a GNU or Unix system, the standard error stream is commonly |
300 | redirected to a file such as @file{~/.xsession-errors}, so you can | |
301 | look for the crash report there. On MS-Windows, the crash report is | |
302 | written to a file named @file{emacs_backtrace.txt} in the current | |
303 | directory of the Emacs process, in addition to the standard error | |
304 | stream. | |
4c1f6a5b CY |
305 | |
306 | The format of the crash report depends on the platform. On some | |
307 | platforms, such as those using the GNU C Library, the crash report | |
308 | includes a @dfn{backtrace} describing the execution state prior to | |
309 | crashing, which can be used to help debug the crash. Here is an | |
a33da68b | 310 | example for a GNU system: |
cf29dd84 PE |
311 | |
312 | @example | |
313 | Fatal error 11: Segmentation fault | |
314 | Backtrace: | |
315 | emacs[0x5094e4] | |
316 | emacs[0x4ed3e6] | |
317 | emacs[0x4ed504] | |
318 | /lib64/libpthread.so.0[0x375220efe0] | |
319 | /lib64/libpthread.so.0(read+0xe)[0x375220e08e] | |
320 | emacs[0x509af6] | |
321 | emacs[0x5acc26] | |
4c1f6a5b | 322 | @dots{} |
cf29dd84 PE |
323 | @end example |
324 | ||
325 | @noindent | |
4c1f6a5b CY |
326 | The number @samp{11} is the system signal number corresponding to the |
327 | crash---in this case a segmentation fault. The hexadecimal numbers | |
328 | are program addresses, which can be associated with source code lines | |
329 | using a debugging tool. For example, the GDB command | |
330 | @samp{list *0x509af6} prints the source-code lines corresponding to | |
331 | the @samp{emacs[0x509af6]} entry. If your system has the | |
332 | @command{addr2line} utility, the following shell command outputs a | |
333 | backtrace with source-code line numbers: | |
58f3a196 PE |
334 | |
335 | @example | |
336 | sed -n 's/.*\[\(.*\)]$/\1/p' @var{backtrace} | | |
7f102272 | 337 | addr2line -C -f -i -p -e @var{bindir}/@var{emacs-binary} |
58f3a196 PE |
338 | @end example |
339 | ||
340 | @noindent | |
341 | Here, @var{backtrace} is the name of a text file containing a copy of | |
a33da68b EZ |
342 | the backtrace, @var{bindir} is the name of the directory that |
343 | contains the Emacs executable, and @var{emacs-binary} is the name of | |
344 | the Emacs executable file, normally @file{emacs} on GNU and Unix | |
ee271528 PE |
345 | systems and @file{emacs.exe} on MS-Windows and MS-DOS. Omit the |
346 | @option{-p} option if your version of @command{addr2line} is too old | |
347 | to have it. | |
cf29dd84 | 348 | |
4c1f6a5b | 349 | @cindex core dump |
a33da68b EZ |
350 | Optionally, Emacs can generate a @dfn{core dump} when it crashes, on |
351 | systems that support core files. A core dump is a file containing | |
352 | voluminous data about the state of the program prior to the crash, | |
d8ad4d3f | 353 | usually examined by loading it into a debugger such as GDB@. On many |
a33da68b EZ |
354 | platforms, core dumps are disabled by default, and you must explicitly |
355 | enable them by running the shell command @samp{ulimit -c unlimited} | |
d8ad4d3f | 356 | (e.g., in your shell startup script). |
4c1f6a5b | 357 | |
6bf7aab6 DL |
358 | @node After a Crash |
359 | @subsection Recovery After a Crash | |
a419eaa7 | 360 | @cindex recovering crashed session |
6bf7aab6 DL |
361 | |
362 | If Emacs or the computer crashes, you can recover the files you were | |
363 | editing at the time of the crash from their auto-save files. To do | |
364 | this, start Emacs again and type the command @kbd{M-x recover-session}. | |
365 | ||
366 | This command initially displays a buffer which lists interrupted | |
367 | session files, each with its date. You must choose which session to | |
368 | recover from. Typically the one you want is the most recent one. Move | |
369 | point to the one you choose, and type @kbd{C-c C-c}. | |
370 | ||
21c80203 RS |
371 | Then @code{recover-session} considers each of the files that you |
372 | were editing during that session; for each such file, it asks whether | |
373 | to recover that file. If you answer @kbd{y} for a file, it shows the | |
374 | dates of that file and its auto-save file, then asks once again | |
375 | whether to recover that file. For the second question, you must | |
376 | confirm with @kbd{yes}. If you do, Emacs visits the file but gets the | |
377 | text from the auto-save file. | |
6bf7aab6 DL |
378 | |
379 | When @code{recover-session} is done, the files you've chosen to | |
380 | recover are present in Emacs buffers. You should then save them. Only | |
381 | this---saving them---updates the files themselves. | |
382 | ||
615cdecf NF |
383 | As a last resort, if you had buffers with content which were not |
384 | associated with any files, or if the autosave was not recent enough to | |
385 | have recorded important changes, you can use the | |
16540869 NF |
386 | @file{etc/emacs-buffer.gdb} script with GDB (the GNU Debugger) to |
387 | retrieve them from a core dump--provided that a core dump was saved, | |
388 | and that the Emacs executable was not stripped of its debugging | |
389 | symbols. | |
390 | ||
21c80203 RS |
391 | As soon as you get the core dump, rename it to another name such as |
392 | @file{core.emacs}, so that another crash won't overwrite it. | |
393 | ||
5cf98ab4 | 394 | To use this script, run @code{gdb} with the file name of your Emacs |
1df7defd | 395 | executable and the file name of the core dump, e.g., @samp{gdb |
16540869 NF |
396 | /usr/bin/emacs core.emacs}. At the @code{(gdb)} prompt, load the |
397 | recovery script: @samp{source /usr/src/emacs/etc/emacs-buffer.gdb}. | |
5cf98ab4 RS |
398 | Then type the command @code{ybuffer-list} to see which buffers are |
399 | available. For each buffer, it lists a buffer number. To save a | |
400 | buffer, use @code{ysave-buffer}; you specify the buffer number, and | |
401 | the file name to write that buffer into. You should use a file name | |
402 | which does not already exist; if the file does exist, the script does | |
a5cecf92 | 403 | not make a backup of its old contents. |
615cdecf | 404 | |
6bf7aab6 DL |
405 | @node Emergency Escape |
406 | @subsection Emergency Escape | |
a419eaa7 | 407 | @cindex emergency escape |
6bf7aab6 | 408 | |
0be641c0 CY |
409 | On text terminals, the @dfn{emergency escape} feature suspends Emacs |
410 | immediately if you type @kbd{C-g} a second time before Emacs can | |
21c80203 RS |
411 | actually respond to the first one by quitting. This is so you can |
412 | always get out of GNU Emacs no matter how badly it might be hung. | |
413 | When things are working properly, Emacs recognizes and handles the | |
414 | first @kbd{C-g} so fast that the second one won't trigger emergency | |
415 | escape. However, if some problem prevents Emacs from handling the | |
416 | first @kbd{C-g} properly, then the second one will get you back to the | |
417 | shell. | |
6bf7aab6 | 418 | |
21c80203 RS |
419 | When you resume Emacs after a suspension caused by emergency escape, |
420 | it asks two questions before going back to what it had been doing: | |
6bf7aab6 DL |
421 | |
422 | @example | |
423 | Auto-save? (y or n) | |
424 | Abort (and dump core)? (y or n) | |
425 | @end example | |
426 | ||
427 | @noindent | |
428 | Answer each one with @kbd{y} or @kbd{n} followed by @key{RET}. | |
429 | ||
21c80203 RS |
430 | Saying @kbd{y} to @samp{Auto-save?} causes immediate auto-saving of |
431 | all modified buffers in which auto-saving is enabled. Saying @kbd{n} | |
432 | skips this. | |
433 | ||
434 | Saying @kbd{y} to @samp{Abort (and dump core)?} causes Emacs to | |
435 | crash, dumping core. This is to enable a wizard to figure out why | |
436 | Emacs was failing to quit in the first place. Execution does not | |
437 | continue after a core dump. | |
6bf7aab6 | 438 | |
21c80203 RS |
439 | If you answer this question @kbd{n}, Emacs execution resumes. With |
440 | luck, Emacs will ultimately do the requested quit. If not, each | |
441 | subsequent @kbd{C-g} invokes emergency escape again. | |
6bf7aab6 DL |
442 | |
443 | If Emacs is not really hung, just slow, you may invoke the double | |
21c80203 RS |
444 | @kbd{C-g} feature without really meaning to. Then just resume and |
445 | answer @kbd{n} to both questions, and you will get back to the former | |
446 | state. The quit you requested will happen by and by. | |
6bf7aab6 | 447 | |
58af1784 RS |
448 | Emergency escape is active only for text terminals. On graphical |
449 | displays, you can use the mouse to kill Emacs or switch to another | |
450 | program. | |
6bf7aab6 | 451 | |
d7e9a7f8 | 452 | On MS-DOS, you must type @kbd{C-@key{Break}} (twice) to cause |
21c80203 RS |
453 | emergency escape---but there are cases where it won't work, when |
454 | system call hangs or when Emacs is stuck in a tight loop in C code. | |
6bf7aab6 | 455 | |
abb9615e | 456 | @node Bugs |
6bf7aab6 DL |
457 | @section Reporting Bugs |
458 | ||
459 | @cindex bugs | |
63e1eaa1 GM |
460 | If you think you have found a bug in Emacs, please report it. We |
461 | cannot promise to fix it, or always to agree that it is a bug, but we | |
462 | certainly want to hear about it. The same applies for new features | |
463 | you would like to see added. The following sections will help you to | |
464 | construct an effective bug report. | |
9e25ea70 | 465 | |
6bf7aab6 | 466 | @menu |
63e1eaa1 | 467 | * Known Problems:: How to read about known problems and bugs. |
8838673e GM |
468 | * Criteria: Bug Criteria. Have you really found a bug? |
469 | * Understanding Bug Reporting:: How to report a bug effectively. | |
470 | * Checklist:: Steps to follow for a good bug report. | |
471 | * Sending Patches:: How to send a patch for GNU Emacs. | |
6bf7aab6 DL |
472 | @end menu |
473 | ||
63e1eaa1 GM |
474 | @node Known Problems |
475 | @subsection Reading Existing Bug Reports and Known Problems | |
476 | ||
477 | Before reporting a bug, if at all possible please check to see if it | |
478 | is already known about. Indeed, it may already have been fixed in a | |
479 | later release of Emacs, or in the development version. Here is a list | |
480 | of the main places you can read about known issues: | |
481 | ||
482 | @itemize | |
483 | @item | |
c61ab18c CY |
484 | The @file{etc/PROBLEMS} file; type @kbd{C-h C-p} to read it. This |
485 | file contains a list of particularly well-known issues that have been | |
486 | encountered in compiling, installing and running Emacs. Often, there | |
487 | are suggestions for workarounds and solutions. | |
63e1eaa1 GM |
488 | |
489 | @item | |
490 | Some additional user-level problems can be found in @ref{Bugs and | |
491 | problems, , Bugs and problems, efaq, GNU Emacs FAQ}. | |
492 | ||
c61ab18c CY |
493 | @cindex bug tracker |
494 | @item | |
495 | The GNU Bug Tracker at @url{http://debbugs.gnu.org}. Emacs bugs are | |
496 | filed in the tracker under the @samp{emacs} package. The tracker | |
497 | records information about the status of each bug, the initial bug | |
498 | report, and the follow-up messages by the bug reporter and Emacs | |
499 | developers. You can search for bugs by subject, severity, and other | |
500 | criteria. | |
501 | ||
502 | @cindex debbugs package | |
503 | Instead of browsing the bug tracker as a webpage, you can browse it | |
504 | from Emacs using the @code{debbugs} package, which can be downloaded | |
505 | via the Package Menu (@pxref{Packages}). This package provides the | |
506 | command @kbd{M-x debbugs-gnu} to list bugs, and @kbd{M-x | |
87288971 MA |
507 | debbugs-gnu-search} to search for a specific bug. User tags, applied |
508 | by the Emacs maintainers, are shown by @kbd{M-x debbugs-gnu-usertags}. | |
c61ab18c | 509 | |
63e1eaa1 GM |
510 | @item |
511 | The @samp{bug-gnu-emacs} mailing list (also available as the newsgroup | |
ae742cb5 | 512 | @samp{gnu.emacs.bug}). You can read the list archives at |
c61ab18c CY |
513 | @url{http://lists.gnu.org/mailman/listinfo/bug-gnu-emacs}. This list |
514 | works as a ``mirror'' of the Emacs bug reports and follow-up messages | |
515 | which are sent to the bug tracker. It also contains old bug reports | |
516 | from before the bug tracker was introduced (in early 2008). | |
63e1eaa1 | 517 | |
c61ab18c CY |
518 | If you like, you can subscribe to the list. Be aware that its purpose |
519 | is to provide the Emacs maintainers with information about bugs and | |
520 | feature requests, so reports may contain fairly large amounts of data; | |
521 | spectators should not complain about this. | |
63e1eaa1 GM |
522 | |
523 | @item | |
524 | The @samp{emacs-pretest-bug} mailing list. This list is no longer | |
525 | used, and is mainly of historical interest. At one time, it was used | |
526 | for bug reports in development (i.e., not yet released) versions of | |
527 | Emacs. You can read the archives for 2003 to mid 2007 at | |
c61ab18c CY |
528 | @url{http://lists.gnu.org/archive/html/emacs-pretest-bug/}. Nowadays, |
529 | it is an alias for @samp{bug-gnu-emacs}. | |
63e1eaa1 GM |
530 | |
531 | @item | |
532 | The @samp{emacs-devel} mailing list. Sometimes people report bugs to | |
533 | this mailing list. This is not the main purpose of the list, however, | |
534 | and it is much better to send bug reports to the bug list. You should | |
535 | not feel obliged to read this list before reporting a bug. | |
536 | ||
537 | @end itemize | |
538 | ||
539 | ||
6bf7aab6 DL |
540 | @node Bug Criteria |
541 | @subsection When Is There a Bug | |
a419eaa7 EZ |
542 | @cindex bug criteria |
543 | @cindex what constitutes an Emacs bug | |
6bf7aab6 | 544 | |
21c80203 RS |
545 | If Emacs accesses an invalid memory location (``segmentation |
546 | fault''), or exits with an operating system error message that | |
547 | indicates a problem in the program (as opposed to something like | |
548 | ``disk full''), then it is certainly a bug. | |
6bf7aab6 | 549 | |
c61ab18c CY |
550 | If the Emacs display does not correspond properly to the contents of |
551 | the buffer, then it is a bug. But you should check that features like | |
552 | buffer narrowing (@pxref{Narrowing}), which can hide parts of the | |
553 | buffer or change how it is displayed, are not responsible. | |
6bf7aab6 DL |
554 | |
555 | Taking forever to complete a command can be a bug, but you must make | |
c61ab18c | 556 | sure that it is really Emacs's fault. Some commands simply take a |
d7e9a7f8 | 557 | long time. Type @kbd{C-g} (@kbd{C-@key{Break}} on MS-DOS) and then |
c61ab18c CY |
558 | @kbd{C-h l} to see whether the input Emacs received was what you |
559 | intended to type; if the input was such that you @emph{know} it should | |
560 | have been processed quickly, report a bug. If you don't know whether | |
561 | the command should take a long time, find out by looking in the manual | |
562 | or by asking for assistance. | |
6bf7aab6 DL |
563 | |
564 | If a command you are familiar with causes an Emacs error message in a | |
565 | case where its usual definition ought to be reasonable, it is probably a | |
566 | bug. | |
567 | ||
c61ab18c CY |
568 | If a command does the wrong thing, that is a bug. But be sure you |
569 | know for certain what it ought to have done. If you aren't familiar | |
570 | with the command, it might actually be working right. If in doubt, | |
571 | read the command's documentation (@pxref{Name Help}). | |
6bf7aab6 | 572 | |
c61ab18c CY |
573 | A command's intended definition may not be the best possible |
574 | definition for editing with. This is a very important sort of | |
575 | problem, but it is also a matter of judgment. Also, it is easy to | |
ba3ce288 GM |
576 | come to such a conclusion out of ignorance of some of the existing |
577 | features. It is probably best not to complain about such a problem | |
578 | until you have checked the documentation in the usual ways, feel | |
579 | confident that you understand it, and know for certain that what you | |
21c80203 RS |
580 | want is not available. Ask other Emacs users, too. If you are not |
581 | sure what the command is supposed to do after a careful reading of the | |
582 | manual, check the index and glossary for any terms that may be | |
583 | unclear. | |
6bf7aab6 DL |
584 | |
585 | If after careful rereading of the manual you still do not understand | |
586 | what the command should do, that indicates a bug in the manual, which | |
587 | you should report. The manual's job is to make everything clear to | |
588 | people who are not Emacs experts---including you. It is just as | |
589 | important to report documentation bugs as program bugs. | |
590 | ||
c61ab18c | 591 | If the built-in documentation for a function or variable disagrees |
6bf7aab6 DL |
592 | with the manual, one of them must be wrong; that is a bug. |
593 | ||
594 | @node Understanding Bug Reporting | |
595 | @subsection Understanding Bug Reporting | |
a419eaa7 EZ |
596 | @cindex bug reporting |
597 | @cindex report an Emacs bug, how to | |
6bf7aab6 DL |
598 | |
599 | @findex emacs-version | |
c61ab18c CY |
600 | When you decide that there is a bug, it is important to report it |
601 | and to report it in a way which is useful. What is most useful is an | |
602 | exact description of what commands you type, starting with the shell | |
603 | command to run Emacs, until the problem happens. | |
6bf7aab6 DL |
604 | |
605 | The most important principle in reporting a bug is to report | |
c61ab18c CY |
606 | @emph{facts}. Hypotheses and verbal descriptions are no substitute |
607 | for the detailed raw data. Reporting the facts is straightforward, | |
608 | but many people strain to posit explanations and report them instead | |
609 | of the facts. If the explanations are based on guesses about how | |
610 | Emacs is implemented, they will be useless; meanwhile, lacking the | |
611 | facts, we will have no real information about the bug. If you want to | |
612 | actually @emph{debug} the problem, and report explanations that are | |
613 | more than guesses, that is useful---but please include the raw facts | |
614 | as well. | |
6bf7aab6 DL |
615 | |
616 | For example, suppose that you type @kbd{C-x C-f /glorp/baz.ugh | |
21c80203 | 617 | @key{RET}}, visiting a file which (you know) happens to be rather |
c61ab18c CY |
618 | large, and Emacs displays @samp{I feel pretty today}. The bug report |
619 | would need to provide all that information. You should not assume | |
620 | that the problem is due to the size of the file and say, ``I visited a | |
621 | large file, and Emacs displayed @samp{I feel pretty today}.'' This is | |
16152b76 | 622 | what we mean by ``guessing explanations''. The problem might be due |
c61ab18c CY |
623 | to the fact that there is a @samp{z} in the file name. If this is so, |
624 | then when we got your report, we would try out the problem with some | |
16152b76 | 625 | ``large file'', probably with no @samp{z} in its name, and not see any |
c61ab18c | 626 | problem. There is no way we could guess that we should try visiting a |
6bf7aab6 DL |
627 | file with a @samp{z} in its name. |
628 | ||
c61ab18c CY |
629 | You should not even say ``visit a file'' instead of @kbd{C-x C-f}. |
630 | Similarly, rather than saying ``if I have three characters on the | |
16152b76 | 631 | line'', say ``after I type @kbd{@key{RET} A B C @key{RET} C-p}'', if |
c61ab18c CY |
632 | that is the way you entered the text. |
633 | ||
634 | If possible, try quickly to reproduce the bug by invoking Emacs with | |
635 | @command{emacs -Q} (so that Emacs starts with no initial | |
636 | customizations; @pxref{Initial Options}), and repeating the steps that | |
637 | you took to trigger the bug. If you can reproduce the bug this way, | |
638 | that rules out bugs in your personal customizations. Then your bug | |
639 | report should begin by stating that you started Emacs with | |
640 | @command{emacs -Q}, followed by the exact sequence of steps for | |
641 | reproducing the bug. If possible, inform us of the exact contents of | |
642 | any file that is needed to reproduce the bug. | |
643 | ||
644 | Some bugs are not reproducible from @command{emacs -Q}; some are not | |
645 | easily reproducible at all. In that case, you should report what you | |
646 | have---but, as before, please stick to the raw facts about what you | |
647 | did to trigger the bug the first time. | |
6bf7aab6 | 648 | |
ad15bd74 GM |
649 | If you have multiple issues that you want to report, please make a |
650 | separate bug report for each. | |
65faed73 | 651 | |
6bf7aab6 DL |
652 | @node Checklist |
653 | @subsection Checklist for Bug Reports | |
a419eaa7 EZ |
654 | @cindex checklist before reporting a bug |
655 | @cindex bug reporting, checklist | |
63e1eaa1 GM |
656 | |
657 | Before reporting a bug, first try to see if the problem has already | |
658 | been reported (@pxref{Known Problems}). | |
659 | ||
660 | If you are able to, try the latest release of Emacs to see if the | |
661 | problem has already been fixed. Even better is to try the latest | |
662 | development version. We recognize that this is not easy for some | |
663 | people, so do not feel that you absolutely must do this before making | |
664 | a report. | |
6bf7aab6 | 665 | |
6bf7aab6 | 666 | @findex report-emacs-bug |
63e1eaa1 GM |
667 | The best way to write a bug report for Emacs is to use the command |
668 | @kbd{M-x report-emacs-bug}. This sets up a mail buffer | |
669 | (@pxref{Sending Mail}) and automatically inserts @emph{some} of the | |
670 | essential information. However, it cannot supply all the necessary | |
671 | information; you should still read and follow the guidelines below, so | |
672 | you can enter the other crucial information by hand before you send | |
673 | the message. You may feel that some of the information inserted by | |
674 | @kbd{M-x report-emacs-bug} is not relevant, but unless you are | |
675 | absolutely sure it is best to leave it, so that the developers can | |
676 | decide for themselves. | |
677 | ||
678 | When you have finished writing your report, type @kbd{C-c C-c} and it | |
2f3ac208 GM |
679 | will be sent to the Emacs maintainers at |
680 | @ifnothtml | |
681 | @email{bug-gnu-emacs@@gnu.org}. | |
682 | @end ifnothtml | |
683 | @ifhtml | |
684 | @url{http://lists.gnu.org/mailman/listinfo/bug-gnu-emacs, bug-gnu-emacs}. | |
685 | @end ifhtml | |
63e1eaa1 GM |
686 | (If you want to suggest an improvement or new feature, use the same |
687 | address.) If you cannot send mail from inside Emacs, you can copy the | |
91af9d2e | 688 | text of your report to your normal mail client (if your system |
c4af1efc | 689 | supports it, you can type @kbd{C-c M-i} to have Emacs do this for you) |
91af9d2e GM |
690 | and send it to that address. Or you can simply send an email to that |
691 | address describing the problem. | |
63e1eaa1 GM |
692 | |
693 | Your report will be sent to the @samp{bug-gnu-emacs} mailing list, and | |
c61ab18c | 694 | stored in the GNU Bug Tracker at @url{http://debbugs.gnu.org}. Please |
63e1eaa1 GM |
695 | include a valid reply email address, in case we need to ask you for |
696 | more information about your report. Submissions are moderated, so | |
697 | there may be a delay before your report appears. | |
698 | ||
c61ab18c CY |
699 | You do not need to know how the Gnu Bug Tracker works in order to |
700 | report a bug, but if you want to, you can read the tracker's online | |
701 | documentation to see the various features you can use. | |
63e1eaa1 GM |
702 | |
703 | All mail sent to the @samp{bug-gnu-emacs} mailing list is also | |
ffda048b | 704 | gatewayed to the @samp{gnu.emacs.bug} newsgroup. The reverse is also |
da3930f3 GM |
705 | true, but we ask you not to post bug reports (or replies) via the |
706 | newsgroup. It can make it much harder to contact you if we need to ask | |
707 | for more information, and it does not integrate well with the bug | |
708 | tracker. | |
63e1eaa1 GM |
709 | |
710 | If your data is more than 500,000 bytes, please don't include it | |
711 | directly in the bug report; instead, offer to send it on request, or | |
712 | make it available by ftp and say where. | |
6bf7aab6 DL |
713 | |
714 | To enable maintainers to investigate a bug, your report | |
715 | should include all these things: | |
716 | ||
717 | @itemize @bullet | |
718 | @item | |
63e1eaa1 GM |
719 | The version number of Emacs. Without this, we won't know whether there is any |
720 | point in looking for the bug in the current version of GNU Emacs. | |
6bf7aab6 | 721 | |
63e1eaa1 GM |
722 | @kbd{M-x report-emacs-bug} includes this information automatically, |
723 | but if you are not using that command for your report you can get the | |
724 | version number by typing @kbd{M-x emacs-version @key{RET}}. If that | |
725 | command does not work, you probably have something other than GNU | |
726 | Emacs, so you will have to report the bug somewhere else. | |
6bf7aab6 DL |
727 | |
728 | @item | |
729 | The type of machine you are using, and the operating system name and | |
63e1eaa1 GM |
730 | version number (again, automatically included by @kbd{M-x |
731 | report-emacs-bug}). @kbd{M-x emacs-version @key{RET}} provides this | |
1c64e6ed | 732 | information too. Copy its output from the @file{*Messages*} buffer, |
63e1eaa1 | 733 | so that you get it all and get it accurately. |
6bf7aab6 DL |
734 | |
735 | @item | |
736 | The operands given to the @code{configure} command when Emacs was | |
63e1eaa1 | 737 | installed (automatically included by @kbd{M-x report-emacs-bug}). |
6bf7aab6 DL |
738 | |
739 | @item | |
740 | A complete list of any modifications you have made to the Emacs source. | |
741 | (We may not have time to investigate the bug unless it happens in an | |
742 | unmodified Emacs. But if you've made modifications and you don't tell | |
743 | us, you are sending us on a wild goose chase.) | |
744 | ||
745 | Be precise about these changes. A description in English is not | |
746 | enough---send a context diff for them. | |
747 | ||
748 | Adding files of your own, or porting to another machine, is a | |
749 | modification of the source. | |
750 | ||
751 | @item | |
752 | Details of any other deviations from the standard procedure for installing | |
753 | GNU Emacs. | |
754 | ||
755 | @item | |
756 | The complete text of any files needed to reproduce the bug. | |
757 | ||
758 | If you can tell us a way to cause the problem without visiting any files, | |
759 | please do so. This makes it much easier to debug. If you do need files, | |
760 | make sure you arrange for us to see their exact contents. For example, it | |
21c80203 | 761 | can matter whether there are spaces at the ends of lines, or a |
6bf7aab6 DL |
762 | newline after the last line in the buffer (nothing ought to care whether |
763 | the last line is terminated, but try telling the bugs that). | |
764 | ||
765 | @item | |
c61ab18c CY |
766 | The precise commands we need to type to reproduce the bug. If at all |
767 | possible, give a full recipe for an Emacs started with the @samp{-Q} | |
768 | option (@pxref{Initial Options}). This bypasses your personal | |
769 | customizations. | |
6bf7aab6 DL |
770 | |
771 | @findex open-dribble-file | |
772 | @cindex dribble file | |
34a41968 | 773 | @cindex logging keystrokes |
63e1eaa1 | 774 | One way to record the input to Emacs precisely is to write a dribble |
fb23ecc2 LMI |
775 | file. To start the file, use the @kbd{M-x open-dribble-file |
776 | @key{RET}} command. From then on, Emacs copies all your input to the | |
50ea0f87 GM |
777 | specified dribble file until the Emacs process is killed. Be aware |
778 | that sensitive information (such as passwords) may end up recorded in | |
779 | the dribble file. | |
6bf7aab6 DL |
780 | |
781 | @item | |
782 | @findex open-termscript | |
783 | @cindex termscript file | |
60a96371 | 784 | @cindex @env{TERM} environment variable |
6bf7aab6 | 785 | For possible display bugs, the terminal type (the value of environment |
60a96371 | 786 | variable @env{TERM}), the complete termcap entry for the terminal from |
6bf7aab6 DL |
787 | @file{/etc/termcap} (since that file is not identical on all machines), |
788 | and the output that Emacs actually sent to the terminal. | |
789 | ||
790 | The way to collect the terminal output is to execute the Lisp expression | |
791 | ||
792 | @example | |
793 | (open-termscript "~/termscript") | |
794 | @end example | |
795 | ||
796 | @noindent | |
1c64e6ed | 797 | using @kbd{M-:} or from the @file{*scratch*} buffer just after |
6bf7aab6 DL |
798 | starting Emacs. From then on, Emacs copies all terminal output to the |
799 | specified termscript file as well, until the Emacs process is killed. | |
800 | If the problem happens when Emacs starts up, put this expression into | |
c61ab18c CY |
801 | your Emacs initialization file so that the termscript file will be |
802 | open when Emacs displays the screen for the first time. | |
6bf7aab6 DL |
803 | |
804 | Be warned: it is often difficult, and sometimes impossible, to fix a | |
805 | terminal-dependent bug without access to a terminal of the type that | |
21c80203 | 806 | stimulates the bug. |
6bf7aab6 | 807 | |
d527b615 | 808 | @item |
76dd3692 | 809 | If non-@acronym{ASCII} text or internationalization is relevant, the locale that |
e6830948 | 810 | was current when you started Emacs. On GNU/Linux and Unix systems, or |
892c6176 | 811 | if you use a Posix-style shell such as Bash, you can use this shell |
e6830948 | 812 | command to view the relevant values: |
d527b615 | 813 | |
520e10f5 | 814 | @smallexample |
d881eade | 815 | echo LC_ALL=$LC_ALL LC_COLLATE=$LC_COLLATE LC_CTYPE=$LC_CTYPE \ |
b72d30a7 | 816 | LC_MESSAGES=$LC_MESSAGES LC_TIME=$LC_TIME LANG=$LANG |
520e10f5 | 817 | @end smallexample |
d527b615 | 818 | |
2cd8b7f6 EZ |
819 | Alternatively, use the @command{locale} command, if your system has it, |
820 | to display your locale settings. | |
821 | ||
822 | You can use the @kbd{M-!} command to execute these commands from | |
1c64e6ed | 823 | Emacs, and then copy the output from the @file{*Messages*} buffer into |
c1cb46c7 | 824 | the bug report. Alternatively, @kbd{M-x getenv @key{RET} LC_ALL |
1ba2ce68 | 825 | @key{RET}} will display the value of @code{LC_ALL} in the echo area, and |
1c64e6ed | 826 | you can copy its output from the @file{*Messages*} buffer. |
d527b615 | 827 | |
6bf7aab6 DL |
828 | @item |
829 | A description of what behavior you observe that you believe is | |
16152b76 | 830 | incorrect. For example, ``The Emacs process gets a fatal signal'', or, |
6bf7aab6 DL |
831 | ``The resulting text is as follows, which I think is wrong.'' |
832 | ||
833 | Of course, if the bug is that Emacs gets a fatal signal, then one can't | |
834 | miss it. But if the bug is incorrect text, the maintainer might fail to | |
835 | notice what is wrong. Why leave it to chance? | |
836 | ||
837 | Even if the problem you experience is a fatal signal, you should still | |
838 | say so explicitly. Suppose something strange is going on, such as, your | |
839 | copy of the source is out of sync, or you have encountered a bug in the | |
840 | C library on your system. (This has happened!) Your copy might crash | |
841 | and the copy here might not. If you @emph{said} to expect a crash, then | |
842 | when Emacs here fails to crash, we would know that the bug was not | |
843 | happening. If you don't say to expect a crash, then we would not know | |
844 | whether the bug was happening---we would not be able to draw any | |
845 | conclusion from our observations. | |
846 | ||
ab26d9a1 RS |
847 | @item |
848 | If the bug is that the Emacs Manual or the Emacs Lisp Reference Manual | |
849 | fails to describe the actual behavior of Emacs, or that the text is | |
850 | confusing, copy in the text from the online manual which you think is | |
851 | at fault. If the section is small, just the section name is enough. | |
852 | ||
6bf7aab6 DL |
853 | @item |
854 | If the manifestation of the bug is an Emacs error message, it is | |
855 | important to report the precise text of the error message, and a | |
856 | backtrace showing how the Lisp program in Emacs arrived at the error. | |
857 | ||
858 | To get the error message text accurately, copy it from the | |
1c64e6ed | 859 | @file{*Messages*} buffer into the bug report. Copy all of it, not just |
6bf7aab6 DL |
860 | part. |
861 | ||
50556a88 | 862 | @findex toggle-debug-on-error |
68b34f99 | 863 | @pindex Edebug |
50556a88 RS |
864 | To make a backtrace for the error, use @kbd{M-x toggle-debug-on-error} |
865 | before the error happens (that is to say, you must give that command | |
21c80203 | 866 | and then make the bug happen). This causes the error to start the Lisp |
50556a88 | 867 | debugger, which shows you a backtrace. Copy the text of the |
1139b0be XF |
868 | debugger's backtrace into the bug report. @xref{Edebug,, Edebug, |
869 | elisp, the Emacs Lisp Reference Manual}, for information on debugging | |
870 | Emacs Lisp programs with the Edebug package. | |
6bf7aab6 DL |
871 | |
872 | This use of the debugger is possible only if you know how to make the | |
873 | bug happen again. If you can't make it happen again, at least copy | |
874 | the whole error message. | |
875 | ||
88ab4340 EZ |
876 | @vindex debug-on-quit |
877 | If Emacs appears to be stuck in an infinite loop or in a very long | |
878 | operation, typing @kbd{C-g} with the variable @code{debug-on-quit} | |
879 | non-@code{nil} will start the Lisp debugger and show a backtrace. | |
880 | This backtrace is useful for debugging such long loops, so if you can | |
881 | produce it, copy it into the bug report. | |
882 | ||
649f602c GM |
883 | @vindex debug-on-event |
884 | If you cannot get Emacs to respond to @kbd{C-g} (e.g., because | |
885 | @code{inhibit-quit} is set), then you can try sending the signal | |
886 | specified by @code{debug-on-event} (default SIGUSR2) from outside | |
887 | Emacs to cause it to enter the debugger. | |
888 | ||
6bf7aab6 DL |
889 | @item |
890 | Check whether any programs you have loaded into the Lisp world, | |
c61ab18c CY |
891 | including your initialization file, set any variables that may affect |
892 | the functioning of Emacs. Also, see whether the problem happens in a | |
893 | freshly started Emacs without loading your initialization file (start | |
894 | Emacs with the @code{-Q} switch to prevent loading the init files). | |
895 | If the problem does @emph{not} occur then, you must report the precise | |
896 | contents of any programs that you must load into the Lisp world in | |
897 | order to cause the problem to occur. | |
6bf7aab6 DL |
898 | |
899 | @item | |
900 | If the problem does depend on an init file or other Lisp programs that | |
901 | are not part of the standard Emacs system, then you should make sure it | |
902 | is not a bug in those programs by complaining to their maintainers | |
903 | first. After they verify that they are using Emacs in a way that is | |
904 | supposed to work, they should report the bug. | |
905 | ||
906 | @item | |
907 | If you wish to mention something in the GNU Emacs source, show the line | |
908 | of code with a few lines of context. Don't just give a line number. | |
909 | ||
910 | The line numbers in the development sources don't match those in your | |
911 | sources. It would take extra work for the maintainers to determine what | |
912 | code is in your version at a given line number, and we could not be | |
913 | certain. | |
914 | ||
915 | @item | |
916 | Additional information from a C debugger such as GDB might enable | |
917 | someone to find a problem on a machine which he does not have available. | |
918 | If you don't know how to use GDB, please read the GDB manual---it is not | |
919 | very long, and using GDB is easy. You can find the GDB distribution, | |
920 | including the GDB manual in online form, in most of the same places you | |
921 | can find the Emacs distribution. To run Emacs under GDB, you should | |
922 | switch to the @file{src} subdirectory in which Emacs was compiled, then | |
923 | do @samp{gdb emacs}. It is important for the directory @file{src} to be | |
924 | current so that GDB will read the @file{.gdbinit} file in this | |
925 | directory. | |
926 | ||
927 | However, you need to think when you collect the additional information | |
928 | if you want it to show what causes the bug. | |
929 | ||
930 | @cindex backtrace for bug reports | |
931 | For example, many people send just a backtrace, but that is not very | |
932 | useful by itself. A simple backtrace with arguments often conveys | |
933 | little about what is happening inside GNU Emacs, because most of the | |
934 | arguments listed in the backtrace are pointers to Lisp objects. The | |
935 | numeric values of these pointers have no significance whatever; all that | |
936 | matters is the contents of the objects they point to (and most of the | |
937 | contents are themselves pointers). | |
938 | ||
939 | @findex debug_print | |
940 | To provide useful information, you need to show the values of Lisp | |
941 | objects in Lisp notation. Do this for each variable which is a Lisp | |
942 | object, in several stack frames near the bottom of the stack. Look at | |
943 | the source to see which variables are Lisp objects, because the debugger | |
944 | thinks of them as integers. | |
945 | ||
946 | To show a variable's value in Lisp syntax, first print its value, then | |
947 | use the user-defined GDB command @code{pr} to print the Lisp object in | |
948 | Lisp syntax. (If you must use another debugger, call the function | |
949 | @code{debug_print} with the object as an argument.) The @code{pr} | |
950 | command is defined by the file @file{.gdbinit}, and it works only if you | |
951 | are debugging a running process (not with a core dump). | |
952 | ||
953 | To make Lisp errors stop Emacs and return to GDB, put a breakpoint at | |
954 | @code{Fsignal}. | |
955 | ||
8389e1e2 | 956 | For a short listing of Lisp functions running, type the GDB |
177c0ea7 | 957 | command @code{xbacktrace}. |
8389e1e2 | 958 | |
6bf7aab6 DL |
959 | The file @file{.gdbinit} defines several other commands that are useful |
960 | for examining the data types and contents of Lisp objects. Their names | |
961 | begin with @samp{x}. These commands work at a lower level than | |
962 | @code{pr}, and are less convenient, but they may work even when | |
963 | @code{pr} does not, such as when debugging a core dump or when Emacs has | |
964 | had a fatal signal. | |
965 | ||
878c3c90 EZ |
966 | @cindex debugging Emacs, tricks and techniques |
967 | More detailed advice and other useful techniques for debugging Emacs | |
968 | are available in the file @file{etc/DEBUG} in the Emacs distribution. | |
969 | That file also includes instructions for investigating problems | |
970 | whereby Emacs stops responding (many people assume that Emacs is | |
16152b76 | 971 | ``hung'', whereas in fact it might be in an infinite loop). |
878c3c90 | 972 | |
ac41be63 RS |
973 | To find the file @file{etc/DEBUG} in your Emacs installation, use the |
974 | directory name stored in the variable @code{data-directory}. | |
6bf7aab6 DL |
975 | @end itemize |
976 | ||
977 | Here are some things that are not necessary in a bug report: | |
978 | ||
979 | @itemize @bullet | |
980 | @item | |
981 | A description of the envelope of the bug---this is not necessary for a | |
982 | reproducible bug. | |
983 | ||
984 | Often people who encounter a bug spend a lot of time investigating | |
985 | which changes to the input file will make the bug go away and which | |
986 | changes will not affect it. | |
987 | ||
988 | This is often time-consuming and not very useful, because the way we | |
ac41be63 RS |
989 | will find the bug is by running a single example under the debugger |
990 | with breakpoints, not by pure deduction from a series of examples. | |
991 | You might as well save time by not searching for additional examples. | |
992 | It is better to send the bug report right away, go back to editing, | |
993 | and find another bug to report. | |
6bf7aab6 DL |
994 | |
995 | Of course, if you can find a simpler example to report @emph{instead} of | |
996 | the original one, that is a convenience. Errors in the output will be | |
997 | easier to spot, running under the debugger will take less time, etc. | |
998 | ||
999 | However, simplification is not vital; if you can't do this or don't have | |
1000 | time to try, please report the bug with your original test case. | |
1001 | ||
c6fcb73d RS |
1002 | @item |
1003 | A core dump file. | |
1004 | ||
1005 | Debugging the core dump might be useful, but it can only be done on | |
1006 | your machine, with your Emacs executable. Therefore, sending the core | |
1007 | dump file to the Emacs maintainers won't be useful. Above all, don't | |
1008 | include the core file in an email bug report! Such a large message | |
1009 | can be extremely inconvenient. | |
1010 | ||
6bf7aab6 DL |
1011 | @item |
1012 | A system-call trace of Emacs execution. | |
1013 | ||
1014 | System-call traces are very useful for certain special kinds of | |
1015 | debugging, but in most cases they give little useful information. It is | |
1016 | therefore strange that many people seem to think that @emph{the} way to | |
1017 | report information about a crash is to send a system-call trace. Perhaps | |
1018 | this is a habit formed from experience debugging programs that don't | |
1019 | have source code or debugging symbols. | |
1020 | ||
1021 | In most programs, a backtrace is normally far, far more informative than | |
1022 | a system-call trace. Even in Emacs, a simple backtrace is generally | |
1023 | more informative, though to give full information you should supplement | |
1024 | the backtrace by displaying variable values and printing them as Lisp | |
1025 | objects with @code{pr} (see above). | |
1026 | ||
1027 | @item | |
1028 | A patch for the bug. | |
1029 | ||
1030 | A patch for the bug is useful if it is a good one. But don't omit the | |
1031 | other information that a bug report needs, such as the test case, on the | |
1032 | assumption that a patch is sufficient. We might see problems with your | |
1033 | patch and decide to fix the problem another way, or we might not | |
1034 | understand it at all. And if we can't understand what bug you are | |
1035 | trying to fix, or why your patch should be an improvement, we mustn't | |
1036 | install it. | |
1037 | ||
62fe831c | 1038 | @ifnottex |
6bf7aab6 DL |
1039 | @xref{Sending Patches}, for guidelines on how to make it easy for us to |
1040 | understand and install your patches. | |
62fe831c | 1041 | @end ifnottex |
6bf7aab6 DL |
1042 | |
1043 | @item | |
1044 | A guess about what the bug is or what it depends on. | |
1045 | ||
1046 | Such guesses are usually wrong. Even experts can't guess right about | |
1047 | such things without first using the debugger to find the facts. | |
1048 | @end itemize | |
1049 | ||
1050 | @node Sending Patches | |
1051 | @subsection Sending Patches for GNU Emacs | |
1052 | ||
1053 | @cindex sending patches for GNU Emacs | |
1054 | @cindex patches, sending | |
1055 | If you would like to write bug fixes or improvements for GNU Emacs, | |
1056 | that is very helpful. When you send your changes, please follow these | |
1057 | guidelines to make it easy for the maintainers to use them. If you | |
1058 | don't follow these guidelines, your information might still be useful, | |
1059 | but using it will take extra work. Maintaining GNU Emacs is a lot of | |
1060 | work in the best of circumstances, and we can't keep up unless you do | |
1061 | your best to help. | |
1062 | ||
1063 | @itemize @bullet | |
1064 | @item | |
1065 | Send an explanation with your changes of what problem they fix or what | |
63e1eaa1 GM |
1066 | improvement they bring about. For a fix for an existing bug, it is |
1067 | best to reply to the relevant discussion on the @samp{bug-gnu-emacs} | |
c61ab18c CY |
1068 | list, or the bug entry in the GNU Bug Tracker at |
1069 | @url{http://debbugs.gnu.org}. Explain why your change fixes the bug. | |
6bf7aab6 DL |
1070 | |
1071 | @item | |
1072 | Always include a proper bug report for the problem you think you have | |
1073 | fixed. We need to convince ourselves that the change is right before | |
1074 | installing it. Even if it is correct, we might have trouble | |
1075 | understanding it if we don't have a way to reproduce the problem. | |
1076 | ||
1077 | @item | |
1078 | Include all the comments that are appropriate to help people reading the | |
1079 | source in the future understand why this change was needed. | |
1080 | ||
1081 | @item | |
1082 | Don't mix together changes made for different reasons. | |
1083 | Send them @emph{individually}. | |
1084 | ||
1085 | If you make two changes for separate reasons, then we might not want to | |
1086 | install them both. We might want to install just one. If you send them | |
1087 | all jumbled together in a single set of diffs, we have to do extra work | |
1088 | to disentangle them---to figure out which parts of the change serve | |
1089 | which purpose. If we don't have time for this, we might have to ignore | |
1090 | your changes entirely. | |
1091 | ||
1092 | If you send each change as soon as you have written it, with its own | |
1093 | explanation, then two changes never get tangled up, and we can consider | |
1094 | each one properly without any extra work to disentangle them. | |
1095 | ||
1096 | @item | |
1097 | Send each change as soon as that change is finished. Sometimes people | |
1098 | think they are helping us by accumulating many changes to send them all | |
1099 | together. As explained above, this is absolutely the worst thing you | |
1100 | could do. | |
1101 | ||
1102 | Since you should send each change separately, you might as well send it | |
1103 | right away. That gives us the option of installing it immediately if it | |
1104 | is important. | |
1105 | ||
1106 | @item | |
1107 | Use @samp{diff -c} to make your diffs. Diffs without context are hard | |
1108 | to install reliably. More than that, they are hard to study; we must | |
1109 | always study a patch to decide whether we want to install it. Unidiff | |
1110 | format is better than contextless diffs, but not as easy to read as | |
1111 | @samp{-c} format. | |
1112 | ||
1113 | If you have GNU diff, use @samp{diff -c -F'^[_a-zA-Z0-9$]+ *('} when | |
1114 | making diffs of C code. This shows the name of the function that each | |
1115 | change occurs in. | |
1116 | ||
1117 | @item | |
1118 | Avoid any ambiguity as to which is the old version and which is the new. | |
1119 | Please make the old version the first argument to diff, and the new | |
1120 | version the second argument. And please give one version or the other a | |
1121 | name that indicates whether it is the old version or your new changed | |
1122 | one. | |
1123 | ||
1124 | @item | |
1125 | Write the change log entries for your changes. This is both to save us | |
1126 | the extra work of writing them, and to help explain your changes so we | |
1127 | can understand them. | |
1128 | ||
1129 | The purpose of the change log is to show people where to find what was | |
1130 | changed. So you need to be specific about what functions you changed; | |
1131 | in large functions, it's often helpful to indicate where within the | |
1132 | function the change was. | |
1133 | ||
1134 | On the other hand, once you have shown people where to find the change, | |
1135 | you need not explain its purpose in the change log. Thus, if you add a | |
1136 | new function, all you need to say about it is that it is new. If you | |
1137 | feel that the purpose needs explaining, it probably does---but put the | |
1138 | explanation in comments in the code. It will be more useful there. | |
1139 | ||
21c80203 RS |
1140 | Please read the @file{ChangeLog} files in the @file{src} and |
1141 | @file{lisp} directories to see what sorts of information to put in, | |
1142 | and to learn the style that we use. @xref{Change Log}. | |
6bf7aab6 DL |
1143 | |
1144 | @item | |
1145 | When you write the fix, keep in mind that we can't install a change that | |
1146 | would break other systems. Please think about what effect your change | |
1147 | will have if compiled on another type of system. | |
1148 | ||
1149 | Sometimes people send fixes that @emph{might} be an improvement in | |
1150 | general---but it is hard to be sure of this. It's hard to install | |
1151 | such changes because we have to study them very carefully. Of course, | |
1152 | a good explanation of the reasoning by which you concluded the change | |
1153 | was correct can help convince us. | |
1154 | ||
1155 | The safest changes are changes to the configuration files for a | |
1156 | particular machine. These are safe because they can't create new bugs | |
1157 | on other machines. | |
1158 | ||
1159 | Please help us keep up with the workload by designing the patch in a | |
1160 | form that is clearly safe to install. | |
1161 | @end itemize | |
1162 | ||
412a0972 | 1163 | @c FIXME: Include the node above? |
abb9615e | 1164 | @node Contributing |
6bf7aab6 | 1165 | @section Contributing to Emacs Development |
16207c0a | 1166 | @cindex contributing to Emacs |
6bf7aab6 | 1167 | |
2f3ac208 GM |
1168 | If you would like to work on improving Emacs, please contact the maintainers at |
1169 | @ifnothtml | |
1170 | @email{emacs-devel@@gnu.org}. | |
1171 | @end ifnothtml | |
1172 | @ifhtml | |
1173 | @url{http://lists.gnu.org/mailman/listinfo/emacs-devel, the | |
1174 | emacs-devel mailing list}. | |
1175 | @end ifhtml | |
1176 | You can ask for suggested projects or suggest your own ideas. | |
6bf7aab6 DL |
1177 | |
1178 | If you have already written an improvement, please tell us about it. If | |
1179 | you have not yet started work, it is useful to contact | |
2f3ac208 GM |
1180 | @ifnothtml |
1181 | @email{emacs-devel@@gnu.org} | |
1182 | @end ifnothtml | |
1183 | @ifhtml | |
1184 | @url{http://lists.gnu.org/mailman/listinfo/emacs-devel, emacs-devel} | |
1185 | @end ifhtml | |
1186 | before you start; it might be possible to suggest ways to make your | |
1187 | extension fit in better with the rest of Emacs. | |
6bf7aab6 | 1188 | |
4f3bc373 | 1189 | The development version of Emacs can be downloaded from the |
7e17c3a2 | 1190 | repository where it is actively maintained by a group of developers. |
21c80203 RS |
1191 | See the Emacs project page |
1192 | @url{http://savannah.gnu.org/projects/emacs/} for details. | |
b656e0f4 | 1193 | |
6cdb34f3 GM |
1194 | For more information on how to contribute, see the |
1195 | @ifset WWW_GNU_ORG | |
1196 | @ifhtml | |
1197 | @url{http://gnu.org/software/emacs/CONTRIBUTE, etc/CONTRIBUTE} | |
1198 | @end ifhtml | |
1199 | @ifnothtml | |
1200 | @file{etc/CONTRIBUTE} | |
1201 | @end ifnothtml | |
1202 | @end ifset | |
1203 | @ifclear WWW_GNU_ORG | |
1204 | @file{etc/CONTRIBUTE} | |
1205 | @end ifclear | |
16207c0a GM |
1206 | file in the Emacs distribution. |
1207 | ||
abb9615e | 1208 | @node Service |
6bf7aab6 | 1209 | @section How To Get Help with GNU Emacs |
a419eaa7 EZ |
1210 | @cindex help in using Emacs |
1211 | @cindex help-gnu-emacs mailing list | |
1212 | @cindex gnu.emacs.help newsgroup | |
6bf7aab6 DL |
1213 | |
1214 | If you need help installing, using or changing GNU Emacs, there are two | |
1215 | ways to find it: | |
1216 | ||
1217 | @itemize @bullet | |
1218 | @item | |
2f3ac208 GM |
1219 | Send a message to |
1220 | @ifnothtml | |
1221 | the mailing list @email{help-gnu-emacs@@gnu.org}, | |
1222 | @end ifnothtml | |
1223 | @ifhtml | |
1224 | @url{http://lists.gnu.org/mailman/listinfo/help-gnu-emacs, the | |
1225 | help-gnu-emacs mailing list}, | |
1226 | @end ifhtml | |
1227 | or post your request on newsgroup @code{gnu.emacs.help}. (This | |
1228 | mailing list and newsgroup interconnect, so it does not matter which | |
1229 | one you use.) | |
6bf7aab6 DL |
1230 | |
1231 | @item | |
1669fab9 GM |
1232 | Look in the @uref{http://www.fsf.org/resources/service/, service |
1233 | directory} for someone who might help you for a fee. | |
6bf7aab6 | 1234 | @end itemize |
ab5796a9 | 1235 | |
0d6e9754 LT |
1236 | @ifnottex |
1237 | @lowersections | |
1238 | @end ifnottex |