* binutils.texi: Add section on reporting bugs.
This commit is contained in:
Ian Lance Taylor
parent
7a6e913309
commit
cbcfa12917
1 changed files with 209 additions and 1 deletions
|
|
@ -134,7 +134,8 @@ Convert object code into a Netware Loadable Module
|
|||
* c++filt:: Filter to demangle encoded C++ symbols
|
||||
* nlmconv:: Converts object code into an NLM
|
||||
* Selecting The Target System:: How these utilities determine the target.
|
||||
* Index::
|
||||
* Reporting Bugs:: Reporting Bugs
|
||||
* Index:: Index
|
||||
@end menu
|
||||
|
||||
@node ar
|
||||
|
|
@ -1978,6 +1979,213 @@ compiled-in @code{DEFAULT_EMULATION} from @file{Makefile},
|
|||
which comes from @code{EMUL} in @file{config/@var{target}.mt}
|
||||
@end enumerate
|
||||
|
||||
@node Reporting Bugs
|
||||
@chapter Reporting Bugs
|
||||
@cindex bugs
|
||||
@cindex reporting bugs
|
||||
|
||||
Your bug reports play an essential role in making the binary utilities
|
||||
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 the binary
|
||||
utilities work better. Bug reports are your contribution to their
|
||||
maintenance.
|
||||
|
||||
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
|
||||
@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
|
||||
@cindex fatal signal
|
||||
@cindex crash
|
||||
@item
|
||||
If a binary utility gets a fatal signal, for any input whatever, that is
|
||||
a bug. Reliable utilities never crash.
|
||||
|
||||
@cindex error on valid input
|
||||
@item
|
||||
If a binary utility produces an error message for valid input, that is a
|
||||
bug.
|
||||
|
||||
@item
|
||||
If you are an experienced user of binary utilities, your suggestions for
|
||||
improvement are welcome in any case.
|
||||
@end itemize
|
||||
|
||||
@node Bug Reporting
|
||||
@section How to report bugs
|
||||
@cindex bug reports
|
||||
@cindex bugs, reporting
|
||||
|
||||
A number of companies and individuals offer support for @sc{gnu}
|
||||
products. If you obtained the binary utilities from a support
|
||||
organization, we recommend you contact that organization first.
|
||||
|
||||
You can find contact information for many support companies and
|
||||
individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
|
||||
distribution.
|
||||
|
||||
In any event, we also recommend that you send bug reports for the binary
|
||||
utilities to @samp{bug-gnu-utils@@prep.ai.mit.edu}.
|
||||
|
||||
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 do not matter. Thus, you might
|
||||
assume that the name of a file you use in an example does not matter.
|
||||
Well, probably it does not, but one cannot be sure. Perhaps the bug is
|
||||
a stray memory reference which happens to fetch from the location where
|
||||
that pathname is stored in memory; perhaps, if the pathname were
|
||||
different, the contents of that location would fool the utility 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. 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 the utility. Each utility announces it if you start it
|
||||
with the @samp{--version} argument.
|
||||
|
||||
Without this, we will not know whether there is any point in looking for
|
||||
the bug in the current version of the binary utilities.
|
||||
|
||||
@item
|
||||
Any patches you may have applied to the source, including any patches
|
||||
made to the @code{BFD} library.
|
||||
|
||||
@item
|
||||
The type of machine you are using, and the operating system name and
|
||||
version number.
|
||||
|
||||
@item
|
||||
What compiler (and its version) was used to compile the utilities---e.g.
|
||||
``@code{gcc-2.7}''.
|
||||
|
||||
@item
|
||||
The command arguments you gave the utility to observe the bug. To
|
||||
guarantee you will not omit something important, list them all. A copy
|
||||
of the Makefile (or the output from make) is sufficient.
|
||||
|
||||
If we were to try to guess the arguments, we would probably guess wrong
|
||||
and then we might not encounter the bug.
|
||||
|
||||
@item
|
||||
A complete input file, or set of input files, that will reproduce the
|
||||
bug. If the utility is reading an object file or files, then it is
|
||||
generally most helpful to send the actual object files, uuencoded if
|
||||
necessary to get them through the mail system. Making them available
|
||||
for anonymous FTP is not as good, but may be the only reasonable choice
|
||||
for large object files.
|
||||
|
||||
If the source files were produced exclusively using @sc{gnu} programs
|
||||
(e.g., @code{gcc}, @code{gas}, and/or the @sc{gnu} @code{ld}), then it
|
||||
may be OK to send the source files rather than the object files. In
|
||||
this case, be sure to say exactly what version of @code{gcc}, or
|
||||
whatever, was used to produce the object files. Also say how
|
||||
@code{gcc}, or whatever, was configured.
|
||||
|
||||
@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 the utility 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. 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 the utility 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 source, send us context diffs, as
|
||||
generated by @code{diff} with the @samp{-u}, @samp{-c}, or @samp{-p}
|
||||
option. Always send diffs from the old file to the new file. If you
|
||||
even discuss something in the @code{ld} source, refer to it by context,
|
||||
not by line number.
|
||||
|
||||
The line numbers in our development sources will not 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, and so on.
|
||||
|
||||
However, simplification is not vital; if you do not 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 do not 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 programs as complicated as the binary utilities it is
|
||||
very hard to construct an example that will make the program follow a
|
||||
certain path through the code. If you do not send us the example, we
|
||||
will not be able to construct one, so we will not be able to verify that
|
||||
the bug is fixed.
|
||||
|
||||
And if we cannot understand what bug you are trying to fix, or why your
|
||||
patch should be an improvement, we will not 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 cannot guess right about such
|
||||
things without first using the debugger to find the facts.
|
||||
@end itemize
|
||||
|
||||
@node Index
|
||||
@unnumbered Index
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue