as: Bug Reporting
1
1 10.2 How to Report Bugs
1 =======================
1
1 A number of companies and individuals offer support for GNU products.
1 If you obtained 'as' from a support organization, we recommend you
1 contact that organization first.
1
1 You can find contact information for many support companies and
1 individuals in the file 'etc/SERVICE' in the GNU Emacs distribution.
1
1 In any event, we also recommend that you send bug reports for 'as' to
1 <http://www.sourceware.org/bugzilla/>.
1
1 The fundamental principle of reporting bugs usefully is this: *report
1 all the facts*. If you are not sure whether to state a fact or leave it
1 out, state it!
1
1 Often people omit facts because they think they know what causes the
1 problem and assume that some details do not matter. Thus, you might
1 assume that the name of a symbol you use in an example does not matter.
1 Well, probably it does not, but one cannot be sure. Perhaps the bug is
1 a stray memory reference which happens to fetch from the location where
1 that name is stored in memory; perhaps, if the name were different, the
1 contents of that location would fool the assembler into doing the right
1 thing despite the bug. Play it safe and give a specific, complete
1 example. That is the easiest thing for you to do, and the most helpful.
1
1 Keep in mind that the purpose of a bug report is to enable us to fix
1 the bug if it is new to us. Therefore, always write your bug reports on
1 the assumption that the bug has not been reported previously.
1
1 Sometimes people give a few sketchy facts and ask, "Does this ring a
1 bell?" This cannot help us fix a bug, so it is basically useless. We
1 respond by asking for enough details to enable us to investigate. You
1 might as well expedite matters by sending them to begin with.
1
1 To enable us to fix the bug, you should include all these things:
1
1 * The version of 'as'. 'as' announces it if you start it with the
1 '--version' argument.
1
1 Without this, we will not know whether there is any point in
1 looking for the bug in the current version of 'as'.
1
1 * Any patches you may have applied to the 'as' source.
1
1 * The type of machine you are using, and the operating system name
1 and version number.
1
1 * What compiler (and its version) was used to compile 'as'--e.g.
1 "'gcc-2.7'".
1
1 * The command arguments you gave the assembler to assemble your
1 example and observe the bug. To guarantee you will not omit
1 something important, list them all. A copy of the Makefile (or the
1 output from make) is sufficient.
1
1 If we were to try to guess the arguments, we would probably guess
1 wrong and then we might not encounter the bug.
1
1 * A complete input file that will reproduce the bug. If the bug is
1 observed when the assembler is invoked via a compiler, send the
1 assembler source, not the high level language source. Most
1 compilers will produce the assembler source when run with the '-S'
1 option. If you are using 'gcc', use the options '-v --save-temps';
1 this will save the assembler source in a file with an extension of
1 '.s', and also show you exactly how 'as' is being run.
1
1 * A description of what behavior you observe that you believe is
1 incorrect. For example, "It gets a fatal signal."
1
1 Of course, if the bug is that 'as' gets a fatal signal, then we
1 will certainly notice it. But if the bug is incorrect output, we
1 might not notice unless it is glaringly wrong. You might as well
1 not give us a chance to make a mistake.
1
1 Even if the problem you experience is a fatal signal, you should
1 still say so explicitly. Suppose something strange is going on,
1 such as, your copy of 'as' is out of sync, or you have encountered
1 a bug in the C library on your system. (This has happened!) Your
1 copy might crash and ours would not. If you told us to expect a
1 crash, then when ours fails to crash, we would know that the bug
1 was not happening for us. If you had not told us to expect a
1 crash, then we would not be able to draw any conclusion from our
1 observations.
1
1 * If you wish to suggest changes to the 'as' source, send us context
1 diffs, as generated by 'diff' with the '-u', '-c', or '-p' option.
1 Always send diffs from the old file to the new file. If you even
1 discuss something in the 'as' source, refer to it by context, not
1 by line number.
1
1 The line numbers in our development sources will not match those in
1 your sources. Your line numbers would convey no useful information
1 to us.
1
1 Here are some things that are not necessary:
1
1 * A description of the envelope of the bug.
1
1 Often people who encounter a bug spend a lot of time investigating
1 which changes to the input file will make the bug go away and which
1 changes will not affect it.
1
1 This is often time consuming and not very useful, because the way
1 we will find the bug is by running a single example under the
1 debugger with breakpoints, not by pure deduction from a series of
1 examples. We recommend that you save your time for something else.
1
1 Of course, if you can find a simpler example to report _instead_ of
1 the original one, that is a convenience for us. Errors in the
1 output will be easier to spot, running under the debugger will take
1 less time, and so on.
1
1 However, simplification is not vital; if you do not want to do
1 this, report the bug anyway and send us the entire test case you
1 used.
1
1 * A patch for the bug.
1
1 A patch for the bug does help us if it is a good one. But do not
1 omit the necessary information, such as the test case, on the
1 assumption that a patch is all we need. We might see problems with
1 your patch and decide to fix the problem another way, or we might
1 not understand it at all.
1
1 Sometimes with a program as complicated as 'as' it is very hard to
1 construct an example that will make the program follow a certain
1 path through the code. If you do not send us the example, we will
1 not be able to construct one, so we will not be able to verify that
1 the bug is fixed.
1
1 And if we cannot understand what bug you are trying to fix, or why
1 your patch should be an improvement, we will not install it. A
1 test case will help us to understand.
1
1 * A guess about what the bug is or what it depends on.
1
1 Such guesses are usually wrong. Even we cannot guess right about
1 such things without first using the debugger to find the facts.
1