home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD1.bin / gnu / info / gcc.info-11 (.txt) < prev    next >
GNU Info File  |  1994-12-22  |  39KB  |  654 lines
  1. This is Info file gcc.info, produced by Makeinfo-1.55 from the input
  2. file gcc.texi.
  3.    This file documents the use and the internals of the GNU compiler.
  4.    Published by the Free Software Foundation 675 Massachusetts Avenue
  5. Cambridge, MA 02139 USA
  6.    Copyright (C) 1988, 1989, 1992, 1993, 1994 Free Software Foundation,
  7.    Permission is granted to make and distribute verbatim copies of this
  8. manual provided the copyright notice and this permission notice are
  9. preserved on all copies.
  10.    Permission is granted to copy and distribute modified versions of
  11. this manual under the conditions for verbatim copying, provided also
  12. that the sections entitled "GNU General Public License," "Funding for
  13. Free Software," and "Protect Your Freedom--Fight `Look And Feel'" are
  14. included exactly as in the original, and provided that the entire
  15. resulting derived work is distributed under the terms of a permission
  16. notice identical to this one.
  17.    Permission is granted to copy and distribute translations of this
  18. manual into another language, under the above conditions for modified
  19. versions, except that the sections entitled "GNU General Public
  20. License," "Funding for Free Software," and "Protect Your Freedom--Fight
  21. `Look And Feel'", and this permission notice, may be included in
  22. translations approved by the Free Software Foundation instead of in the
  23. original English.
  24. File: gcc.info,  Node: Bug Reporting,  Next: Sending Patches,  Prev: Bug Lists,  Up: Bugs
  25. How to Report Bugs
  26. ==================
  27.    The fundamental principle of reporting bugs usefully is this:
  28. *report all the facts*.  If you are not sure whether to state a fact or
  29. leave it out, state it!
  30.    Often people omit facts because they think they know what causes the
  31. problem and they conclude that some details don't matter.  Thus, you
  32. might assume that the name of the variable you use in an example does
  33. not matter.  Well, probably it doesn't, but one cannot be sure.
  34. Perhaps the bug is a stray memory reference which happens to fetch from
  35. the location where that name is stored in memory; perhaps, if the name
  36. were different, the contents of that location would fool the compiler
  37. into doing the right thing despite the bug.  Play it safe and give a
  38. specific, complete example.  That is the easiest thing for you to do,
  39. and the most helpful.
  40.    Keep in mind that the purpose of a bug report is to enable someone to
  41. fix the bug if it is not known.  It isn't very important what happens if
  42. the bug is already known.  Therefore, always write your bug reports on
  43. the assumption that the bug is not known.
  44.    Sometimes people give a few sketchy facts and ask, "Does this ring a
  45. bell?"  This cannot help us fix a bug, so it is basically useless.  We
  46. respond by asking for enough details to enable us to investigate.  You
  47. might as well expedite matters by sending them to begin with.
  48.    Try to make your bug report self-contained.  If we have to ask you
  49. for more information, it is best if you include all the previous
  50. information in your response, as well as the information that was
  51. missing.
  52.    Please report each bug in a separate message.  This makes it easier
  53. for us to track which bugs have been fixed and to forward your bugs
  54. reports to the appropriate maintainer.
  55.    To enable someone to investigate the bug, you should include all
  56. these things:
  57.    * The version of GNU CC.  You can get this by running it with the
  58.      `-v' option.
  59.      Without this, we won't know whether there is any point in looking
  60.      for the bug in the current version of GNU CC.
  61.    * A complete input file that will reproduce the bug.  If the bug is
  62.      in the C preprocessor, send a source file and any header files
  63.      that it requires.  If the bug is in the compiler proper (`cc1'),
  64.      run your source file through the C preprocessor by doing `gcc -E
  65.      SOURCEFILE > OUTFILE', then include the contents of OUTFILE in the
  66.      bug report.  (When you do this, use the same `-I', `-D' or `-U'
  67.      options that you used in actual compilation.)
  68.      A single statement is not enough of an example.  In order to
  69.      compile it, it must be embedded in a complete file of compiler
  70.      input; and the bug might depend on the details of how this is done.
  71.      Without a real example one can compile, all anyone can do about
  72.      your bug report is wish you luck.  It would be futile to try to
  73.      guess how to provoke the bug.  For example, bugs in register
  74.      allocation and reloading frequently depend on every little detail
  75.      of the function they happen in.
  76.      Even if the input file that fails comes from a GNU program, you
  77.      should still send the complete test case.  Don't ask the GNU CC
  78.      maintainers to do the extra work of obtaining the program in
  79.      question--they are all overworked as it is.  Also, the problem may
  80.      depend on what is in the header files on your system; it is
  81.      unreliable for the GNU CC maintainers to try the problem with the
  82.      header files available to them.  By sending CPP output, you can
  83.      eliminate this source of uncertainty and save us a certain
  84.      percentage of wild goose chases.
  85.    * The command arguments you gave GNU CC or GNU C++ to compile that
  86.      example and observe the bug.  For example, did you use `-O'?  To
  87.      guarantee you won't omit something important, list all the options.
  88.      If we were to try to guess the arguments, we would probably guess
  89.      wrong and then we would not encounter the bug.
  90.    * The type of machine you are using, and the operating system name
  91.      and version number.
  92.    * The operands you gave to the `configure' command when you installed
  93.      the compiler.
  94.    * A complete list of any modifications you have made to the compiler
  95.      source.  (We don't promise to investigate the bug unless it
  96.      happens in an unmodified compiler.  But if you've made
  97.      modifications and don't tell us, then you are sending us on a wild
  98.      goose chase.)
  99.      Be precise about these changes.  A description in English is not
  100.      enough--send a context diff for them.
  101.      Adding files of your own (such as a machine description for a
  102.      machine we don't support) is a modification of the compiler source.
  103.    * Details of any other deviations from the standard procedure for
  104.      installing GNU CC.
  105.    * A description of what behavior you observe that you believe is
  106.      incorrect.  For example, "The compiler gets a fatal signal," or,
  107.      "The assembler instruction at line 208 in the output is incorrect."
  108.      Of course, if the bug is that the compiler gets a fatal signal,
  109.      then one can't miss it.  But if the bug is incorrect output, the
  110.      maintainer might not notice unless it is glaringly wrong.  None of
  111.      us has time to study all the assembler code from a 50-line C
  112.      program just on the chance that one instruction might be wrong.
  113.      We need *you* to do this part!
  114.      Even if the problem you experience is a fatal signal, you should
  115.      still say so explicitly.  Suppose something strange is going on,
  116.      such as, your copy of the compiler is out of synch, or you have
  117.      encountered a bug in the C library on your system.  (This has
  118.      happened!)  Your copy might crash and the copy here would not.  If
  119.      you said to expect a crash, then when the compiler here fails to
  120.      crash, we would know that the bug was not happening.  If you don't
  121.      say to expect a crash, then we would not know whether the bug was
  122.      happening.  We would not be able to draw any conclusion from our
  123.      observations.
  124.      If the problem is a diagnostic when compiling GNU CC with some
  125.      other compiler, say whether it is a warning or an error.
  126.      Often the observed symptom is incorrect output when your program
  127.      is run.  Sad to say, this is not enough information unless the
  128.      program is short and simple.  None of us has time to study a large
  129.      program to figure out how it would work if compiled correctly,
  130.      much less which line of it was compiled wrong.  So you will have
  131.      to do that.  Tell us which source line it is, and what incorrect
  132.      result happens when that line is executed.  A person who
  133.      understands the program can find this as easily as finding a bug
  134.      in the program itself.
  135.