add directory study
This commit is contained in:
gohigh
266
study/Ref-docs/manual as/as_25.html
Normal file
266
study/Ref-docs/manual as/as_25.html
Normal file
@@ -0,0 +1,266 @@
|
||||
<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>
|
||||
Reference in New Issue
Block a user