* doc/as.texinfo: Added section on reporting bugs.
This commit is contained in:
parent
eb1b89196c
commit
9a5acea834
|
@ -1,5 +1,7 @@
|
|||
Fri Nov 1 10:42:49 1996 Ian Lance Taylor <ian@cygnus.com>
|
||||
|
||||
* doc/as.texinfo: Added section on reporting bugs.
|
||||
|
||||
* config/tc-alpha.c: Change uses of void * to PTR. Change the
|
||||
alpha_macro emit field to expect a const argument, and change the
|
||||
arg field to be const. Fix some spacing to follow the GNU
|
||||
|
|
|
@ -170,6 +170,7 @@ code for @value{TARGET} architectures.
|
|||
* Expressions:: Expressions
|
||||
* Pseudo Ops:: Assembler Directives
|
||||
* Machine Dependencies:: Machine Dependent Features
|
||||
* Reporting Bugs:: Reporting Bugs
|
||||
* Acknowledgements:: Who Did What
|
||||
* Index:: Index
|
||||
@end menu
|
||||
|
@ -206,6 +207,12 @@ Here is a brief summary of how to invoke @code{@value{AS}}. For details,
|
|||
[ -mbig-endian | -mlittle-endian ]
|
||||
@end ifset
|
||||
@c end-sanitize-arc
|
||||
@c start-sanitize-d10v
|
||||
@ifset D10V
|
||||
[ -O ]
|
||||
@end ifset
|
||||
@c end-sanitize-d10v
|
||||
|
||||
@ifset H8
|
||||
@c Hitachi family chips have no machine-dependent assembler options
|
||||
@end ifset
|
||||
|
@ -352,6 +359,19 @@ Generate ``little endian'' format output.
|
|||
@end table
|
||||
@end ifset
|
||||
|
||||
@c start-sanitize-d10v
|
||||
@ifset D10V
|
||||
The following options are available when @value{AS} is configured for
|
||||
a D10V processor.
|
||||
@table @code
|
||||
@cindex D10V optimization
|
||||
@cindex optimization, D10V
|
||||
@item -O
|
||||
Optimize output by parallelizing instructions.
|
||||
@end table
|
||||
@end ifset
|
||||
@c end-sanitize-d10v
|
||||
|
||||
@ifset I960
|
||||
The following options are available when @value{AS} is configured for the
|
||||
Intel 80960 processor.
|
||||
|
@ -3003,6 +3023,8 @@ alignment required, as described below.
|
|||
The second expression (also absolute) gives the value to be stored in
|
||||
the padding bytes. It (and the comma) may be omitted. If it is
|
||||
omitted, the padding bytes are zero.
|
||||
For the alpha, if the section is marked as containing code and the
|
||||
padding expression is omitted, then the space is filled with no-ops.
|
||||
|
||||
The way the required alignment is specified varies from system to system.
|
||||
For the a29k, hppa, m68k, m88k, w65, sparc, and Hitachi SH, and i386 using ELF
|
||||
|
@ -4353,6 +4375,11 @@ subject, see the hardware manufacturer's manual.
|
|||
* ARC-Dependent:: ARC Dependent Features
|
||||
@end ifset
|
||||
@c end-sanitize-arc
|
||||
@c start-sanitize-d10v
|
||||
@ifset D10V
|
||||
* D10V-Dependent:: D10V Dependent Features
|
||||
@end ifset
|
||||
@c end-sanitize-d10v
|
||||
@ifset H8/300
|
||||
* H8/300-Dependent:: Hitachi H8/300 Dependent Features
|
||||
@end ifset
|
||||
|
@ -4499,6 +4526,12 @@ family.
|
|||
@end ifclear
|
||||
@end ifset
|
||||
|
||||
@c start-sanitize-d10v
|
||||
@ifset D10V
|
||||
@include c-d10v.texi
|
||||
@end ifset
|
||||
@c end-sanitize-d10v
|
||||
|
||||
@ifset H8/300
|
||||
@include c-h8300.texi
|
||||
@end ifset
|
||||
|
@ -4552,6 +4585,208 @@ family.
|
|||
@raisesections
|
||||
@end ifset
|
||||
|
||||
@node Reporting Bugs
|
||||
@chapter Reporting Bugs
|
||||
@cindex bugs in @code{@value{AS}}
|
||||
@cindex reporting bugs in @code{@value{AS}}
|
||||
|
||||
Your bug reports play an essential role in making @code{@value{AS}} 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 @code{@value{AS}} work better.
|
||||
Bug reports are your contribution to the maintenance of @code{@value{AS}}.
|
||||
|
||||
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 assembler crash
|
||||
@cindex crash of assembler
|
||||
@item
|
||||
If the assembler gets a fatal signal, for any input whatever, that is a
|
||||
@code{@value{AS}} bug. Reliable assemblers never crash.
|
||||
|
||||
@cindex error on valid input
|
||||
@item
|
||||
If @code{@value{AS}} produces an error message for valid input, that is a bug.
|
||||
|
||||
@cindex invalid input
|
||||
@item
|
||||
If @code{@value{AS}} 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 assemblers, your suggestions for improvement
|
||||
of @code{@value{AS}} are welcome in any case.
|
||||
@end itemize
|
||||
|
||||
@node Bug Reporting
|
||||
@section How to report bugs
|
||||
@cindex bug reports
|
||||
@cindex @code{@value{AS}} bugs, reporting
|
||||
|
||||
A number of companies and individuals offer support for @sc{gnu} products. If
|
||||
you obtained @code{@value{AS}} 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 @code{@value{AS}}
|
||||
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 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.
|
||||
|
||||
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 @code{@value{AS}}. @code{@value{AS}} announces it if you start
|
||||
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 @code{@value{AS}}.
|
||||
|
||||
@item
|
||||
Any patches you may have applied to the @code{@value{AS}} source.
|
||||
|
||||
@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 @code{@value{AS}}---e.g.
|
||||
``@code{gcc-2.7}''.
|
||||
|
||||
@item
|
||||
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.
|
||||
|
||||
@item
|
||||
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} option. If you are using @code{@value{GCC}}, use
|
||||
the options @samp{-v --save-temps}; this will save the assembler source in a
|
||||
file with an extension of @file{.s}, and also show you exactly how
|
||||
@code{@value{AS}} is being run.
|
||||
|
||||
@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 @code{@value{AS}} 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{@value{AS}} 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 @code{@value{AS}} 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{@value{AS}} 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 a program as complicated as @code{@value{AS}} 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 Acknowledgements
|
||||
@chapter Acknowledgements
|
||||
|
||||
|
|
Loading…
Reference in New Issue