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