mirror of
git://gcc.gnu.org/git/gcc.git
synced 2025-01-11 18:15:17 +08:00
bugreport.texi: Remove most of the bug reporting instructions and merge them into bugs.html.
* doc/bugreport.texi: Remove most of the bug reporting instructions and merge them into bugs.html. From-SVN: r66825
This commit is contained in:
parent
e083f3f926
commit
486772b126
@ -1,3 +1,8 @@
|
||||
2003-05-15 Wolfgang Bangerth <bangerth@dealii.org>
|
||||
|
||||
* doc/bugreport.texi: Remove most of the bug reporting
|
||||
instructions and merge them into bugs.html.
|
||||
|
||||
2003-05-14 Eric Christopher <echristo@redhat.com>
|
||||
|
||||
* combine.c: Fix header comments.
|
||||
|
@ -1,5 +1,5 @@
|
||||
@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
|
||||
@c 1999, 2000, 2001 Free Software Foundation, Inc.
|
||||
@c 1999, 2000, 2001, 2003 Free Software Foundation, Inc.
|
||||
@c This is part of the GCC manual.
|
||||
@c For copying conditions, see the file gcc.texi.
|
||||
|
||||
@ -29,14 +29,12 @@ information that makes for fixing the bug.
|
||||
|
||||
@menu
|
||||
* Criteria: Bug Criteria. Have you really found a bug?
|
||||
* Where: Bug Lists. Where to send your bug report.
|
||||
* Reporting: Bug Reporting. How to report a bug effectively.
|
||||
* GNATS: gccbug. You can use a bug reporting tool.
|
||||
* Known: Trouble. Known problems.
|
||||
* Help: Service. Where to ask for help.
|
||||
@end menu
|
||||
|
||||
@node Bug Criteria,Bug Lists,,Bugs
|
||||
@node Bug Criteria,Bug Reporting,,Bugs
|
||||
@section Have You Found a Bug?
|
||||
@cindex bug criteria
|
||||
|
||||
@ -99,293 +97,11 @@ If you are an experienced user of one of the languages GCC supports, your
|
||||
suggestions for improvement of GCC are welcome in any case.
|
||||
@end itemize
|
||||
|
||||
@node Bug Lists,Bug Reporting,Bug Criteria,Bugs
|
||||
@section Where to Report Bugs
|
||||
@cindex bug report mailing lists
|
||||
@kindex gcc-bugs@@gcc.gnu.org or bug-gcc@@gnu.org
|
||||
|
||||
Send bug reports for the GNU Compiler Collection to
|
||||
@email{gcc-bugs@@gcc.gnu.org}. In accordance with the GNU-wide
|
||||
convention, in which bug reports for tool ``foo'' are sent
|
||||
to @samp{bug-foo@@gnu.org}, the address @email{bug-gcc@@gnu.org}
|
||||
may also be used; it will forward to the address given above.
|
||||
|
||||
Please read @uref{http://gcc.gnu.org/bugs.html} for additional and/or
|
||||
more up-to-date bug reporting instructions before you post a bug report.
|
||||
|
||||
@node Bug Reporting,gccbug,Bug Lists,Bugs
|
||||
@section How to Report Bugs
|
||||
@node Bug Reporting,Trouble,Bug Criteria,Bugs
|
||||
@section How and where to Report Bugs
|
||||
@cindex compiler bugs, reporting
|
||||
|
||||
The fundamental principle of reporting bugs usefully is this:
|
||||
@strong{report all the facts}. If you are not sure whether to state a
|
||||
fact or leave it out, state it!
|
||||
|
||||
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.
|
||||
|
||||
To enable someone to investigate the bug, you should include all these
|
||||
things:
|
||||
|
||||
@itemize @bullet
|
||||
@item
|
||||
The version of GCC@. You can get this by running it with the
|
||||
@option{-v} option.
|
||||
|
||||
Without this, we won't know whether there is any point in looking for
|
||||
the bug in the current version of GCC@.
|
||||
|
||||
@item
|
||||
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 (@file{cc1}), send the
|
||||
preprocessor output generated by adding @option{-save-temps} to the
|
||||
compilation command (@pxref{Debugging Options}). When you do this, use
|
||||
the same @option{-I}, @option{-D} or @option{-U} options that you used in
|
||||
actual compilation. Then send the @var{input}.i or @var{input}.ii files
|
||||
generated.
|
||||
|
||||
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 GCC 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 GCC 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.
|
||||
|
||||
@item
|
||||
The command arguments you gave GCC to compile that example
|
||||
and observe the bug. For example, did you use @option{-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.
|
||||
|
||||
@item
|
||||
The type of machine you are using, and the operating system name and
|
||||
version number.
|
||||
|
||||
@item
|
||||
The operands you gave to the @code{configure} command when you installed
|
||||
the compiler.
|
||||
|
||||
@item
|
||||
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.
|
||||
|
||||
@item
|
||||
Details of any other deviations from the standard procedure for installing
|
||||
GCC@.
|
||||
|
||||
@item
|
||||
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 @emph{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 @i{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 GCC 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.
|
||||
|
||||
@item
|
||||
If you send examples of assembler code output from GCC,
|
||||
please use @option{-g} when you make them. The debugging information
|
||||
includes source line numbers which are essential for correlating the
|
||||
output with the input.
|
||||
|
||||
@item
|
||||
If you wish to mention something in the GCC 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.
|
||||
|
||||
@item
|
||||
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.
|
||||
|
||||
@cindex backtrace for bug reports
|
||||
For example, many people send just a backtrace, but that is never
|
||||
useful by itself. A simple backtrace with arguments conveys little
|
||||
about GCC 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.
|
||||
|
||||
@findex debug_rtx
|
||||
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 @code{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 @code{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.
|
||||
@end itemize
|
||||
|
||||
Here are some things that are not necessary:
|
||||
|
||||
@itemize @bullet
|
||||
@item
|
||||
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 debugger 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 @emph{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 GCC 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.
|
||||
|
||||
@item
|
||||
In particular, some people insert conditionals @samp{#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.
|
||||
|
||||
@item
|
||||
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 GCC 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 @uref{http://gcc.gnu.org/contribute.html}
|
||||
for guidelines on how to make it easy for us to
|
||||
understand and install your patches.
|
||||
|
||||
@item
|
||||
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.
|
||||
|
||||
@item
|
||||
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.
|
||||
@end itemize
|
||||
|
||||
@node gccbug,, Bug Reporting, Bugs
|
||||
@section The gccbug script
|
||||
@cindex gccbug script
|
||||
|
||||
To simplify creation of bug reports, and to allow better tracking of
|
||||
reports, we use the GNATS bug tracking system. Part of that system is
|
||||
the @command{gccbug} script. This is a Unix shell script, so you need a
|
||||
shell to run it. It is normally installed in the same directory where
|
||||
@command{gcc} is installed.
|
||||
|
||||
The gccbug script is derived from send-pr, @pxref{using
|
||||
send-pr,,Creating new Problem Reports,send-pr,Reporting Problems}. When
|
||||
invoked, it starts a text editor so you can fill out the various fields
|
||||
of the report. When the you quit the editor, the report is automatically
|
||||
send to the bug reporting address.
|
||||
|
||||
A number of fields in this bug report form are specific to GCC, and are
|
||||
explained at @uref{http://gcc.gnu.org/gnats.html}.
|
||||
Bugs should be reported to our bug database. Please refer to
|
||||
@uref{http://gcc.gnu.org/bugs.html} for up-to-date instructions how to
|
||||
submit bug reports. Copies of this file in HTML (@file{bugs.html}) and
|
||||
plain text (@file{BUGS}) are also part of GCC releases.
|
||||
|
@ -1,3 +1,8 @@
|
||||
2003-05-15 Wolfgang Bangerth <bangerth@dealii.org>
|
||||
|
||||
* g77.texi: Remove most of the bug reporting instructions and
|
||||
merge them into bugs.html.
|
||||
|
||||
2003-05-13 Zack Weinberg <zack@codesourcery.com>
|
||||
|
||||
* com.c: Replace all calls to fatal_io_error with calls to
|
||||
|
346
gcc/f/g77.texi
346
gcc/f/g77.texi
@ -2,8 +2,8 @@
|
||||
@c %**start of header
|
||||
@setfilename g77.info
|
||||
|
||||
@set last-update 2002-04-29
|
||||
@set copyrights-g77 1995,1996,1997,1998,1999,2000,2001,2002
|
||||
@set last-update 2003-05-13
|
||||
@set copyrights-g77 1995,1996,1997,1998,1999,2000,2001,2002,2003
|
||||
|
||||
@include root.texi
|
||||
|
||||
@ -10445,7 +10445,6 @@ information that makes for fixing the bug.
|
||||
|
||||
@menu
|
||||
* Criteria: Bug Criteria. Have you really found a bug?
|
||||
* Where: Bug Lists. Where to send your bug report.
|
||||
* Reporting: Bug Reporting. How to report a bug effectively.
|
||||
@end menu
|
||||
|
||||
@ -10636,348 +10635,15 @@ It might mean the bug is in your code, and that @command{g77} simply
|
||||
exposes it more readily than other compilers.
|
||||
@end itemize
|
||||
|
||||
@node Bug Lists
|
||||
@section Where to Report Bugs
|
||||
@cindex bug report mailing lists
|
||||
@kindex @value{email-bugs}
|
||||
Send bug reports for GNU Fortran to @email{@value{email-bugs}}.
|
||||
|
||||
Often people think of posting bug reports to a newsgroup instead of
|
||||
mailing them.
|
||||
This sometimes appears to work, but it has one problem which can be
|
||||
crucial: a newsgroup posting does not contain a mail path back to the
|
||||
sender.
|
||||
Thus, if maintainers need more information, they might be unable
|
||||
to reach you. For this reason, you should always send bug reports by
|
||||
mail to the proper mailing list.
|
||||
|
||||
As a last resort, send bug reports on paper to:
|
||||
|
||||
@example
|
||||
GNU Compiler Bugs
|
||||
Free Software Foundation
|
||||
59 Temple Place - Suite 330
|
||||
Boston, MA 02111-1307, USA
|
||||
@end example
|
||||
|
||||
@node Bug Reporting
|
||||
@section How to Report Bugs
|
||||
@cindex compiler bugs, reporting
|
||||
|
||||
The fundamental principle of reporting bugs usefully is this:
|
||||
@strong{report all the facts}.
|
||||
If you are not sure whether to state a
|
||||
fact or leave it out, state it!
|
||||
Bugs should be reported to our bug database. Please refer to
|
||||
@uref{http://gcc.gnu.org/bugs.html} for up-to-date instructions how to
|
||||
submit bug reports. Copies of this file in HTML (@file{bugs.html}) and
|
||||
plain text (@file{BUGS}) are also part of GCC releases.
|
||||
|
||||
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 rarely helpful.
|
||||
We respond by asking for enough details to enable us to investigate.
|
||||
You might as well expedite matters by sending them to begin with.
|
||||
(Besides, there are enough bells ringing around here as it is.)
|
||||
|
||||
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 @file{uuencode}.
|
||||
If you do so it will slow down the processing
|
||||
of your bug.
|
||||
If you must submit multiple large files, use @file{shar},
|
||||
which allows us to read your message without having to run any
|
||||
decompression programs.
|
||||
|
||||
(As a special exception for GNU Fortran bug-reporting, at least
|
||||
for now, if you are sending more than a few lines of code, if
|
||||
your program's source file format contains ``interesting'' things
|
||||
like trailing spaces or strange characters, or if you need to
|
||||
include binary data files, it is acceptable to put all the
|
||||
files together in a @command{tar} archive, and, whether you need to
|
||||
do that, it is acceptable to then compress the single file (@command{tar}
|
||||
archive or source file)
|
||||
using @command{gzip} and encode it via @command{uuencode}.
|
||||
Do not use any MIME stuff---the current maintainer can't decode this.
|
||||
Using @command{compress} instead of @command{gzip} is acceptable, assuming
|
||||
you have licensed the use of the patented algorithm in
|
||||
@command{compress} from Unisys.)
|
||||
|
||||
To enable someone to investigate the bug, you should include all these
|
||||
things:
|
||||
|
||||
@itemize @bullet
|
||||
@item
|
||||
The version of GNU Fortran.
|
||||
You can get this by running @command{g77} with the @option{-v} option.
|
||||
(Ignore any error messages that might be displayed
|
||||
when the linker is run.)
|
||||
|
||||
Without this, we won't know whether there is any point in looking for
|
||||
the bug in the current version of GNU Fortran.
|
||||
|
||||
@item
|
||||
@cindex preprocessor
|
||||
@cindex cpp program
|
||||
@cindex programs, cpp
|
||||
@pindex cpp
|
||||
A complete input file that will reproduce the bug.
|
||||
|
||||
If your source file(s) require preprocessing
|
||||
(for example, their names have suffixes like
|
||||
@samp{.F}, @samp{.fpp}, @samp{.FPP}, and @samp{.r}),
|
||||
and the bug is in the compiler proper (@file{f771})
|
||||
or in a subsequent phase of processing,
|
||||
run your source file through the C preprocessor
|
||||
by doing @samp{g77 -E @var{sourcefile} > @var{newfile}}.
|
||||
Then, include the contents of @var{newfile} in the bug report.
|
||||
(When you do this, use the same preprocessor options---such as
|
||||
@option{-I}, @option{-D}, and @option{-U}---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.
|
||||
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
|
||||
can depend on every little detail of the source and include files
|
||||
that trigger them.
|
||||
|
||||
@item
|
||||
@cindex included files
|
||||
@cindex INCLUDE directive
|
||||
@cindex directive, INCLUDE
|
||||
@cindex #include directive
|
||||
@cindex directive, #include
|
||||
Note that you should include with your bug report any files
|
||||
included by the source file
|
||||
(via the @code{#include} or @code{INCLUDE} directive)
|
||||
that you send, and any files they include, and so on.
|
||||
|
||||
It is not necessary to replace
|
||||
the @code{#include} and @code{INCLUDE} directives
|
||||
with the actual files in the version of the source file that
|
||||
you send, but it might make submitting the bug report easier
|
||||
in the end.
|
||||
However, be sure to @emph{reproduce} the bug using the @emph{exact}
|
||||
version of the source material you submit, to avoid wild-goose
|
||||
chases.
|
||||
|
||||
@item
|
||||
The command arguments you gave GNU Fortran to compile that example
|
||||
and observe the bug. For example, did you use @option{-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.
|
||||
|
||||
@item
|
||||
The type of machine you are using, and the operating system name and
|
||||
version number.
|
||||
(Much of this information is printed by @samp{g77 -v}---if you
|
||||
include that, send along any additional info you have that you
|
||||
don't see clearly represented in that output.)
|
||||
|
||||
@item
|
||||
The operands you gave to the @command{configure} command when you installed
|
||||
the compiler.
|
||||
|
||||
@item
|
||||
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.
|
||||
|
||||
@item
|
||||
Details of any other deviations from the standard procedure for installing
|
||||
GNU Fortran.
|
||||
|
||||
@item
|
||||
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 Fortran program just on the chance that
|
||||
one instruction might be wrong. We need @emph{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 @i{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 building GNU Fortran 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.
|
||||
|
||||
@item
|
||||
If you send examples of assembler code output from GNU Fortran,
|
||||
please use @option{-g} when you make them. The debugging information
|
||||
includes source line numbers which are essential for correlating the
|
||||
output with the input.
|
||||
|
||||
@item
|
||||
If you wish to mention something in the GNU Fortran 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 convenient information to the
|
||||
maintainers.
|
||||
|
||||
@item
|
||||
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.
|
||||
|
||||
@cindex backtrace for bug reports
|
||||
For example, many people send just a backtrace, but that is never
|
||||
useful by itself. A simple backtrace with arguments conveys little
|
||||
about GNU Fortran 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.
|
||||
|
||||
@findex debug_rtx
|
||||
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 @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 @code{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.
|
||||
@end itemize
|
||||
|
||||
Here are some things that are not necessary:
|
||||
|
||||
@itemize @bullet
|
||||
@item
|
||||
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 debugger 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 @emph{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 Fortran 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 might 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.
|
||||
|
||||
@item
|
||||
In particular, some people insert conditionals @samp{#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 preprocessor output, and that can't have conditionals.
|
||||
|
||||
@item
|
||||
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 Fortran 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 @uref{http://gcc.gnu.org/contribute.html}
|
||||
for guidelines on how to make it easy for us to
|
||||
understand and install your patches.
|
||||
|
||||
@item
|
||||
A guess about what the bug is or what it depends on.
|
||||
|
||||
Such guesses are usually wrong. Even the maintainer can't guess right
|
||||
about such things without first using the debugger to find the facts.
|
||||
|
||||
@item
|
||||
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.
|
||||
@end itemize
|
||||
|
||||
@node Service
|
||||
@chapter How To Get Help with GNU Fortran
|
||||
|
Loading…
Reference in New Issue
Block a user