Contents|Index|Previous|Next
How
to report bugs
For those with valid support
agreements with Cygnus, see the Cygnus website:
The fundamental principle of
reporting bugs usefully is this: report all the facts. If
you are not sure whether to state a fact or leave it out, state it!
See Sending
patches for GNU CC for guidelines on how to make it easy for us to
understand and install your patches.
Often people omit facts because
they think they know what causes the problem and they conclude that some
details don’t matter. Thus, you might assume that the name of the variable
you use in an example does not matter. Well, probably it doesn’t, but one
cannot be sure. Perhaps the bug is a stray memory reference which happens
to fetch from the location where that name is stored in memory; perhaps,
if the name were different, the contents of that location would fool the
compiler into doing the right thing despite the bug. Play it safe and give
a specific, complete example. That is the easiest thing for you to do,
and the most helpful.
Keep in mind that the purpose
of a bug report is to enable someone to fix the bug if it is not known.
It isn’t very important what happens if the bug is already known. Therefore,
always write your bug reports on the assumption that the bug is not known.
Sometimes people give a few
sketchy facts and ask, “Does this ring a bell?” This cannot help us fix
a bug, so it is basically useless. We respond by asking for enough details
to enable us to investigate. You might as well expedite matters by sending
them to begin with.
Try to make your bug report
self-contained. If we have to ask you for more information, it is best
if you include all the previous information in your response, as well as
the information that was missing.
Please report each bug in
a separate message. This makes it easier for us to track which bugs have
been fixed and to forward your bugs reports to the appropriate maintainer.
Do not compress and encode
any part of your bug report using programs such as ‘uuencode’.
If you do so it will slow down the processing of your bug. If you must
submit multiple large files, use ‘shar’,
which allows us to read your message without having to run any decompression
programs.
To enable someone to investigate
the bug, you should include all these things:
-
The version of GNU CC. You can
get this by running it with the ‘-v’
option.
Without this, we won’t know
whether there is any point in looking for the bug in the current version
of GNU CC.
-
A complete input file that will
reproduce the bug. If the bug is in the C preprocessor, send a source file
and any header files that it requires. If the bug is in the compiler proper
(cc1),
run your source file through the C preprocessor by doing ‘gcc
-E sourcefile > outfile’,
then include the contents of outfile in the bug report. (When you do this,
use the same ‘-I’,
‘-D’
or ‘-U’
options that you used in actual compilation.)
A single statement is not
enough of an example. In order to compile it, it must be embedded in a
complete file of compiler input; and the bug might depend on the details
of how this is done.
Without a real example one
can compile, all anyone can do about your bug report is wish you luck.
It would be futile to try to guess how to provoke the bug. For example,
bugs in register allocation and reloading frequently depend on every little
detail of the function they happen in.
Even if the input file that
fails comes from a GNU program, you should still send the complete test
case. Don’t ask the GNU CC maintainers to do the extra work of obtaining
the program in question—they are all overworked as it is. Also, the problem
may depend on what is in the header files on your system; it is unreliable
for the GNU CC maintainers to try the problem with the header files available
to them. By sending CPP output, you can eliminate this source of uncertainty
and save us a certain percentage of wild goose chases.
-
The command arguments you gave
GNU CC or GNU C++ to compile that example and observe the bug. For example,
did you use ‘-O’?
To guarantee you won’t omit something important, list all the options.
If we were to try to guess
the arguments, we would probably guess wrong and then we would not encounter
the bug.
-
The type of machine you are
using, and the operating system name and version number.
-
The operands you gave to the
configure command when you installed the compiler.
-
A complete list of any modifications
you have made to the compiler source. (We don’t promise to investigate
the bug unless it happens in an unmodified compiler. But if you’ve made
modifications and don’t tell us, then you are sending us on a wild goose
chase.)
Be precise about these changes.
A description in English is not enough—send a context diff
for them.
Adding files of your own
(such as a machine description for a machine we don’t support) is a modification
of the compiler source.
-
Details of any other deviations
from the standard procedure for installing GNU CC.
-
A description of what behavior
you observe that you believe is incorrect. For example, “The compiler gets
a fatal signal,” or, “The assembler instruction at line 208 in the output
is incorrect.”
Of course, if the bug is
that the compiler gets a fatal signal, then one can’t miss it. But if the
bug is incorrect output, the maintainer might not notice unless it is glaringly
wrong. None of us has time to study all the assembler code from a 50-line
C program just on the chance that one instruction might be wrong. We
need you to do this part!
Even if the problem you
experience is a fatal signal, you should still say so explicitly. Suppose
something strange is going on, such as, your copy of the compiler is out
of synch, or you have encountered a bug in the C library on your system.
(This has happened!) Your copy might crash and the copy here would not.
If you said to expect a crash, then when the compiler here fails
to crash, we would know that the bug was not happening. If you don’t say
to expect a crash, then we would not know whether the bug was happening.
We would not be able to draw any conclusion from our observations.
If the problem is a diagnostic
when compiling GNU CC with some other compiler, say whether it is a warning
or an error.
Often the observed symptom
is incorrect output when your program is run. Sad to say, this is not enough
information unless the program is short and simple. None of us has time
to study a large program to figure out how it would work if compiled correctly,
much less which line of it was compiled wrong. So you will have to do that.
Tell us which source line it is, and what incorrect result happens when
that line is executed. A person who understands the program can find this
as easily as finding a bug in the program itself.
-
If you send examples of assembler
code output from GNU CC or GNU C++, please use ‘-g’
when you make them. The debugging information includes source line numbers
which are essential for correlating the output with the input.
If you wish to mention something
in the GNU CC source, refer to it by context, not by line number.
The line numbers in the
development sources don’t match those in your sources. Your line numbers
would convey no useful information to the maintainers.
-
Additional information from
a debugger might enable someone to find a problem on a machine which he
does not have available. However, you need to think when you collect this
information if you want it to have any chance of being useful.
For example, many people
send just a backtrace, but that is never useful by itself. A simple backtrace
with arguments conveys little about GNU CC because the compiler is largely
data-driven; the same functions are called over and over for different
RTL insns, doing different things depending on the details of the insn.
Most of the arguments listed
in the backtrace are useless because they are pointers to RTL list structure.
The numeric values of the pointers, which the debugger prints in the backtrace,
have no significance whatever; all that matters is the contents of the
objects they point to (and most of the contents are other such pointers).
In addition, most compiler
passes consist of one or more loops that scan the RTL insn sequence. The
most vital piece of information about such a loop—which insn it has reached—is
usually in a local variable, not in an argument.
What you need to provide
in addition to a backtrace are the values of the local variables for several
stack frames up. When a local variable or an argument is an RTX, first
print its value and then use the GDB command pr
to print the RTL expression that it points to. (If GDB doesn’t run on your
machine, use your debugger to call the function debug_rtx
with the RTX as an argument.) In general, whenever a variable is a pointer,
its value is no use without the data it points to.
What follows are some things
that are not necessary.
-
A description of the envelope
of the bug.
Often people who encounter
a bug spend a lot of time investigating which changes to the input file
will make the bug go away and which changes will not affect it. This is
often time consuming and not very useful, because the way we will find
the bug is by running a single example under the de-bugger with breakpoints,
not by pure deduction from a series of examples. You might as well save
your time for something else. Of course, if you can find a simpler example
to report instead of the original one, that is a convenience. Errors in
the output will be easier to spot, running under the debugger will take
less time, etc. Most GNU CC bugs involve just one function, so the most
straightforward way to simplify an example is to delete all the function
definitions except the one where the bug occurs. Those earlier in the file
may be replaced by external declarations if the crucial function depends
on them. (Exception: inline functions may affect compilation of functions
defined later in the file.)
However, simplification
is not vital; if you don’t want to do this, report the bug anyway and send
the entire test case you used.
In particular, some people
insert conditionals (#ifdef
BUG) around a
statement which, if removed, makes the bug not happen. These are just clutter;
we won’t pay any attention to them anyway. Besides, you should send us
cpp output, and that can’t have conditionals.
-
A patch for the bug.
A patch for the bug is useful
if it is a good one. But don’t omit the necessary information, such as
the test case, on the assumption that a patch is all we need.
We might see problems with
your patch and decide to fix the problem another way, or we might not understand
it at all.
Sometimes with a program
as complicated as GNU CC it is very hard to construct an example that will
make the program follow a certain path through the code.
If you don’t send the example,
we won’t be able to construct one, so we won’t be able to verify that the
bug is fixed.
And if we can’t understand
what bug you are trying to fix, or why your patch should be an improvement,
we won’t install it. A test case will help us to understand.
See Sending
patches for GNU CC for guidelines on how to make it easy for us to
understand and install your patches.
-
A guess about what the bug is
or what it depends on. Such guesses are usually wrong. Even I can’t guess
right about such things without first using the debugger to find the facts.
-
A core dump file. We have no
way of examining a core dump for your type of machine unless we have an
identical system—and if we do have one, we should be able to reproduce
the crash ourselves.
Top|Contents|Index|Previous|Next