forked from Imagelibrary/binutils-gdb
recording file death
This commit is contained in:
K. Richard Pixley
@@ -1,221 +0,0 @@
|
||||
_dnl__ Copyright (c) 1990 1991 Free Software Foundation, Inc.
|
||||
_dnl__ This file is part of the source for the GDB manual.
|
||||
@c M4 FRAGMENT: $Id$
|
||||
@node _GDBN__ Bugs, Renamed Commands, Emacs, Top
|
||||
@chapter Reporting Bugs in _GDBN__
|
||||
@cindex Bugs in _GDBN__
|
||||
@cindex Reporting Bugs in _GDBN__
|
||||
|
||||
Your bug reports play an essential role in making _GDBN__ reliable.
|
||||
|
||||
Reporting a bug may help you by bringing a solution to your problem, or it
|
||||
may not. But in any case the principal function of a bug report is to help
|
||||
the entire community by making the next version of _GDBN__ work better. Bug
|
||||
reports are your contribution to the maintenance of _GDBN__.
|
||||
|
||||
In order for a bug report to serve its purpose, you must include the
|
||||
information that enables us to fix the bug.
|
||||
|
||||
@menu
|
||||
* Bug Criteria:: Have You Found a Bug?
|
||||
* Bug Reporting:: How to Report Bugs
|
||||
@end menu
|
||||
|
||||
@node Bug Criteria, Bug Reporting, _GDBN__ Bugs, _GDBN__ Bugs
|
||||
@section Have You Found a Bug?
|
||||
@cindex Bug Criteria
|
||||
|
||||
If you are not sure whether you have found a bug, here are some guidelines:
|
||||
|
||||
@itemize @bullet
|
||||
@item
|
||||
@cindex Fatal Signal
|
||||
@cindex Core Dump
|
||||
If the debugger gets a fatal signal, for any input whatever, that is a
|
||||
_GDBN__ bug. Reliable debuggers never crash.
|
||||
|
||||
@item
|
||||
@cindex error on Valid Input
|
||||
If _GDBN__ produces an error message for valid input, that is a bug.
|
||||
|
||||
@item
|
||||
@cindex Invalid Input
|
||||
If _GDBN__ does not produce an error message for invalid input,
|
||||
that is a bug. However, you should note that your idea of
|
||||
``invalid input'' might be our idea of ``an extension'' or ``support
|
||||
for traditional practice''.
|
||||
|
||||
@item
|
||||
If you are an experienced user of debugging tools, your suggestions
|
||||
for improvement of _GDBN__ are welcome in any case.
|
||||
@end itemize
|
||||
|
||||
@node Bug Reporting, , Bug Criteria, _GDBN__ Bugs
|
||||
@section How to Report Bugs
|
||||
@cindex Bug Reports
|
||||
@cindex Compiler Bugs, Reporting
|
||||
|
||||
A number of companies and individuals offer support for GNU products.
|
||||
If you obtained _GDBN__ from a support organization, we recommend you
|
||||
contact that organization first.
|
||||
|
||||
Contact information for many support companies and individuals is
|
||||
available in the file @file{etc/SERVICE} in the GNU Emacs distribution.
|
||||
|
||||
In any event, we also recommend that you send bug reports for _GDBN__ to one
|
||||
of these addresses:
|
||||
|
||||
@example
|
||||
bug-gdb@@prep.ai.mit.edu
|
||||
@{ucbvax|mit-eddie|uunet@}!prep.ai.mit.edu!bug-gdb
|
||||
@end example
|
||||
|
||||
@strong{Do not send bug reports to @samp{info-gdb}, or to
|
||||
@samp{help-gdb}, or to any newsgroups.} Most users of _GDBN__ do not want to
|
||||
receive bug reports. Those that do, have arranged to receive @samp{bug-gdb}.
|
||||
|
||||
The mailing list @samp{bug-gdb} has a newsgroup which serves as a
|
||||
repeater. The mailing list and the newsgroup carry exactly the same
|
||||
messages. Often people think of posting bug reports to the newsgroup
|
||||
instead of mailing them. This appears to work, but it has one problem
|
||||
which can be crucial: a newsgroup posting often lacks a mail path
|
||||
back to the sender. Thus, if we need to ask for more information, we
|
||||
may be unable to reach you. For this reason, it is better to send bug
|
||||
reports to the mailing list.
|
||||
|
||||
As a last resort, send bug reports on paper to:
|
||||
|
||||
@example
|
||||
GNU Debugger Bugs
|
||||
545 Tech Square
|
||||
Cambridge, MA 02139
|
||||
@end example
|
||||
|
||||
The fundamental principle of reporting bugs usefully is this:
|
||||
@strong{report all the facts}. If you are not sure whether to state a
|
||||
fact or leave it out, state it!
|
||||
|
||||
Often people omit facts because they think they know what causes the
|
||||
problem and assume that some details don't matter. Thus, you might
|
||||
assume that the name of the variable you use in an example does not matter.
|
||||
Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a
|
||||
stray memory reference which happens to fetch from the location where that
|
||||
name is stored in memory; perhaps, if the name were different, the contents
|
||||
of that location would fool the debugger into doing the right thing despite
|
||||
the bug. Play it safe and give a specific, complete example. That is the
|
||||
easiest thing for you to do, and the most helpful.
|
||||
|
||||
Keep in mind that the purpose of a bug report is to enable us to fix
|
||||
the bug if it is new to us. It isn't as important what happens if
|
||||
the bug is already known. Therefore, always write your bug reports on
|
||||
the assumption that the bug has not been reported previously.
|
||||
|
||||
Sometimes people give a few sketchy facts and ask, ``Does this ring a
|
||||
bell?'' Those bug reports are useless, and we urge everyone to
|
||||
@emph{refuse to respond to them} except to chide the sender to report
|
||||
bugs properly.
|
||||
|
||||
To enable us to fix the bug, you should include all these things:
|
||||
|
||||
@itemize @bullet
|
||||
@item
|
||||
The version of _GDBN__. _GDBN__ announces it if you start with no
|
||||
arguments; you can also print it at any time using @code{show version}.
|
||||
|
||||
Without this, we won't know whether there is any point in looking for
|
||||
the bug in the current version of _GDBN__.
|
||||
|
||||
@item
|
||||
A complete input script, and all necessary source files, that will
|
||||
reproduce the bug.
|
||||
|
||||
@item
|
||||
What compiler (and its version) was used to compile _GDBN__---e.g.
|
||||
``_GCC__-1.37.1''.
|
||||
|
||||
@item
|
||||
The command arguments you gave the compiler to compile your example and
|
||||
observe the bug. For example, did you use @samp{-O}? To guarantee
|
||||
you won't omit something important, list them all.
|
||||
|
||||
If we were to try to guess the arguments, we would probably guess wrong
|
||||
and then we might not encounter the bug.
|
||||
|
||||
@item
|
||||
The type of machine you are using, and the operating system name and
|
||||
version number.
|
||||
|
||||
@item
|
||||
A description of what behavior you observe that you believe is
|
||||
incorrect. For example, ``It gets a fatal signal.''
|
||||
|
||||
Of course, if the bug is that _GDBN__ gets a fatal signal, then we will
|
||||
certainly notice it. But if the bug is incorrect output, we might not
|
||||
notice unless it is glaringly wrong. We are human, after all. You
|
||||
might as well not give us a chance to make a mistake.
|
||||
|
||||
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 _GDBN__ is out of synch, or you have encountered a
|
||||
bug in the C library on your system. (This has happened!) Your copy
|
||||
might crash and ours would not. If you told us to expect a crash,
|
||||
then when ours fails to crash, we would know that the bug was not
|
||||
happening for us. If you had not told us to expect a crash, then we
|
||||
would not be able to draw any conclusion from our observations.
|
||||
|
||||
@item
|
||||
If you wish to suggest changes to the _GDBN__ source, send us context
|
||||
diffs. If you even discuss something in the _GDBN__ source, refer to
|
||||
it by context, not by line number.
|
||||
|
||||
The line numbers in our development sources won't match those in your
|
||||
sources. Your line numbers would convey no useful information to us.
|
||||
|
||||
@end itemize
|
||||
|
||||
Here are some things that are not necessary:
|
||||
|
||||
@itemize @bullet
|
||||
@item
|
||||
A description of the envelope of the 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.
|
||||
We recommend that you save your time for something else.
|
||||
|
||||
Of course, if you can find a simpler example to report @emph{instead}
|
||||
of the original one, that is a convenience for us. 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 don't want to do this,
|
||||
report the bug anyway and send us the entire test case you used.
|
||||
|
||||
@item
|
||||
A patch for the bug.
|
||||
|
||||
A patch for the bug does help us if it is a good one. But don't omit
|
||||
the necessary information, such as the test case, on the assumption that
|
||||
a patch is all we need. We might see problems with your patch and decide
|
||||
to fix the problem another way, or we might not understand it at all.
|
||||
|
||||
Sometimes with a program as complicated as _GDBN__ it is very hard to
|
||||
construct an example that will make the program follow a certain path
|
||||
through the code. If you don't send us the example, we won't be able
|
||||
to construct one, so we won't be able to verify that the bug is fixed.
|
||||
|
||||
And if we can't understand what bug you are trying to fix, or why your
|
||||
patch should be an improvement, we won't install it. A test case will
|
||||
help us to understand.
|
||||
|
||||
@item
|
||||
A guess about what the bug is or what it depends on.
|
||||
|
||||
Such guesses are usually wrong. Even we can't guess right about such
|
||||
things without first using the debugger to find the facts.
|
||||
@end itemize
|
||||
|
||||
Reference in New Issue
Block a user