1593 lines
66 KiB
Plaintext
1593 lines
66 KiB
Plaintext
@c This is part of the Emacs manual.
|
|
@c Copyright (C) 1985--1987, 1993--1995, 1997, 2001--2024 Free Software
|
|
@c Foundation, Inc.
|
|
@c See file emacs.texi for copying conditions.
|
|
@iftex
|
|
@chapter Dealing with Common Problems
|
|
|
|
If you type an Emacs command you did not intend, the results are often
|
|
mysterious. This chapter tells what you can do to cancel your mistake or
|
|
recover from a mysterious situation. Emacs bugs and system crashes are
|
|
also considered.
|
|
@end iftex
|
|
|
|
@ifnottex
|
|
@raisesections
|
|
@end ifnottex
|
|
|
|
@node Quitting
|
|
@section Quitting and Aborting
|
|
|
|
@table @kbd
|
|
@item C-g
|
|
@itemx C-@key{Break} @r{(MS-DOS only)}
|
|
Quit: cancel running or partially typed command.
|
|
@item C-]
|
|
Abort innermost recursive editing level and cancel the command which
|
|
invoked it (@code{abort-recursive-edit}).
|
|
@item @key{ESC} @key{ESC} @key{ESC}
|
|
Either quit or abort, whichever makes sense (@code{keyboard-escape-quit}).
|
|
@item M-x top-level
|
|
Abort all recursive editing levels that are currently executing.
|
|
@item C-/
|
|
@itemx C-x u
|
|
@itemx C-_
|
|
Cancel a previously made change in the buffer contents (@code{undo}).
|
|
@end table
|
|
|
|
There are two ways of canceling a command before it has finished:
|
|
@dfn{quitting} with @kbd{C-g}, and @dfn{aborting} with @kbd{C-]} or
|
|
@kbd{M-x top-level}. Quitting cancels a partially typed command, or
|
|
one which is still running. Aborting exits a recursive editing level
|
|
and cancels the command that invoked the recursive edit
|
|
(@pxref{Recursive Edit}).
|
|
|
|
@cindex quitting
|
|
@kindex C-g
|
|
Quitting with @kbd{C-g} is the way to get rid of a partially typed
|
|
command, or a numeric argument that you don't want. Furthermore, if
|
|
you are in the middle of a command that is running, @kbd{C-g} stops
|
|
the command in a relatively safe way. For example, if you quit out of
|
|
a kill command that is taking a long time, either your text will
|
|
@emph{all} still be in the buffer, or it will @emph{all} be in the
|
|
kill ring, or maybe both. If the region is active, @kbd{C-g}
|
|
deactivates the mark, unless Transient Mark mode is off
|
|
(@pxref{Disabled Transient Mark}). If you are in the middle of an
|
|
incremental search, @kbd{C-g} behaves specially; it may take two
|
|
successive @kbd{C-g} characters to get out of a search.
|
|
@xref{Incremental Search}, for details.
|
|
|
|
If you type @kbd{C-g} in a minibuffer, this quits the command that
|
|
opened that minibuffer, closing it. If that minibuffer is not the
|
|
most recently opened one (which can happen when
|
|
@code{minibuffer-follows-selected-frame} is @code{nil} (@pxref{Basic
|
|
Minibuffer})), @kbd{C-g} also closes the more recently opened ones,
|
|
quitting their associated commands, after asking you for confirmation.
|
|
|
|
On MS-DOS, the character @kbd{C-@key{Break}} serves as a quit character
|
|
like @kbd{C-g}. The reason is that it is not feasible, on MS-DOS, to
|
|
recognize @kbd{C-g} while a command is running, between interactions
|
|
with the user. By contrast, it @emph{is} feasible to recognize
|
|
@kbd{C-@key{Break}} at all times.
|
|
@iftex
|
|
@xref{MS-DOS Keyboard,,,emacs-xtra, Specialized Emacs Features}.
|
|
@end iftex
|
|
@ifnottex
|
|
@xref{MS-DOS Keyboard}.
|
|
@end ifnottex
|
|
|
|
@findex keyboard-quit
|
|
@kbd{C-g} works by setting the variable @code{quit-flag} to @code{t}
|
|
the instant @kbd{C-g} is typed; Emacs Lisp checks this variable
|
|
frequently, and quits if it is non-@code{nil}. @kbd{C-g} is only
|
|
actually executed as a command if you type it while Emacs is waiting for
|
|
input. In that case, the command it runs is @code{keyboard-quit}.
|
|
|
|
On a text terminal, if you quit with @kbd{C-g} a second time before
|
|
the first @kbd{C-g} is recognized, you activate the emergency-escape
|
|
feature and return to the shell. @xref{Emergency Escape}.
|
|
|
|
@cindex NFS and quitting
|
|
There are some situations where you cannot quit. When Emacs is
|
|
waiting for the operating system to do something, quitting is
|
|
impossible unless special pains are taken for the particular system
|
|
call within Emacs where the waiting occurs. We have done this for the
|
|
system calls that users are likely to want to quit from, but it's
|
|
possible you will encounter a case not handled. In one very common
|
|
case---waiting for file input or output using NFS---Emacs itself knows
|
|
how to quit, but many NFS implementations simply do not allow user
|
|
programs to stop waiting for NFS when the NFS server is hung.
|
|
|
|
@cindex aborting recursive edit
|
|
@findex abort-recursive-edit
|
|
@kindex C-]
|
|
Aborting with @kbd{C-]} (@code{abort-recursive-edit}) is used to get
|
|
out of a recursive editing level and cancel the command which invoked
|
|
it. Quitting with @kbd{C-g} does not do this, and could not do this,
|
|
because it is used to cancel a partially typed command @emph{within} the
|
|
recursive editing level. Both operations are useful. For example, if
|
|
you are in a recursive edit and type @kbd{C-u 8} to enter a numeric
|
|
argument, you can cancel that argument with @kbd{C-g} and remain in the
|
|
recursive edit.
|
|
|
|
@findex keyboard-escape-quit
|
|
@kindex ESC ESC ESC
|
|
The sequence @kbd{@key{ESC} @key{ESC} @key{ESC}}
|
|
(@code{keyboard-escape-quit}) can either quit or abort. (We defined
|
|
it this way because @key{ESC} means ``get out'' in many PC programs.)
|
|
It can cancel a prefix argument, clear a selected region, or get out
|
|
of a Query Replace, like @kbd{C-g}. It can get out of the minibuffer
|
|
or a recursive edit, like @kbd{C-]}. It can also get out of splitting
|
|
the frame into multiple windows, as with @kbd{C-x 1}. One thing it
|
|
cannot do, however, is stop a command that is running. That's because
|
|
it executes as an ordinary command, and Emacs doesn't notice it until
|
|
it is ready for the next command.
|
|
|
|
@findex top-level
|
|
The command @kbd{M-x top-level} is equivalent to enough
|
|
@kbd{C-]} commands to get you out of all the levels of recursive edits
|
|
that you are in; it also exits the minibuffer if it is active.
|
|
@kbd{C-]} gets you out one level at a time, but @kbd{M-x top-level}
|
|
goes out all levels at once. Both @kbd{C-]} and @kbd{M-x top-level}
|
|
are like all other commands, and unlike @kbd{C-g}, in that they take
|
|
effect only when Emacs is ready for a command. @kbd{C-]} is an
|
|
ordinary key and has its meaning only because of its binding in the
|
|
keymap. @xref{Recursive Edit}.
|
|
|
|
@kbd{C-/} (@code{undo}) is not strictly speaking a way of canceling
|
|
a command, but you can think of it as canceling a command that already
|
|
finished executing. @xref{Undo}, for more information about the undo
|
|
facility.
|
|
|
|
@node Lossage
|
|
@section Dealing with Emacs Trouble
|
|
@cindex troubleshooting Emacs
|
|
|
|
This section describes how to recognize and deal with situations in
|
|
which Emacs does not work as you expect, such as keyboard code mixups,
|
|
garbled displays, running out of memory, and crashes and hangs.
|
|
|
|
@xref{Bugs}, for what to do when you think you have found a bug in
|
|
Emacs.
|
|
|
|
@menu
|
|
* Stuck Recursive:: '[...]' in mode line around the parentheses.
|
|
* Screen Garbled:: Garbage on the screen.
|
|
* Text Garbled:: Garbage in the text.
|
|
* Memory Full:: How to cope when you run out of memory.
|
|
* Crashing:: What Emacs does when it crashes.
|
|
* After a Crash:: Recovering editing in an Emacs session that crashed.
|
|
* Emergency Escape:: What to do if Emacs stops responding.
|
|
* DEL Does Not Delete:: What to do if @key{DEL} doesn't delete.
|
|
@end menu
|
|
|
|
@node Stuck Recursive
|
|
@subsection Recursive Editing Levels
|
|
@cindex stuck in recursive editing
|
|
@cindex recursive editing, cannot exit
|
|
|
|
Recursive editing levels are important and useful features of Emacs, but
|
|
they can seem like malfunctions if you do not understand them.
|
|
|
|
If the mode line has square brackets @samp{[@dots{}]} around the
|
|
parentheses that contain the names of the major and minor modes, you
|
|
have entered a recursive editing level. If you did not do this on
|
|
purpose, or if you don't understand what that means, you should just
|
|
get out of the recursive editing level. To do so, type @kbd{M-x
|
|
top-level}. @xref{Recursive Edit}.
|
|
|
|
@node Screen Garbled
|
|
@subsection Garbage on the Screen
|
|
@cindex garbled display
|
|
@cindex display, incorrect
|
|
@cindex screen display, wrong
|
|
|
|
If the text on a text terminal looks wrong, the first thing to do is
|
|
see whether it is wrong in the buffer. Type @kbd{C-l}
|
|
(@code{recenter-top-bottom}) to redisplay the entire screen. If the
|
|
screen appears correct after this, the problem was entirely in the
|
|
previous screen update. (Otherwise, see the following section.)
|
|
|
|
Display updating problems often result from an incorrect terminfo
|
|
entry for the terminal you are using. The file @file{etc/TERMS} in
|
|
the Emacs distribution gives the fixes for known problems of this
|
|
sort. @file{INSTALL} contains general advice for these problems in
|
|
one of its sections. If you seem to be using the right terminfo
|
|
entry, it is possible that there is a bug in the terminfo entry, or a
|
|
bug in Emacs that appears for certain terminal types.
|
|
|
|
@node Text Garbled
|
|
@subsection Garbage in the Text
|
|
@cindex garbled text
|
|
@cindex buffer text garbled
|
|
|
|
If @kbd{C-l} shows that the text is wrong, first type @kbd{C-h l}
|
|
(@code{view-lossage}) to see what commands you typed to produce the
|
|
observed results. Then try undoing the changes step by step using
|
|
@kbd{C-x u} (@code{undo}), until it gets back to a state you consider
|
|
correct.
|
|
|
|
If a large portion of text appears to be missing at the beginning or
|
|
end of the buffer, check for the word @samp{Narrow} in the mode line.
|
|
If it appears, the text you don't see is probably still present, but
|
|
temporarily off-limits. To make it accessible again, type @kbd{C-x n
|
|
w} (@code{widen}). @xref{Narrowing}.
|
|
|
|
@node Memory Full
|
|
@subsection Running out of Memory
|
|
@cindex memory full
|
|
@cindex out of memory
|
|
|
|
If you get the error message @samp{Virtual memory exceeded}, save
|
|
your modified buffers with @kbd{C-x s} (@code{save-some-buffers}).
|
|
This method of saving them has the smallest need for additional
|
|
memory. Emacs keeps a reserve of memory which it makes available when
|
|
this error happens; that should be enough to enable @kbd{C-x s} to
|
|
complete its work. When the reserve has been used, @samp{!MEM FULL!}
|
|
appears at the beginning of the mode line, indicating there is no more
|
|
reserve.
|
|
|
|
Once you have saved your modified buffers, you can exit this Emacs
|
|
session and start another, or you can use @kbd{M-x kill-some-buffers}
|
|
to free space in the current Emacs job. If this frees up sufficient
|
|
space, Emacs will refill its memory reserve, and @samp{!MEM FULL!}
|
|
will disappear from the mode line. That means you can safely go on
|
|
editing in the same Emacs session.
|
|
|
|
Do not use @kbd{M-x buffer-menu} to save or kill buffers when you run
|
|
out of memory, because the Buffer Menu needs a fair amount of memory
|
|
itself, and the reserve supply may not be enough.
|
|
|
|
@cindex out of memory killer, GNU/Linux
|
|
@cindex OOM killer
|
|
On GNU/Linux systems, Emacs does not normally get notified about
|
|
out-of-memory situations; instead, the OS can kill the Emacs process
|
|
when it runs out of memory. This feature is known as the
|
|
@dfn{out-of-memory killer}, or @dfn{@acronym{OOM} killer}. When this
|
|
behavior is in effect, Emacs is unable to detect the out-of-memory
|
|
situation in time, and won't be able to let you save your buffer as
|
|
described above. However, it is possible to turn off this behavior of
|
|
the OS, and thus allow Emacs a chance to handle the out-of-memory
|
|
situation in a more useful manner, before it is killed. To do that,
|
|
become the super user, edit the file @code{/etc/sysctl.conf} to
|
|
contain the lines shown below, and then invoke the command
|
|
@w{@kbd{sysctl -p}} from the shell prompt:
|
|
|
|
@example
|
|
vm.overcommit_memory=2
|
|
vm.overcommit_ratio=0
|
|
@end example
|
|
|
|
@noindent
|
|
Please note that the above setting affects all the processes on the
|
|
system, and in general the behavior of the system under memory
|
|
pressure, not just the Emacs process alone.
|
|
|
|
@node Crashing
|
|
@subsection When Emacs Crashes
|
|
|
|
@cindex crash report
|
|
@cindex backtrace
|
|
@cindex @file{emacs_backtrace.txt} file, MS-Windows
|
|
Emacs is not supposed to crash, but if it does, it produces a
|
|
@dfn{crash report} prior to exiting. The crash report is printed to
|
|
the standard error stream. If Emacs was started from a graphical
|
|
desktop on a GNU or Unix system, the standard error stream is commonly
|
|
redirected to a file such as @file{~/.xsession-errors}, so you can
|
|
look for the crash report there. On MS-Windows, the crash report is
|
|
written to a file named @file{emacs_backtrace.txt} in the current
|
|
directory of the Emacs process, in addition to the standard error
|
|
stream.
|
|
|
|
The format of the crash report depends on the platform. On some
|
|
platforms, such as those using the GNU C Library, the crash report
|
|
includes a @dfn{backtrace} describing the execution state prior to
|
|
crashing, which can be used to help debug the crash. Here is an
|
|
example for a GNU system:
|
|
|
|
@example
|
|
Fatal error 11: Segmentation fault
|
|
Backtrace:
|
|
emacs[0x5094e4]
|
|
emacs[0x4ed3e6]
|
|
emacs[0x4ed504]
|
|
/lib64/libpthread.so.0[0x375220efe0]
|
|
/lib64/libpthread.so.0(read+0xe)[0x375220e08e]
|
|
emacs[0x509af6]
|
|
emacs[0x5acc26]
|
|
@dots{}
|
|
@end example
|
|
|
|
@noindent
|
|
The number @samp{11} is the system signal number corresponding to the
|
|
crash---in this case a segmentation fault. The hexadecimal numbers
|
|
are program addresses, which can be associated with source code lines
|
|
using a debugging tool. For example, the GDB command
|
|
@samp{list *0x509af6} prints the source-code lines corresponding to
|
|
the @samp{emacs[0x509af6]} entry. If your system has the
|
|
@command{addr2line} utility, the following shell command outputs a
|
|
backtrace with source-code line numbers:
|
|
|
|
@example
|
|
sed -n 's/.*\[\(.*\)]$/\1/p' @var{backtrace} |
|
|
addr2line -C -f -i -p -e @var{bindir}/@var{emacs-binary}
|
|
@end example
|
|
|
|
@noindent
|
|
On MS-Windows, the backtrace looks somewhat differently, for example:
|
|
|
|
@example
|
|
Backtrace:
|
|
00007ff61166a12e
|
|
00007ff611538be1
|
|
00007ff611559601
|
|
00007ff6116ce84a
|
|
00007ff9b7977ff0
|
|
@dots{}
|
|
@end example
|
|
|
|
@noindent
|
|
Therefore, the filtering via @command{sed} is not required, and the
|
|
command to show the source-code line number is
|
|
|
|
@example
|
|
addr2line -C -f -i -p -e @var{bindir}/@var{emacs-binary} < @var{backtrace}
|
|
@end example
|
|
|
|
@noindent
|
|
Here, @var{backtrace} is the name of a text file containing a copy of
|
|
the backtrace (on MS-Windows, @file{emacs_backtrace.txt} in the
|
|
directory where Emacs was started), @var{bindir} is the name of the
|
|
directory that contains the Emacs executable, and @var{emacs-binary}
|
|
is the name of the Emacs executable file, normally @file{emacs} on GNU
|
|
and Unix systems and @file{emacs.exe} on MS-Windows and MS-DOS@. Omit
|
|
the @option{-p} option if your version of @command{addr2line} is too
|
|
old to have it.
|
|
|
|
@cindex core dump
|
|
Optionally, Emacs can generate a @dfn{core dump} when it crashes, on
|
|
systems that support core files. A core dump is a file containing
|
|
voluminous data about the state of the program prior to the crash,
|
|
usually examined by loading it into a debugger such as GDB@. On many
|
|
platforms, core dumps are disabled by default, and you must explicitly
|
|
enable them by running the shell command @samp{ulimit -c unlimited}
|
|
(e.g., in your shell startup script).
|
|
|
|
@node After a Crash
|
|
@subsection Recovery After a Crash
|
|
@cindex recovering crashed session
|
|
|
|
If Emacs or the computer crashes, you can recover the files you were
|
|
editing at the time of the crash from their auto-save files. To do
|
|
this, start Emacs again and type the command @kbd{M-x recover-session}.
|
|
|
|
This command initially displays a buffer which lists interrupted
|
|
session files, each with its date. You must choose which session to
|
|
recover from. Typically the one you want is the most recent one. Move
|
|
point to the one you choose, and type @kbd{C-c C-c}.
|
|
|
|
Then @code{recover-session} considers each of the files that you
|
|
were editing during that session; for each such file, it asks whether
|
|
to recover that file. If you answer @kbd{y} for a file, it shows the
|
|
dates of that file and its auto-save file, then asks once again
|
|
whether to recover that file. For the second question, you must
|
|
confirm with @kbd{yes}. If you do, Emacs visits the file but gets the
|
|
text from the auto-save file.
|
|
|
|
When @code{recover-session} is done, the files you've chosen to
|
|
recover are present in Emacs buffers. You should then save them. Only
|
|
this---saving them---updates the files themselves.
|
|
|
|
As a last resort, if you had buffers with content which were not
|
|
associated with any files, or if the autosave was not recent enough to
|
|
have recorded important changes, you can use the
|
|
@file{etc/emacs-buffer.gdb} script with GDB (the GNU Debugger) to
|
|
retrieve them from a core dump---provided that a core dump was saved,
|
|
and that the Emacs executable was not stripped of its debugging
|
|
symbols.
|
|
|
|
As soon as you get the core dump, rename it to another name such as
|
|
@file{core.emacs}, so that another crash won't overwrite it.
|
|
|
|
To use this script, run @code{gdb} with the file name of your Emacs
|
|
executable and the file name of the core dump, e.g., @samp{gdb
|
|
/usr/bin/emacs core.emacs}. At the @code{(gdb)} prompt, load the
|
|
recovery script: @samp{source /usr/src/emacs/etc/emacs-buffer.gdb}.
|
|
Then type the command @code{ybuffer-list} to see which buffers are
|
|
available. For each buffer, it lists a buffer number. To save a
|
|
buffer, use @code{ysave-buffer}; you specify the buffer number, and
|
|
the file name to write that buffer into. You should use a file name
|
|
which does not already exist; if the file does exist, the script does
|
|
not make a backup of its old contents.
|
|
|
|
@node Emergency Escape
|
|
@subsection Emergency Escape
|
|
@cindex emergency escape
|
|
|
|
On text terminals, the @dfn{emergency escape} feature suspends Emacs
|
|
immediately if you type @kbd{C-g} a second time before Emacs can
|
|
actually respond to the first one by quitting. This is so you can
|
|
always get out of GNU Emacs no matter how badly it might be hung.
|
|
When things are working properly, Emacs recognizes and handles the
|
|
first @kbd{C-g} so fast that the second one won't trigger emergency
|
|
escape. However, if some problem prevents Emacs from handling the
|
|
first @kbd{C-g} properly, then the second one will get you back to the
|
|
shell.
|
|
|
|
When you resume Emacs after a suspension caused by emergency escape,
|
|
it reports the resumption and asks a question or two before going back
|
|
to what it had been doing:
|
|
|
|
@example
|
|
Emacs is resuming after an emergency escape.
|
|
Auto-save? (y or n)
|
|
Abort (and dump core)? (y or n)
|
|
@end example
|
|
|
|
@noindent
|
|
Answer each question with @kbd{y} or @kbd{n} followed by @key{RET}.
|
|
|
|
Saying @kbd{y} to @samp{Auto-save?} causes immediate auto-saving of
|
|
all modified buffers in which auto-saving is enabled. Saying @kbd{n}
|
|
skips this. This question is omitted if Emacs is in a state where
|
|
auto-saving cannot be done safely.
|
|
|
|
Saying @kbd{y} to @samp{Abort (and dump core)?} causes Emacs to
|
|
crash, dumping core. This is to enable a wizard to figure out why
|
|
Emacs was failing to quit in the first place. Execution does not
|
|
continue after a core dump.
|
|
|
|
If you answer this question @kbd{n}, Emacs execution resumes. With
|
|
luck, Emacs will ultimately do the requested quit. If not, each
|
|
subsequent @kbd{C-g} invokes emergency escape again.
|
|
|
|
If Emacs is not really hung, just slow, you may invoke the double
|
|
@kbd{C-g} feature without really meaning to. Then just resume and
|
|
answer @kbd{n} to both questions, and you will get back to the former
|
|
state. The quit you requested will happen by and by.
|
|
|
|
Emergency escape is active only for text terminals. On graphical
|
|
displays, you can use the mouse to kill Emacs or switch to another
|
|
program.
|
|
|
|
On MS-DOS, you must type @kbd{C-@key{Break}} (twice) to cause
|
|
emergency escape---but there are cases where it won't work, when a
|
|
system call hangs or when Emacs is stuck in a tight loop in C code.
|
|
|
|
@node DEL Does Not Delete
|
|
@subsection If @key{DEL} Fails to Delete
|
|
@cindex @key{DEL} vs @key{BACKSPACE}
|
|
@cindex @key{BACKSPACE} vs @key{DEL}
|
|
@cindex @key{DEL} does not delete
|
|
|
|
Every keyboard has a large key, usually labeled @key{BACKSPACE},
|
|
which is ordinarily used to erase the last character that you typed.
|
|
In Emacs, this key is supposed to be equivalent to @key{DEL}.
|
|
|
|
When Emacs starts up on a graphical display, it determines
|
|
automatically which key should be @key{DEL}. In some unusual cases,
|
|
Emacs gets the wrong information from the system, and @key{BACKSPACE}
|
|
ends up deleting forwards instead of backwards.
|
|
|
|
Some keyboards also have a @key{Delete} key, which is ordinarily
|
|
used to delete forwards. If this key deletes backward in Emacs, that
|
|
too suggests Emacs got the wrong information---but in the opposite
|
|
sense.
|
|
|
|
On a text terminal, if you find that @key{BACKSPACE} prompts for a
|
|
Help command, like @kbd{Control-h}, instead of deleting a character,
|
|
it means that key is actually sending the @samp{BS} character. Emacs
|
|
ought to be treating @key{BS} as @key{DEL}, but it isn't.
|
|
|
|
@findex normal-erase-is-backspace-mode
|
|
In all of those cases, the immediate remedy is the same: use the
|
|
command @kbd{M-x normal-erase-is-backspace-mode}. This toggles
|
|
between the two modes that Emacs supports for handling @key{DEL}, so
|
|
if Emacs starts in the wrong mode, this should switch to the right
|
|
mode. On a text terminal, if you want to ask for help when @key{BS}
|
|
is treated as @key{DEL}, use @key{F1} instead of @kbd{C-h}; @kbd{C-?}
|
|
may also work, if it sends character code 127.
|
|
|
|
To fix the problem in every Emacs session, put one of the following
|
|
lines into your initialization file (@pxref{Init File}). For the
|
|
first case above, where @key{BACKSPACE} deletes forwards instead of
|
|
backwards, use this line to make @key{BACKSPACE} act as @key{DEL}:
|
|
|
|
@lisp
|
|
(normal-erase-is-backspace-mode 0)
|
|
@end lisp
|
|
|
|
@noindent
|
|
For the other two cases, use this line:
|
|
|
|
@lisp
|
|
(normal-erase-is-backspace-mode 1)
|
|
@end lisp
|
|
|
|
@vindex normal-erase-is-backspace
|
|
Another way to fix the problem for every Emacs session is to
|
|
customize the variable @code{normal-erase-is-backspace}: the value
|
|
@code{t} specifies the mode where @key{BS} or @key{BACKSPACE} is
|
|
@key{DEL}, and @code{nil} specifies the other mode. @xref{Easy
|
|
Customization}.
|
|
|
|
@node Bugs
|
|
@section Reporting Bugs
|
|
|
|
@cindex bugs
|
|
If you think you have found a bug in Emacs, please report it. We
|
|
cannot promise to fix it, or always to agree that it is a bug, but we
|
|
certainly want to hear about it. The same applies for new features
|
|
you would like to see added. This section will help you to determine
|
|
whether you found a bug, and if so, construct an effective bug report.
|
|
|
|
The general procedure when you find something that could be a bug is
|
|
as follows:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
See if what you found is a known problem or a bug that was already
|
|
reported and/or fixed. @xref{Known Problems}, where you will find how
|
|
to look for known problems and bugs.
|
|
|
|
@item
|
|
If you are unsure whether the behavior you see is a bug, see @ref{Bug
|
|
Criteria}, which tells what we consider as clear bugs in Emacs.
|
|
|
|
@item
|
|
Once you decide you found a bug, see @ref{Understanding Bug
|
|
Reporting}, which helps you in describing what you see in the most
|
|
efficient manner, making our job of reproducing the issue and
|
|
investigating it easier.
|
|
|
|
@item
|
|
Next, see @ref{Checklist, Checklist for Bug Reports}, where we
|
|
describe in detail how to submit a bug report and what information to
|
|
include in it. In a nutshell, you submit a bug report via electronic
|
|
mail using the Emacs command @code{report-emacs-bug}, which assists
|
|
you in doing so. Submitting a bug report starts the process of
|
|
investigating and fixing the bug, where you will receive copies of
|
|
email messages discussing the bug, in which we might ask you to
|
|
provide more information, test possible fixes, etc.
|
|
|
|
@item
|
|
Finally, if you want to propose specific changes to Emacs, whether to
|
|
fix a bug, add a new feature, or improve our documentation, please see
|
|
@ref{Sending Patches}, for details about submitting such changes.
|
|
@end itemize
|
|
|
|
@menu
|
|
* Known Problems:: How to read about known problems and bugs.
|
|
* Criteria: Bug Criteria. Have you really found a bug?
|
|
* Understanding Bug Reporting:: How to report a bug effectively.
|
|
* Checklist:: Steps to follow for a good bug report.
|
|
* Sending Patches:: How to send a patch for GNU Emacs.
|
|
@end menu
|
|
|
|
@node Known Problems
|
|
@subsection Reading Existing Bug Reports and Known Problems
|
|
@cindex known bugs and problems
|
|
|
|
Before reporting a bug, if at all possible, please check to see if
|
|
we already know about it. Indeed, it may already have been fixed in a
|
|
later release of Emacs, or in the development version. Here is a list
|
|
of the main places you can read about known issues:
|
|
|
|
@itemize
|
|
@item
|
|
The @file{etc/PROBLEMS} file; type @kbd{C-h C-p} to read it. This
|
|
file contains a list of particularly well-known issues that have been
|
|
encountered in compiling, installing and running Emacs, with special
|
|
emphasis on issues caused by other software that cannot be easily
|
|
solved in Emacs. Often, you will find there suggestions for
|
|
workarounds and solutions.
|
|
|
|
@cindex bug tracker
|
|
@cindex issue tracker
|
|
@cindex search known bugs
|
|
@item
|
|
The GNU Bug Tracker at @url{https://debbugs.gnu.org}. Emacs bugs and
|
|
issues are filed in the tracker under the @samp{emacs} package. The
|
|
tracker records information about the status of each bug, the initial
|
|
bug report, and the follow-up messages by the bug reporter and Emacs
|
|
developers who participate in discussing and fixing the bug. You can
|
|
search for bugs by subject, severity, and other criteria. For more
|
|
complex search criteria, use
|
|
@url{https://debbugs.gnu.org/cgi/search.cgi}.
|
|
|
|
@cindex debbugs package
|
|
Instead of browsing the bug tracker as a web page, you can browse it
|
|
from Emacs using the @code{debbugs} package, which can be downloaded
|
|
via the Package Menu (@pxref{Packages}). This package provides the
|
|
command @kbd{M-x debbugs-gnu} to list bugs, and @kbd{M-x
|
|
debbugs-gnu-search} to search for a specific bug. User tags, applied
|
|
by the Emacs maintainers, are shown by @kbd{M-x debbugs-gnu-usertags}.
|
|
|
|
@item
|
|
The @samp{bug-gnu-emacs} mailing list (also available as the newsgroup
|
|
@samp{gnu.emacs.bug}). You can read the list archives at
|
|
@url{https://lists.gnu.org/mailman/listinfo/bug-gnu-emacs}. This list
|
|
works as a mirror of the Emacs bug reports and follow-up messages
|
|
which are sent to the bug tracker. It also contains old bug reports
|
|
from before the bug tracker was introduced (in early 2008).
|
|
|
|
If you like, you can subscribe to the list. Be aware that its purpose
|
|
is to provide the Emacs maintainers with information about bugs and
|
|
feature requests, so reports may contain fairly large amounts of data;
|
|
spectators should not complain about this.
|
|
|
|
@item
|
|
The @samp{emacs-pretest-bug} mailing list. This list is no longer
|
|
used, and is mainly of historical interest. At one time, it was used
|
|
for bug reports in development (i.e., not yet released) versions of
|
|
Emacs. You can read the archives for 2003 to mid 2007 at
|
|
@url{https://lists.gnu.org/r/emacs-pretest-bug/}. Nowadays,
|
|
email messages sent to this list are redirected to
|
|
@samp{bug-gnu-emacs}.
|
|
|
|
@item
|
|
The @samp{emacs-devel} mailing list. Sometimes people report bugs to
|
|
this mailing list. This is not the main purpose of the list, however,
|
|
and it is much better to send bug reports to the bug list. You should
|
|
not feel obliged to read this list before reporting a bug.
|
|
@end itemize
|
|
|
|
|
|
@node Bug Criteria
|
|
@subsection When Is There a Bug
|
|
@cindex bug criteria
|
|
@cindex what constitutes an Emacs bug
|
|
|
|
If Emacs accesses an invalid memory location (a.k.a.@:
|
|
``segmentation fault'') or exits with an operating system error
|
|
message that indicates a problem in the program (as opposed to
|
|
something like ``disk full''), then it is certainly a bug.
|
|
|
|
If the Emacs display does not correspond properly to the contents of
|
|
the buffer, then it is a bug. But you should check that features like
|
|
buffer narrowing (@pxref{Narrowing}), which can hide parts of the
|
|
buffer or change how it is displayed, are not responsible.
|
|
|
|
Taking forever to complete a command can be a bug, but you must make
|
|
sure that it is really Emacs's fault. Some commands simply take a
|
|
long time. Type @kbd{C-g} (@kbd{C-@key{Break}} on MS-DOS) and then
|
|
@kbd{C-h l} to see whether the input Emacs received was what you
|
|
intended to type; if the input was such that you @emph{know} it should
|
|
have been processed quickly, report a bug. If you don't know whether
|
|
the command should take a long time, find out by looking in the manual
|
|
or by asking for assistance.
|
|
|
|
If a command you are familiar with causes an Emacs error message in a
|
|
case where its usual definition ought to be reasonable, it is probably a
|
|
bug.
|
|
|
|
If a command does the wrong thing, that is a bug. But be sure you
|
|
know for certain what it ought to have done. If you aren't familiar
|
|
with the command, it might actually be working right. If in doubt,
|
|
read the command's documentation (@pxref{Name Help}).
|
|
|
|
A command's intended definition may not be the best possible
|
|
definition for editing with. This is a very important sort of
|
|
problem, but it is also a matter of judgment. Also, it is easy to
|
|
come to such a conclusion out of ignorance of some of the existing
|
|
features. It is probably best not to complain about such a problem
|
|
until you have checked the documentation in the usual ways, feel
|
|
confident that you understand it, and know for certain that what you
|
|
want is not available. Ask other Emacs users, too. If you are not
|
|
sure what the command is supposed to do after a careful reading of the
|
|
manual, check the index and glossary for any terms that may be
|
|
unclear.
|
|
|
|
If after careful rereading of the manual you still do not understand
|
|
what the command should do, that indicates a bug in the manual, which
|
|
you should report. The manual's job is to make everything clear to
|
|
people who are not Emacs experts---including you. It is just as
|
|
important to report documentation bugs as program bugs.
|
|
|
|
If the built-in documentation for a function or variable disagrees
|
|
with the manual, one of them must be wrong; that is a bug.
|
|
|
|
For problems with packages that are not part of Emacs, it is better
|
|
to begin by reporting them to the package developers.
|
|
|
|
@node Understanding Bug Reporting
|
|
@subsection Understanding Bug Reporting
|
|
@cindex bug reporting, principles
|
|
@cindex report an Emacs bug, how to
|
|
|
|
When you decide that there is a bug, it is important to report it,
|
|
and to report it in a way which is useful. What is most useful is an
|
|
exact description of what commands you type, starting with the shell
|
|
command to run Emacs, until the problem happens, and the effects
|
|
produced by typing those commands.
|
|
|
|
The most important principle in reporting a bug is to report
|
|
@emph{facts}. Hypotheses and verbal descriptions are no substitute
|
|
for the detailed raw data. Reporting the facts is straightforward,
|
|
but many people strain to posit explanations and report them instead
|
|
of the facts. If the explanations are based on guesses about how
|
|
Emacs is implemented, they might not be useful; meanwhile, lacking the
|
|
facts, we will have no real information about the bug. If you want to
|
|
actually @emph{debug} the problem, and report explanations that are
|
|
more than guesses, that is useful---but please include the raw facts
|
|
as well.
|
|
|
|
For example, suppose that you type @kbd{C-x C-f /glorp/baz.ugh
|
|
@key{RET}}, visiting a file which (you know) happens to be rather
|
|
large, and Emacs displays @samp{I feel pretty today}. The bug report
|
|
would need to provide all that information. You should not assume
|
|
that the problem is due to the size of the file and say, ``I visited a
|
|
large file, and Emacs displayed @samp{I feel pretty today}.'' This is
|
|
what we mean by ``guessing explanations''. The problem might be due
|
|
to the fact that there is a @samp{z} in the file name. If this is so,
|
|
then when we got your report, we would try out the problem with some
|
|
large file, probably with no @samp{z} in its name, and not see any
|
|
problem. There is no way we could guess that we should try visiting a
|
|
file with a @samp{z} in its name.
|
|
|
|
You should not even say ``visit a file'' instead of @kbd{C-x C-f}.
|
|
That's because a file can be visited in more than one way, and there's
|
|
no certainty that all of them reproduce the problem. Similarly,
|
|
rather than saying ``if I have three characters on the line'', say
|
|
``after I type @kbd{@key{RET} A B C @key{RET} C-p}'', if that is the
|
|
way you entered the text---that is, tell us about the text which in
|
|
your case produced the problem.
|
|
|
|
If possible, try quickly to reproduce the bug by invoking Emacs with
|
|
@command{emacs -Q} (so that Emacs starts with no initial
|
|
customizations; @pxref{Initial Options}), and repeating the steps that
|
|
you took to trigger the bug. If you can reproduce the bug this way,
|
|
that rules out bugs in your personal customizations and makes the bug
|
|
much easier to reproduce. Then your bug report should begin by
|
|
stating that you started Emacs with @command{emacs -Q}, followed by
|
|
the exact sequence of steps for reproducing the bug. If possible,
|
|
inform us of the exact contents of any file that is needed to
|
|
reproduce the bug.
|
|
|
|
Some bugs are not reproducible from @command{emacs -Q}; some are not
|
|
easily reproducible at all. In that case, you should report what you
|
|
have---but, as before, please stick to the raw facts about what you
|
|
did to trigger the bug the first time.
|
|
|
|
If you have multiple issues that you want to report, please make a
|
|
separate bug report for each.
|
|
|
|
@node Checklist
|
|
@subsection Checklist for Bug Reports
|
|
@cindex checklist before reporting a bug
|
|
@cindex bug reporting, checklist
|
|
@cindex report bugs in Emacs
|
|
|
|
Before reporting a bug, first try to see if the problem has already
|
|
been reported (@pxref{Known Problems}).
|
|
|
|
If you are able to, try the latest release of Emacs to see if the
|
|
problem has already been fixed. Even better is to try the latest
|
|
development version. We recognize that this is not easy for some
|
|
people, so do not feel that you absolutely must do this before making
|
|
a report.
|
|
|
|
@findex report-emacs-bug
|
|
The best way to write a bug report for Emacs is to use the command
|
|
@kbd{M-x report-emacs-bug}. This sets up a mail buffer
|
|
(@pxref{Sending Mail}) and automatically inserts @emph{some} of the
|
|
essential information. However, it cannot supply all the necessary
|
|
information; you should still read and follow the guidelines below, so
|
|
you can enter the other crucial information by hand before you send
|
|
the message. You may feel that some of the information inserted by
|
|
@kbd{M-x report-emacs-bug} is not relevant, but unless you are
|
|
absolutely sure, it is best to leave it, so that the developers can
|
|
decide for themselves.
|
|
|
|
When you have finished writing your report, type @kbd{C-c C-c} and it
|
|
will be sent to the Emacs maintainers at
|
|
@ifnothtml
|
|
@email{bug-gnu-emacs@@gnu.org}.
|
|
@end ifnothtml
|
|
@ifhtml
|
|
@url{https://lists.gnu.org/mailman/listinfo/bug-gnu-emacs, bug-gnu-emacs}.
|
|
@end ifhtml
|
|
If you cannot send mail from inside Emacs, you can copy the
|
|
text of your report to your normal mail client (if your system
|
|
supports it, you can type @kbd{C-c M-i} to have Emacs do this for you)
|
|
and send it to that address. Or you can simply send an email to that
|
|
address describing the problem, including the necessary information
|
|
mentioned below.
|
|
|
|
If you want to submit code to Emacs (to fix a problem or implement a
|
|
new feature), the easiest way to do this is to send a patch to the
|
|
Emacs issue tracker. Use the @kbd{M-x submit-emacs-patch} command for
|
|
that, which works much the same as when reporting bugs; @pxref{Sending
|
|
Patches}.
|
|
|
|
In any case, your report will be sent to the @samp{bug-gnu-emacs}
|
|
mailing list, and stored in the GNU Bug Tracker at
|
|
@url{https://debbugs.gnu.org}. Please include a valid reply email
|
|
address, in case we need to ask you for more information about your
|
|
report. Submissions are moderated, so there may be a delay before
|
|
your report actually appears on the tracker.
|
|
|
|
You do not need to know how the GNU Bug Tracker works in order to
|
|
report a bug, but if you want to, you can read the tracker's
|
|
@uref{https://debbugs.gnu.org/Advanced.html, online documentation} to
|
|
see the various features you can use.
|
|
|
|
All mail sent to the @samp{bug-gnu-emacs} mailing list is also
|
|
gatewayed to the @samp{gnu.emacs.bug} newsgroup. The reverse is also
|
|
true, but we ask you not to post bug reports (or replies) via the
|
|
newsgroup. It can make it much harder to contact you if we need to ask
|
|
for more information, and it does not integrate well with the bug
|
|
tracker.
|
|
|
|
If your data is more than 500,000 bytes, please don't include it
|
|
directly in the bug report; instead, offer to send it on request, or
|
|
make it available online and say where. Large attachments are best
|
|
sent compressed.
|
|
|
|
The GNU Bug Tracker will assign a bug number to your report; please
|
|
use it in the following discussions, keeping the bug address in the
|
|
list of recipients, so that the bug discussion is recorded by the
|
|
tracker. The bug address will look like
|
|
@samp{@var{nnnnn}@@debbugs.gnu.org}, where @var{nnnnn} is the bug
|
|
number.
|
|
|
|
To enable maintainers to investigate a bug, your report
|
|
should include all these things:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
A description of what behavior you observe that you believe is
|
|
incorrect. For example, ``The Emacs process gets a fatal signal'', or,
|
|
``The resulting text is as follows, which I think is wrong.''
|
|
|
|
Of course, if the bug is that Emacs gets a fatal signal, then one can't
|
|
miss it. But if the bug is incorrect text, the maintainer might fail to
|
|
notice what is wrong. Why leave it to chance?
|
|
|
|
Even if the problem you experience is a fatal signal, you should still
|
|
say so explicitly. Suppose something strange is going on, such as, your
|
|
copy of the source is out of sync, or you have encountered a bug in the
|
|
C library on your system. (This has happened!) Your copy might crash
|
|
and the copy here might not. If you @emph{said} to expect a crash, then
|
|
when Emacs here fails to crash, we would know that the bug was not
|
|
happening. If you don't say to expect a crash, then we would not know
|
|
whether the bug was happening---we would not be able to draw any
|
|
conclusion from our observations.
|
|
|
|
Usually, description of the behavior and of the way to reproduce the
|
|
problem needs to specify one or more of the following aspects:
|
|
|
|
@itemize @minus
|
|
@item
|
|
The complete text of any files needed to reproduce the bug.
|
|
|
|
If you can tell us a way to cause the problem without visiting any files,
|
|
please do so. This makes it much easier to debug. If you do need files,
|
|
make sure you arrange for us to see their exact contents. For example, it
|
|
can matter whether there are spaces at the ends of lines, or a
|
|
newline after the last line in the buffer (nothing ought to care whether
|
|
the last line is terminated, but try telling the bugs that).
|
|
|
|
@item
|
|
The precise commands we need to type to reproduce the bug. If at all
|
|
possible, give a full recipe for an Emacs started with the @samp{-Q}
|
|
option (@pxref{Initial Options}). This bypasses your personal
|
|
customizations.
|
|
|
|
@findex open-dribble-file
|
|
@cindex dribble file
|
|
@cindex logging keystrokes
|
|
One way to record the input to Emacs precisely is to write a dribble
|
|
file. To start the file, use the command @w{@kbd{M-x open-dribble-file}}.
|
|
From then on, Emacs copies all your input to the specified dribble
|
|
file until the Emacs process is killed. Be aware that sensitive
|
|
information (such as passwords) may end up recorded in the dribble
|
|
file.
|
|
|
|
@item
|
|
If the bug is that the Emacs Manual or the Emacs Lisp Reference Manual
|
|
fails to describe the actual behavior of Emacs, or that the text is
|
|
confusing, copy in the text from the manual which you think is
|
|
at fault. If the section is small, just the section name is enough.
|
|
|
|
@item
|
|
If the manifestation of the bug is an Emacs error message, it is
|
|
important to report the precise text of the error message, and a
|
|
backtrace showing how the Lisp program in Emacs arrived at the error.
|
|
|
|
To get the error message text accurately, copy it from the
|
|
@file{*Messages*} buffer into the bug report. Copy all of it, not just
|
|
part.
|
|
|
|
@item
|
|
Check whether any programs you have loaded into the Lisp world,
|
|
including your initialization file, set any variables that may affect
|
|
the functioning of Emacs. Also, see whether the problem happens in a
|
|
freshly started Emacs without loading your initialization file (start
|
|
Emacs with the @code{-Q} switch to prevent loading the init files).
|
|
If the problem does @emph{not} occur then, you must report the precise
|
|
contents of any programs that you must load into the Lisp world in
|
|
order to cause the problem to occur.
|
|
|
|
@item
|
|
If the problem does depend on an init file or other Lisp programs that
|
|
are not part of the standard Emacs system, then you should make sure it
|
|
is not a bug in those programs by complaining to their maintainers
|
|
first. After they verify that they are using Emacs in a way that is
|
|
supposed to work, they should report the bug.
|
|
|
|
@item
|
|
If you wish to mention something in the GNU Emacs source, show the line
|
|
of code with a few lines of context. Don't just give a line number.
|
|
|
|
The line numbers in the development sources don't match those in your
|
|
sources. It would take extra work for the maintainers to determine what
|
|
code is in your version at a given line number, and we could not be
|
|
certain.
|
|
|
|
@item
|
|
@findex open-termscript
|
|
@cindex termscript file
|
|
@vindex TERM@r{, environment variable, and display bugs}
|
|
For possible display bugs on text-mode terminals, the terminal type
|
|
(the value of environment variable @env{TERM}), the complete termcap
|
|
entry for the terminal from @file{/etc/termcap} (since that file is
|
|
not identical on all machines), and the output that Emacs actually
|
|
sent to the terminal.
|
|
|
|
The way to collect the terminal output is to invoke the command
|
|
@kbd{M-x open-termscript} just after starting Emacs; it will prompt
|
|
you for the name of the file where to record all terminal output until
|
|
the Emacs process is killed. If the problem happens when Emacs starts
|
|
up, put the Lisp expression
|
|
|
|
@example
|
|
(open-termscript "~/termscript")
|
|
@end example
|
|
|
|
@noindent
|
|
into your Emacs initialization file so that the termscript file will
|
|
be open when Emacs displays the screen for the first time.
|
|
|
|
Be warned: it is often difficult, and sometimes impossible, to fix a
|
|
terminal-dependent bug without access to a terminal of the type that
|
|
stimulates the bug.
|
|
@end itemize
|
|
|
|
@item
|
|
The version number of Emacs. Without this, we won't know whether there is any
|
|
point in looking for the bug in the current version of GNU Emacs.
|
|
|
|
@findex emacs-version
|
|
@kbd{M-x report-emacs-bug} includes this information automatically,
|
|
but if you are not using that command for your report you can get the
|
|
version number by typing @kbd{M-x emacs-version @key{RET}}. If that
|
|
command does not work, you probably have something other than GNU
|
|
Emacs, so you will have to report the bug somewhere else.
|
|
|
|
@item
|
|
The type of machine you are using, and the operating system name and
|
|
version number (again, automatically included by @w{@kbd{M-x
|
|
report-emacs-bug}}). @w{@kbd{M-x emacs-version @key{RET}}} provides
|
|
this information too. Copy its output from the @file{*Messages*}
|
|
buffer, so that you get it all and get it accurately, or use
|
|
@w{@kbd{C-u M-x emacs-version @key{RET}}} to insert the version
|
|
information into the current buffer.
|
|
|
|
@item
|
|
The command-line arguments given to the @code{configure} command when
|
|
Emacs was built (automatically included by @kbd{M-x
|
|
report-emacs-bug}).
|
|
|
|
@item
|
|
A complete list of any modifications you have made to the Emacs source.
|
|
(We may not have time to investigate the bug unless it happens in an
|
|
unmodified Emacs. But if you've made modifications and you don't tell
|
|
us, you are sending us on a wild goose chase.)
|
|
|
|
Be precise about these changes. A description in English is not
|
|
enough---send a unified context diff for them.
|
|
|
|
Adding files of your own, or porting to another machine, is a
|
|
modification of the source.
|
|
|
|
@item
|
|
Details of any other deviations from the standard procedure for installing
|
|
GNU Emacs.
|
|
|
|
@item
|
|
If non-@acronym{ASCII} text or internationalization is relevant, the locale that
|
|
was current when you started Emacs. This is automatically included by @kbd{M-x
|
|
report-emacs-bug}; alternatively, on GNU/Linux and Unix systems, or
|
|
if you use a POSIX-style shell such as Bash, you can use this shell
|
|
command to view the relevant values:
|
|
|
|
@smallexample
|
|
echo LC_ALL=$LC_ALL LC_COLLATE=$LC_COLLATE LC_CTYPE=$LC_CTYPE \
|
|
LC_MESSAGES=$LC_MESSAGES LC_TIME=$LC_TIME LANG=$LANG
|
|
@end smallexample
|
|
|
|
You can also use the @command{locale} command, if your system has it,
|
|
to display your locale settings.
|
|
@end itemize
|
|
|
|
Here are some things that are not necessary in a bug report:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
A description of the envelope of the bug---this is not necessary for a
|
|
reproducible bug.
|
|
|
|
Often people who encounter a bug spend a lot of time investigating
|
|
which changes to the input file will make the bug go away and which
|
|
changes will not affect it.
|
|
|
|
This is often time-consuming and not very useful, because the way we
|
|
will find the bug is by running a single example under the debugger
|
|
with breakpoints, not by pure deduction from a series of examples.
|
|
You might as well save time by not searching for additional examples.
|
|
It is better to send the bug report right away, go back to editing,
|
|
and find another bug to report.
|
|
|
|
Of course, if you can find a simpler example to report @emph{instead} of
|
|
the original one, that is a convenience. Errors in the output will be
|
|
easier to spot, running under the debugger will take less time, etc.
|
|
|
|
However, simplification is not vital; if you can't do this or don't have
|
|
time to try, please report the bug with your original test case.
|
|
|
|
@item
|
|
A core dump file.
|
|
|
|
Debugging the core dump might be useful, but it can only be done on
|
|
your machine, with your Emacs executable. Therefore, sending the core
|
|
dump file to the Emacs maintainers won't be useful. Above all, don't
|
|
include the core file in an email bug report! Such a large message
|
|
can be extremely inconvenient.
|
|
|
|
@item
|
|
A system-call trace of Emacs execution.
|
|
|
|
System-call traces are very useful for certain special kinds of
|
|
debugging, but in most cases they give little useful information. It is
|
|
therefore strange that many people seem to think that @emph{the} way to
|
|
report information about a crash is to send a system-call trace. Perhaps
|
|
this is a habit formed from experience debugging programs that don't
|
|
have source code or debugging symbols.
|
|
|
|
In most programs, a backtrace is normally far, far more informative than
|
|
a system-call trace. Even in Emacs, a simple backtrace is generally
|
|
more informative, though to give full information you should supplement
|
|
the backtrace by displaying variable values and printing them as Lisp
|
|
objects with @code{pr} (see above).
|
|
|
|
@item
|
|
A patch for the bug.
|
|
|
|
A patch for the bug is useful if it is a good one. But don't omit the
|
|
other information that a bug report needs, such as the test case, on
|
|
the assumption that a patch is sufficient. We might see problems with
|
|
your patch and decide to fix the problem another way, or we might not
|
|
understand it at all. And if we can't understand what bug you are
|
|
trying to fix, or why your patch should be an improvement, we mustn't
|
|
install it. @xref{Sending Patches}, for guidelines on how to make it
|
|
easy for us to understand and install your patches.
|
|
|
|
@item
|
|
A guess about what the bug is or what it depends on.
|
|
|
|
Such guesses are usually wrong. Even experts can't guess right about
|
|
such things without first using the debugger to find the facts.
|
|
@end itemize
|
|
|
|
If you are willing to debug Emacs and provide additional information
|
|
about the bug, here is some useful advice:
|
|
|
|
@findex toggle-debug-on-error
|
|
@pindex Edebug
|
|
@itemize
|
|
@item
|
|
If the bug manifests itself as an error message, try providing a Lisp
|
|
backtrace for the error. To make a backtrace for the error, use
|
|
@kbd{M-x toggle-debug-on-error} before the error happens (that is to
|
|
say, you must give that command and then make the bug happen). This
|
|
causes the error to start the Lisp debugger, which shows you a
|
|
backtrace. Copy the text of the debugger's backtrace into the bug
|
|
report. (The backtrace is more detailed if you load the relevant Lisp
|
|
@file{*.el} source files before triggering the error, so do that if
|
|
you know how to find and load those files.)
|
|
|
|
To debug the error, we suggest using Edebug. @xref{Edebug,, Edebug,
|
|
elisp, the Emacs Lisp Reference Manual}, for information on debugging
|
|
Emacs Lisp programs with the Edebug package.
|
|
|
|
This use of the debugger is possible only if you know how to make the
|
|
bug happen again. If you can't make it happen again, at least copy
|
|
the whole error message.
|
|
|
|
@vindex debug-on-quit
|
|
@item
|
|
If Emacs appears to be stuck in an infinite loop or in a very long
|
|
operation, typing @kbd{C-g} with the variable @code{debug-on-quit}
|
|
non-@code{nil} will start the Lisp debugger and show a backtrace.
|
|
This backtrace is useful for debugging such long loops, so if you can
|
|
produce it, copy it into the bug report.
|
|
|
|
@vindex debug-on-event
|
|
If you cannot get Emacs to respond to @kbd{C-g} (e.g., because
|
|
@code{inhibit-quit} is set), then you can try sending the signal
|
|
specified by @code{debug-on-event} (default SIGUSR2) from outside
|
|
Emacs to cause it to enter the debugger.
|
|
|
|
@item
|
|
Additional information from a C debugger such as GDB might enable
|
|
someone to find a problem on a machine which he does not have available.
|
|
If you don't know how to use GDB, please read the GDB manual---it is not
|
|
very long, and using GDB is easy. You can find the GDB distribution,
|
|
including the GDB manual in online form, in most of the same places you
|
|
can find the Emacs distribution. To run Emacs under GDB, you should
|
|
switch to the @file{src} subdirectory in which Emacs was compiled, then
|
|
type @kbd{gdb ./emacs}. It is important for the directory @file{src} to be
|
|
current so that GDB will read the @file{.gdbinit} file in this
|
|
directory. (You can also tell GDB to read that file from inside GDB,
|
|
by typing @kbd{source ./.gdbinit}.)
|
|
|
|
However, you need to think when you collect the additional information
|
|
if you want it to show what causes the bug.
|
|
|
|
@cindex backtrace for bug reports
|
|
For example, many people send just a C-level backtrace, but that is
|
|
not very useful by itself. A simple backtrace with arguments often
|
|
conveys little about what is happening inside GNU Emacs, because most
|
|
of the arguments listed in the backtrace are pointers to Lisp objects.
|
|
The numeric values of these pointers have no significance whatever;
|
|
all that matters is the contents of the objects they point to (and
|
|
most of the contents are themselves pointers).
|
|
|
|
@findex debug_print
|
|
To provide useful information, you need to show the values of Lisp
|
|
objects in Lisp notation. Do this for each variable which is a Lisp
|
|
object, in several stack frames near the bottom of the stack. Look at
|
|
the source to see which variables are Lisp objects, because the debugger
|
|
thinks of them as integers.
|
|
|
|
To show a variable's value in Lisp syntax, first print its value, then
|
|
use the user-defined GDB command @code{pr} to print the Lisp object in
|
|
Lisp syntax. (If you must use another debugger, call the function
|
|
@code{debug_print} with the object as an argument.) The @code{pr}
|
|
command is defined by the file @file{.gdbinit}, and it works only if you
|
|
are debugging a running process (not with a core dump).
|
|
|
|
To make Lisp errors stop Emacs and return to GDB, put a breakpoint at
|
|
@code{Fsignal}.
|
|
|
|
For a backtrace of Lisp functions running, type the GDB command
|
|
@code{xbacktrace}.
|
|
|
|
The file @file{.gdbinit} defines several other commands that are useful
|
|
for examining the data types and contents of Lisp objects. Their names
|
|
begin with @samp{x}. These commands work at a lower level than
|
|
@code{pr}, and are less convenient, but they may work even when
|
|
@code{pr} does not, such as when debugging a core dump or when Emacs has
|
|
had a fatal signal.
|
|
|
|
@cindex debugging Emacs, tricks and techniques
|
|
More detailed advice and other useful techniques for debugging Emacs
|
|
are available in the file @file{etc/DEBUG} in the Emacs distribution.
|
|
That file also includes instructions for investigating problems
|
|
whereby Emacs stops responding (many people assume that Emacs is
|
|
``hung'', whereas in fact it might be in an infinite loop).
|
|
|
|
To find the file @file{etc/DEBUG} in your Emacs installation, use the
|
|
directory name stored in the variable @code{data-directory}.
|
|
@end itemize
|
|
|
|
@node Sending Patches
|
|
@subsection Sending Patches for GNU Emacs
|
|
|
|
@cindex sending patches for GNU Emacs
|
|
@cindex patches, sending
|
|
If you would like to write bug fixes or improvements for GNU Emacs,
|
|
that is very helpful. When you send your changes, please follow these
|
|
guidelines to make it easy for the maintainers to use them. If you
|
|
don't follow these guidelines, your information might still be useful,
|
|
but using it will take extra work. Maintaining GNU Emacs is a lot of
|
|
work in the best of circumstances, and we can't keep up unless you do
|
|
your best to help.
|
|
|
|
Every patch must have several pieces of information before we
|
|
can properly evaluate it. They are described below.
|
|
|
|
When you have all these pieces, use the @kbd{M-x submit-emacs-patch}
|
|
command to send the patch. The command will prompt you for the
|
|
Subject of the patch and a patch file. It will then create and
|
|
display a Message mode buffer with the patch file as an attachment,
|
|
display the buffer, and let you explain more about the patch and add
|
|
any other information as requested below. When you are done, type
|
|
@kbd{C-c C-c} to send the patch via email to the developers. It will
|
|
be sent to the GNU Bug Tracker at @url{https://debbugs.gnu.org}. The
|
|
tracker will assign a number to your submission, just like it does
|
|
with bug reports. The developers will usually respond, perhaps asking
|
|
you for more details or any additional information, so be sure to
|
|
include a valid reply email address.
|
|
|
|
Here's what we ask you to provide as part of your patch submissions:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
An explanation of what problem you are fixing or what improvement will
|
|
the patches bring about:
|
|
|
|
@itemize @minus
|
|
@item
|
|
For a fix for an existing bug, it is
|
|
best to reply to the relevant discussion on the @samp{bug-gnu-emacs}
|
|
list, or the bug entry in the GNU Bug Tracker at
|
|
@url{https://debbugs.gnu.org}. Explain why your change fixes the bug.
|
|
|
|
@item
|
|
For a new feature, include a description of the feature and your
|
|
implementation.
|
|
|
|
@item
|
|
For a new bug, include a proper bug report for the problem you think
|
|
you have fixed; @pxref{Checklist, Checklist for Bug Reports}. We need
|
|
to convince ourselves that the change is right before installing it.
|
|
Even if it is correct, we might have trouble understanding it if we
|
|
don't have a way to reproduce the problem it tries to fix.
|
|
@end itemize
|
|
|
|
@item
|
|
Include in your code changes all the comments that are appropriate to
|
|
help people reading the source in the future understand why this
|
|
change was needed.
|
|
|
|
@item
|
|
Don't mix together changes made for different reasons.
|
|
Send them @emph{individually}.
|
|
|
|
If you make two changes for separate reasons, then we might not want
|
|
to install them both. We might want to install just one, or install
|
|
each one in a different versions of Emacs. If you send them all
|
|
jumbled together in a single set of diffs, we have to do extra work to
|
|
disentangle them---to figure out which parts of the change serve which
|
|
purpose. If we don't have time for this, we might have to postpone
|
|
inclusion of your patches for a long time.
|
|
|
|
If you send each change as soon as you have written it, with its own
|
|
explanation, then two changes never get tangled up, and we can consider
|
|
each one properly without any extra work to disentangle them.
|
|
|
|
@item
|
|
Send each change as soon as that change is finished. Sometimes people
|
|
think they are helping us by accumulating many changes to send them all
|
|
together. As explained above, this is absolutely the worst thing you
|
|
could do.
|
|
|
|
Since you should send each change separately, you might as well send it
|
|
right away. That gives us the option of installing it immediately if it
|
|
is important.
|
|
|
|
@item
|
|
The patch itself. This can be produced in one of the following ways:
|
|
|
|
@itemize @minus
|
|
@item
|
|
If you are using the Emacs repository, make sure your copy is
|
|
up-to-date (e.g., with @code{git pull}). You can commit your changes
|
|
to a private branch and generate a patch from the master version by
|
|
using @code{git format-patch master}. (This is the preferred method,
|
|
as it makes our job of applying the patch easier.) Or you can leave
|
|
your changes uncommitted and use @code{git diff}, as described below.
|
|
|
|
@item
|
|
Use @kbd{diff -u} to make your diffs. If you have GNU diff, use
|
|
@w{@kbd{diff -u -F'^[_a-zA-Z0-9$]\+ *('}} when making diffs of C code.
|
|
This shows the name of the function that each change occurs in.
|
|
|
|
When producing the diffs, avoid any ambiguity as to which is the old
|
|
version and which is the new. Please make the old version the first
|
|
argument to diff, and the new version the second argument. And please
|
|
give one version or the other a name that indicates whether it is the
|
|
old version or your new changed one.
|
|
@end itemize
|
|
|
|
@item
|
|
Write the commit log entries for your changes. This is both to save us
|
|
the extra work of writing them, and to help explain your changes so we
|
|
can understand them.
|
|
|
|
The purpose of the commit log is to explain the rationale of the
|
|
changes, the way the modified code solves whatever problems your patch
|
|
is trying to fix, and also show people where to find what was changed.
|
|
So you need to be specific about what functions you changed and why.
|
|
For the details about our style and requirements for good commit log
|
|
messages, please see the ``Commit messages'' section of the file
|
|
@file{CONTRIBUTE} in the Emacs source tree.
|
|
|
|
Please also look at the commit log entries of recent commits to see
|
|
what sorts of information to put in, and to learn the style that we
|
|
use. Note that, unlike some other projects, we do require commit logs
|
|
for documentation, i.e., Texinfo files. @xref{Change Log},
|
|
@ifset WWW_GNU_ORG
|
|
see
|
|
@url{https://www.gnu.org/prep/standards/html_node/Change-Log-Concepts.html},
|
|
@end ifset
|
|
@xref{Change Log Concepts, Change Log Concepts,
|
|
Change Log Concepts, standards, GNU Coding Standards}.
|
|
|
|
@item
|
|
When you write the fix, keep in mind that we can't install a change that
|
|
would break other systems. Please think about what effect your change
|
|
will have if compiled and/or used on another type of system.
|
|
|
|
Sometimes people send fixes that @emph{might} be an improvement in
|
|
general---but it is hard to be sure of this. It's hard to install
|
|
such changes because we have to study them very carefully. Of course,
|
|
a good explanation of the reasoning by which you concluded the change
|
|
was correct can help convince us.
|
|
|
|
The safest changes are changes to the files or portions of files that
|
|
are only used for a particular machine or a particular system. These
|
|
are safe because they can't create new bugs on other machines or
|
|
systems.
|
|
|
|
Please help us keep up with the workload by designing the patch in a
|
|
form that is clearly safe to install.
|
|
@end itemize
|
|
|
|
@node Contributing
|
|
@section Contributing to Emacs Development
|
|
@cindex contributing to Emacs
|
|
|
|
Emacs is a collaborative project and we encourage contributions from
|
|
anyone and everyone.
|
|
|
|
There are many ways to contribute to Emacs:
|
|
|
|
@itemize
|
|
@item
|
|
find and report bugs; @pxref{Bugs}.
|
|
|
|
@item
|
|
answer questions on the Emacs user mailing list
|
|
@url{https://lists.gnu.org/mailman/listinfo/help-gnu-emacs}.
|
|
|
|
@item
|
|
write documentation, either on the @uref{https://www.emacswiki.org/,
|
|
wiki}, or in the Emacs source repository (@pxref{Sending Patches}).
|
|
|
|
@item
|
|
check if existing bug reports are fixed in newer versions of Emacs
|
|
@url{https://debbugs.gnu.org/cgi/pkgreport.cgi?which=pkg&data=emacs}.
|
|
|
|
@item
|
|
fix existing bug reports.
|
|
|
|
@item
|
|
@c etc/TODO not in WWW_GNU_ORG
|
|
implement a feature listed in the @file{etc/TODO} file in the Emacs
|
|
distribution, and submit a patch.
|
|
|
|
@item
|
|
implement a new feature, and submit a patch.
|
|
|
|
@item
|
|
develop a package that works with Emacs, and publish it on your own
|
|
or in GNU ELPA (@url{https://elpa.gnu.org/}).
|
|
|
|
@item
|
|
port Emacs to a new platform, but that is not common nowadays.
|
|
|
|
@end itemize
|
|
|
|
If you would like to work on improving Emacs, please contact the maintainers at
|
|
@ifnothtml
|
|
@email{emacs-devel@@gnu.org}.
|
|
@end ifnothtml
|
|
@ifhtml
|
|
@url{https://lists.gnu.org/mailman/listinfo/emacs-devel, the
|
|
emacs-devel mailing list}.
|
|
@end ifhtml
|
|
You can ask for suggested projects or suggest your own ideas.
|
|
|
|
If you have a feature request or a suggestion for how to improve
|
|
Emacs, the best place to send it is to
|
|
@ifnothtml
|
|
@email{bug-gnu-emacs@@gnu.org}
|
|
@end ifnothtml
|
|
@ifhtml
|
|
@url{https://lists.gnu.org/mailman/listinfo/bug-gnu-emacs, bug-gnu-emacs}
|
|
@end ifhtml
|
|
. Please explain as clearly as possible what change you would like to
|
|
see, and why and how you think it would improve Emacs.
|
|
|
|
If you have already written an improvement, please tell us about it. If
|
|
you have not yet started work, it is useful to contact
|
|
@ifnothtml
|
|
@email{emacs-devel@@gnu.org}
|
|
@end ifnothtml
|
|
@ifhtml
|
|
@url{https://lists.gnu.org/mailman/listinfo/emacs-devel, emacs-devel}
|
|
@end ifhtml
|
|
before you start; it might be possible to suggest ways to make your
|
|
extension fit in better with the rest of Emacs.
|
|
|
|
When implementing a feature, please follow the Emacs coding standards;
|
|
@pxref{Coding Standards}. In addition, substantial contributions
|
|
require a copyright assignment to the FSF; @pxref{Copyright Assignment}.
|
|
|
|
The development version of Emacs can be downloaded from the
|
|
repository where it is actively maintained by a group of developers.
|
|
See the Emacs project page
|
|
@url{https://savannah.gnu.org/projects/emacs/} for access details.
|
|
|
|
It is important to write your patches based on the current working
|
|
version. If you start from an older version, your patch may be
|
|
outdated (so that maintainers will have a hard time applying it), or
|
|
changes in Emacs may have made your patch unnecessary. After you have
|
|
downloaded the repository source, you should read the file
|
|
@file{INSTALL.REPO} for build instructions (they differ to some extent
|
|
from a normal build).
|
|
|
|
If you would like to make more extensive contributions, see the
|
|
@file{CONTRIBUTE} file in the Emacs source tree for information on how
|
|
to be an Emacs developer. That file is distributed as part of the source
|
|
tarball of every released Emacs version, and can also be found on-line
|
|
in the @url{https://git.savannah.gnu.org/cgit/emacs.git/tree/CONTRIBUTE,
|
|
Emacs on-line source repository}. If you cloned the Emacs repository,
|
|
per the instructions in @url{https://savannah.gnu.org/projects/emacs/},
|
|
you will find this file in the top directory of the source Emacs tree.
|
|
|
|
For documentation on Emacs (to understand how to implement your
|
|
desired change), refer to:
|
|
|
|
@itemize
|
|
@item
|
|
@ifset WWW_GNU_ORG
|
|
@ifhtml
|
|
the Emacs Manual
|
|
@url{https://www.gnu.org/software/emacs/manual/emacs.html}.
|
|
@end ifhtml
|
|
@ifnothtml
|
|
@xref{Top, Emacs Manual,,emacs}.
|
|
@end ifnothtml
|
|
@end ifset
|
|
@ifclear WWW_GNU_ORG
|
|
@xref{Top, Emacs Manual,,emacs}.
|
|
@end ifclear
|
|
|
|
@item
|
|
@ifset WWW_GNU_ORG
|
|
@ifhtml
|
|
the Emacs Lisp Reference Manual
|
|
@url{https://www.gnu.org/software/emacs/manual/elisp.html}.
|
|
@end ifhtml
|
|
@ifnothtml
|
|
@xref{Top, Emacs Lisp Reference Manual,,elisp}.
|
|
@end ifnothtml
|
|
@end ifset
|
|
@ifclear WWW_GNU_ORG
|
|
@xref{Top, Emacs Lisp Reference Manual,,elisp}.
|
|
@end ifclear
|
|
|
|
@item
|
|
@url{https://www.gnu.org/software/emacs}
|
|
|
|
@item
|
|
@url{https://www.emacswiki.org/}
|
|
@end itemize
|
|
|
|
@menu
|
|
* Coding Standards:: GNU Emacs coding standards
|
|
* Copyright Assignment:: assigning copyright to the FSF
|
|
@end menu
|
|
|
|
@node Coding Standards
|
|
@subsection Coding Standards
|
|
@cindex coding standards for Emacs submissions
|
|
|
|
Contributed code should follow the GNU Coding Standards
|
|
@url{https://www.gnu.org/prep/standards/}. This may also be available
|
|
in info on your system.
|
|
|
|
If it doesn't, we'll need to find someone to fix the code before we
|
|
can use it.
|
|
|
|
Emacs has additional style and coding conventions:
|
|
|
|
@itemize
|
|
@item
|
|
@ifset WWW_GNU_ORG
|
|
@ifhtml
|
|
the ``Tips and Conventions'' Appendix in the Emacs Lisp Reference
|
|
@url{https://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html}.
|
|
@end ifhtml
|
|
@ifnothtml
|
|
@xref{Tips, ``Tips and Conventions'' Appendix in the Emacs Lisp Reference, Tips
|
|
Appendix, elisp, Emacs Lisp Reference}.
|
|
@end ifnothtml
|
|
@end ifset
|
|
@ifclear WWW_GNU_ORG
|
|
@xref{Tips, ``Tips and Conventions'' Appendix in the Emacs Lisp Reference, Tips
|
|
Appendix, elisp, Emacs Lisp Reference}.
|
|
@end ifclear
|
|
|
|
@item
|
|
Avoid using @code{advice-add} or @code{with-eval-after-load} for Lisp code
|
|
to be included in Emacs.
|
|
|
|
@item
|
|
Remove all trailing whitespace in all source and text files.
|
|
|
|
@item
|
|
Use @code{?\s} instead of @code{? } in Lisp code for a space character.
|
|
|
|
@end itemize
|
|
|
|
@node Copyright Assignment
|
|
@subsection Copyright Assignment
|
|
@cindex copyright assignment
|
|
|
|
The FSF (Free Software Foundation) is the copyright holder for GNU Emacs.
|
|
The FSF is a nonprofit with a worldwide mission to promote computer
|
|
user freedom and to defend the rights of all free software users.
|
|
For general information, see the website @url{https://www.fsf.org/}.
|
|
|
|
Generally speaking, for non-trivial contributions to GNU Emacs and
|
|
packages stored in GNU ELPA, we require that the copyright be assigned
|
|
to the FSF@. For the reasons behind this, see
|
|
@url{https://www.gnu.org/licenses/why-assign.html}.
|
|
|
|
Copyright assignment is a simple process. Residents of many countries
|
|
can do it entirely electronically. We can help you get started,
|
|
including sending you the forms you should fill, and answer any
|
|
questions you may have (or point you to the people with the answers),
|
|
at the @email{emacs-devel@@gnu.org} mailing list.
|
|
|
|
(Please note: general discussion about why some GNU projects ask
|
|
for a copyright assignment is off-topic for emacs-devel.
|
|
See gnu-misc-discuss instead.)
|
|
|
|
A copyright disclaimer is also a possibility, but we prefer an assignment.
|
|
Note that the disclaimer, like an assignment, involves you sending
|
|
signed paperwork to the FSF (simply saying ``this is in the public domain''
|
|
is not enough). Also, a disclaimer cannot be applied to future work, it
|
|
has to be repeated each time you want to send something new.
|
|
|
|
We can accept small changes (roughly, fewer than 15 lines) without
|
|
an assignment. This is a cumulative limit (e.g., three separate 5 line
|
|
patches) over all your contributions.
|
|
|
|
@node Service
|
|
@section How To Get Help with GNU Emacs
|
|
@cindex help in using Emacs
|
|
@cindex @samp{help-gnu-emacs} mailing list
|
|
@cindex @samp{gnu.emacs.help} newsgroup
|
|
|
|
If you need help installing, using or changing GNU Emacs, there are
|
|
two ways to find it:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Send a message to
|
|
@ifnothtml
|
|
the mailing list @email{help-gnu-emacs@@gnu.org},
|
|
@end ifnothtml
|
|
@ifhtml
|
|
@url{https://lists.gnu.org/mailman/listinfo/help-gnu-emacs, the
|
|
help-gnu-emacs mailing list},
|
|
@end ifhtml
|
|
or post your request on newsgroup @code{gnu.emacs.help}. (This
|
|
mailing list and newsgroup interconnect, so it does not matter which
|
|
one you use.)
|
|
|
|
@item
|
|
Look in the @uref{https://www.fsf.org/resources/service/, service
|
|
directory} for someone who might help you for a fee.
|
|
@end itemize
|
|
|
|
@ifnottex
|
|
@lowersections
|
|
@end ifnottex
|