binutils: Bug Reporting

1 
1 19.2 How to Report Bugs
1 =======================
1 
1 A number of companies and individuals offer support for GNU products.
1 If you obtained the binary utilities from a support organization, we
1 recommend you 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 the
1 binary utilities to <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 file 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 pathname is stored in memory; perhaps, if the pathname were
1 different, the contents of that location would fool the utility into
1 doing the right thing despite the bug.  Play it safe and give a
1 specific, complete example.  That is the easiest thing for you to do,
1 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 the utility.  Each utility announces it if you start
1      it with the '--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 the binary utilities.
1 
1    * Any patches you may have applied to the source, including any
1      patches made to the 'BFD' library.
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 the
1      utilities--e.g.  "'gcc-2.7'".
1 
1    * The command arguments you gave the utility to observe the bug.  To
1      guarantee you will not omit something important, list them all.  A
1      copy of the Makefile (or the 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, or set of input files, that will reproduce
1      the bug.  If the utility is reading an object file or files, then
1      it is generally most helpful to send the actual object files.
1 
1      If the source files were produced exclusively using GNU programs
1      (e.g., 'gcc', 'gas', and/or the GNU 'ld'), then it may be OK to
1      send the source files rather than the object files.  In this case,
1      be sure to say exactly what version of 'gcc', or whatever, was used
1      to produce the object files.  Also say how 'gcc', or whatever, was
1      configured.
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 the utility gets a fatal signal, then
1      we will certainly notice it.  But if the bug is incorrect output,
1      we might not notice unless it is glaringly wrong.  You might as
1      well 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 the utility is out of sync, or you have
1      encountered a bug in the C library on your system.  (This has
1      happened!)  Your copy might crash and ours would not.  If you told
1      us to expect a crash, then when ours fails to crash, we would know
1      that the bug was not happening for us.  If you had not told us to
1      expect a crash, then we would not be able to draw any conclusion
1      from our observations.
1 
1    * If you wish to suggest changes to the 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 wish
1      to discuss something in the 'ld' source, refer to it by context,
1      not 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 programs as complicated as the binary utilities it
1      is very hard to construct an example that will make the program
1      follow a certain path through the code.  If you do not send us the
1      example, we will not be able to construct one, so we will not be
1      able to verify that 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