267 lines
8.6 KiB
HTML
267 lines
8.6 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<!-- This HTML file has been created by texi2html 1.52
|
|
from ../texi/as.texinfo on 24 April 1999 -->
|
|
|
|
<TITLE>Using as - Reporting Bugs</TITLE>
|
|
</HEAD>
|
|
<BODY>
|
|
Go to the <A HREF="as_1.html">first</A>, <A HREF="as_24.html">previous</A>, <A HREF="as_26.html">next</A>, <A HREF="as_27.html">last</A> section, <A HREF="as_toc.html">table of contents</A>.
|
|
<P><HR><P>
|
|
|
|
|
|
<H1><A NAME="SEC269" HREF="as_toc.html#TOC269">Reporting Bugs</A></H1>
|
|
<P>
|
|
<A NAME="IDX902"></A>
|
|
<A NAME="IDX903"></A>
|
|
|
|
</P>
|
|
<P>
|
|
Your bug reports play an essential role in making <CODE>as</CODE> reliable.
|
|
|
|
</P>
|
|
<P>
|
|
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 <CODE>as</CODE> work better.
|
|
Bug reports are your contribution to the maintenance of <CODE>as</CODE>.
|
|
|
|
</P>
|
|
<P>
|
|
In order for a bug report to serve its purpose, you must include the
|
|
information that enables us to fix the bug.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC270" HREF="as_toc.html#TOC270">Have you found a bug?</A></H2>
|
|
<P>
|
|
<A NAME="IDX904"></A>
|
|
|
|
</P>
|
|
<P>
|
|
If you are not sure whether you have found a bug, here are some guidelines:
|
|
|
|
</P>
|
|
|
|
<UL>
|
|
<LI>
|
|
|
|
<A NAME="IDX905"></A>
|
|
<A NAME="IDX906"></A>
|
|
<A NAME="IDX907"></A>
|
|
|
|
If the assembler gets a fatal signal, for any input whatever, that is a
|
|
<CODE>as</CODE> bug. Reliable assemblers never crash.
|
|
|
|
<A NAME="IDX908"></A>
|
|
<LI>
|
|
|
|
If <CODE>as</CODE> produces an error message for valid input, that is a bug.
|
|
|
|
<A NAME="IDX909"></A>
|
|
<LI>
|
|
|
|
If <CODE>as</CODE> 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".
|
|
|
|
<LI>
|
|
|
|
If you are an experienced user of assemblers, your suggestions for improvement
|
|
of <CODE>as</CODE> are welcome in any case.
|
|
</UL>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC271" HREF="as_toc.html#TOC271">How to report bugs</A></H2>
|
|
<P>
|
|
<A NAME="IDX910"></A>
|
|
<A NAME="IDX911"></A>
|
|
|
|
</P>
|
|
<P>
|
|
A number of companies and individuals offer support for GNU products. If
|
|
you obtained <CODE>as</CODE> from a support organization, we recommend you
|
|
contact that organization first.
|
|
|
|
</P>
|
|
<P>
|
|
You can find contact information for many support companies and
|
|
individuals in the file <TT>`etc/SERVICE'</TT> in the GNU Emacs
|
|
distribution.
|
|
|
|
</P>
|
|
<P>
|
|
In any event, we also recommend that you send bug reports for <CODE>as</CODE>
|
|
to <SAMP>`bug-gnu-utils@gnu.org'</SAMP>.
|
|
|
|
</P>
|
|
<P>
|
|
The fundamental principle of reporting bugs usefully is this:
|
|
<STRONG>report all the facts</STRONG>. If you are not sure whether to state a
|
|
fact or leave it out, state it!
|
|
|
|
</P>
|
|
<P>
|
|
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 symbol 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 name is stored in memory;
|
|
perhaps, if the name were different, the contents of that location would fool
|
|
the assembler 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.
|
|
|
|
</P>
|
|
<P>
|
|
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.
|
|
|
|
</P>
|
|
<P>
|
|
Sometimes people give a few sketchy facts and ask, "Does this ring a
|
|
bell?" Those bug reports are useless, and we urge everyone to
|
|
<EM>refuse to respond to them</EM> except to chide the sender to report
|
|
bugs properly.
|
|
|
|
</P>
|
|
<P>
|
|
To enable us to fix the bug, you should include all these things:
|
|
|
|
</P>
|
|
|
|
<UL>
|
|
<LI>
|
|
|
|
The version of <CODE>as</CODE>. <CODE>as</CODE> announces it if you start
|
|
it with the <SAMP>`--version'</SAMP> argument.
|
|
|
|
Without this, we will not know whether there is any point in looking for
|
|
the bug in the current version of <CODE>as</CODE>.
|
|
|
|
<LI>
|
|
|
|
Any patches you may have applied to the <CODE>as</CODE> source.
|
|
|
|
<LI>
|
|
|
|
The type of machine you are using, and the operating system name and
|
|
version number.
|
|
|
|
<LI>
|
|
|
|
What compiler (and its version) was used to compile <CODE>as</CODE>---e.g.
|
|
"<CODE>gcc-2.7</CODE>".
|
|
|
|
<LI>
|
|
|
|
The command arguments you gave the assembler to assemble your example and
|
|
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.
|
|
|
|
<LI>
|
|
|
|
A complete input file that will reproduce the bug. If the bug is observed when
|
|
the assembler is invoked via a compiler, send the assembler source, not the
|
|
high level language source. Most compilers will produce the assembler source
|
|
when run with the <SAMP>`-S'</SAMP> option. If you are using <CODE>gcc</CODE>, use
|
|
the options <SAMP>`-v --save-temps'</SAMP>; this will save the assembler source in a
|
|
file with an extension of <TT>`.s'</TT>, and also show you exactly how
|
|
<CODE>as</CODE> is being run.
|
|
|
|
<LI>
|
|
|
|
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 <CODE>as</CODE> 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
|
|
<CODE>as</CODE> 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.
|
|
|
|
<LI>
|
|
|
|
If you wish to suggest changes to the <CODE>as</CODE> source, send us context
|
|
diffs, as generated by <CODE>diff</CODE> with the <SAMP>`-u'</SAMP>, <SAMP>`-c'</SAMP>, or <SAMP>`-p'</SAMP>
|
|
option. Always send diffs from the old file to the new file. If you even
|
|
discuss something in the <CODE>as</CODE> 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.
|
|
</UL>
|
|
|
|
<P>
|
|
Here are some things that are not necessary:
|
|
|
|
</P>
|
|
|
|
<UL>
|
|
<LI>
|
|
|
|
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 <EM>instead</EM>
|
|
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.
|
|
|
|
<LI>
|
|
|
|
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 a program as complicated as <CODE>as</CODE> 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.
|
|
|
|
<LI>
|
|
|
|
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.
|
|
</UL>
|
|
|
|
<P><HR><P>
|
|
Go to the <A HREF="as_1.html">first</A>, <A HREF="as_24.html">previous</A>, <A HREF="as_26.html">next</A>, <A HREF="as_27.html">last</A> section, <A HREF="as_toc.html">table of contents</A>.
|
|
</BODY>
|
|
</HTML>
|