gcc/doc/bugreport.texi

   1 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
   2 @c 1999, 2000, 2001, 2003 Free Software Foundation, Inc.
   3 @c This is part of the GCC manual.
   4 @c For copying conditions, see the file gcc.texi.
   5
   6 @node Bugs
   7 @chapter Reporting Bugs
   8 @cindex bugs
   9 @cindex reporting bugs
  10
  11 Your bug reports play an essential role in making GCC reliable.
  12
  13 When you encounter a problem, the first thing to do is to see if it is
  14 already known.  @xref{Trouble}.  If it isn't known, then you should
  15 report the problem.
  16
  17 Reporting a bug may help you by bringing a solution to your problem, or
  18 it may not.  (If it does not, look in the service directory; see
  19 @ref{Service}.)  In any case, the principal function of a bug report is
  20 to help the entire community by making the next version of GCC work
  21 better.  Bug reports are your contribution to the maintenance of GCC@.
  22
  23 Since the maintainers are very overloaded, we cannot respond to every
  24 bug report.  However, if the bug has not been fixed, we are likely to
  25 send you a patch and ask you to tell us whether it works.
  26
  27 In order for a bug report to serve its purpose, you must include the
  28 information that makes for fixing the bug.
  29
  30 @menu
  31 * Criteria:  Bug Criteria.   Have you really found a bug?
  32 * Reporting: Bug Reporting.  How to report a bug effectively.
  33 * Known: Trouble.            Known problems.
  34 * Help: Service.             Where to ask for help.
  35 @end menu
  36
  37 @node Bug Criteria,Bug Reporting,,Bugs
  38 @section Have You Found a Bug?
  39 @cindex bug criteria
  40
  41 If you are not sure whether you have found a bug, here are some guidelines:
  42
  43 @itemize @bullet
  44 @cindex fatal signal
  45 @cindex core dump
  46 @item
  47 If the compiler gets a fatal signal, for any input whatever, that is a
  48 compiler bug.  Reliable compilers never crash.
  49
  50 @cindex invalid assembly code
  51 @cindex assembly code, invalid
  52 @item
  53 If the compiler produces invalid assembly code, for any input whatever
  54 (except an @code{asm} statement), that is a compiler bug, unless the
  55 compiler reports errors (not just warnings) which would ordinarily
  56 prevent the assembler from being run.
  57
  58 @cindex undefined behavior
  59 @cindex undefined function value
  60 @cindex increment operators
  61 @item
  62 If the compiler produces valid assembly code that does not correctly
  63 execute the input source code, that is a compiler bug.
  64
  65 However, you must double-check to make sure, because you may have a
  66 program whose behavior is undefined, which happened by chance to give
  67 the desired results with another C or C++ compiler.
  68
  69 For example, in many nonoptimizing compilers, you can write @samp{x;}
  70 at the end of a function instead of @samp{return x;}, with the same
  71 results.  But the value of the function is undefined if @code{return}
  72 is omitted; it is not a bug when GCC produces different results.
  73
  74 Problems often result from expressions with two increment operators,
  75 as in @code{f (*p++, *p++)}.  Your previous compiler might have
  76 interpreted that expression the way you intended; GCC might
  77 interpret it another way.  Neither compiler is wrong.  The bug is
  78 in your code.
  79
  80 After you have localized the error to a single source line, it should
  81 be easy to check for these things.  If your program is correct and
  82 well defined, you have found a compiler bug.
  83
  84 @item
  85 If the compiler produces an error message for valid input, that is a
  86 compiler bug.
  87
  88 @cindex invalid input
  89 @item
  90 If the compiler does not produce an error message for invalid input,
  91 that is a compiler bug.  However, you should note that your idea of
  92 ``invalid input'' might be my idea of ``an extension'' or ``support
  93 for traditional practice''.
  94
  95 @item
  96 If you are an experienced user of one of the languages GCC supports, your
  97 suggestions for improvement of GCC are welcome in any case.
  98 @end itemize
  99
 100 @node Bug Reporting,Trouble,Bug Criteria,Bugs
 101 @section How and where to Report Bugs
 102 @cindex compiler bugs, reporting
 103
 104 Bugs should be reported to our bug database.  Please refer to
 105 @uref{http://gcc.gnu.org/bugs.html} for up-to-date instructions how to
 106 submit bug reports.  Copies of this file in HTML (@file{bugs.html}) and
 107 plain text (@file{BUGS}) are also part of GCC releases.