221 lines
8.4 KiB
Text
Executable file
221 lines
8.4 KiB
Text
Executable file
_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
|