diff options
Diffstat (limited to 'gdb/doc/gdb.bugs-m4')
-rwxr-xr-x | gdb/doc/gdb.bugs-m4 | 221 |
1 files changed, 0 insertions, 221 deletions
diff --git a/gdb/doc/gdb.bugs-m4 b/gdb/doc/gdb.bugs-m4 index 9647926..e69de29 100755 --- a/gdb/doc/gdb.bugs-m4 +++ b/gdb/doc/gdb.bugs-m4 @@ -1,221 +0,0 @@ -_dnl__ Copyright (c) 1990 1991 Free Software Foundation, Inc. -_dnl__ This file is part of the source for the GDB manual. -@c M4 FRAGMENT: $Id$ -@node _GDBN__ Bugs, Renamed Commands, Emacs, Top -@chapter Reporting Bugs in _GDBN__ -@cindex Bugs in _GDBN__ -@cindex Reporting Bugs in _GDBN__ - -Your bug reports play an essential role in making _GDBN__ reliable. - -Reporting a bug may help you by bringing a solution to your problem, or it -may not. But in any case the principal function of a bug report is to help -the entire community by making the next version of _GDBN__ work better. Bug -reports are your contribution to the maintenance of _GDBN__. - -In order for a bug report to serve its purpose, you must include the -information that enables us to fix the bug. - -@menu -* Bug Criteria:: Have You Found a Bug? -* Bug Reporting:: How to Report Bugs -@end menu - -@node Bug Criteria, Bug Reporting, _GDBN__ Bugs, _GDBN__ Bugs -@section Have You Found a Bug? -@cindex Bug Criteria - -If you are not sure whether you have found a bug, here are some guidelines: - -@itemize @bullet -@item -@cindex Fatal Signal -@cindex Core Dump -If the debugger gets a fatal signal, for any input whatever, that is a -_GDBN__ bug. Reliable debuggers never crash. - -@item -@cindex error on Valid Input -If _GDBN__ produces an error message for valid input, that is a bug. - -@item -@cindex Invalid Input -If _GDBN__ does not produce an error message for invalid input, -that is a bug. However, you should note that your idea of -``invalid input'' might be our idea of ``an extension'' or ``support -for traditional practice''. - -@item -If you are an experienced user of debugging tools, your suggestions -for improvement of _GDBN__ are welcome in any case. -@end itemize - -@node Bug Reporting, , Bug Criteria, _GDBN__ Bugs -@section How to Report Bugs -@cindex Bug Reports -@cindex Compiler Bugs, Reporting - -A number of companies and individuals offer support for GNU products. -If you obtained _GDBN__ from a support organization, we recommend you -contact that organization first. - -Contact information for many support companies and individuals is -available in the file @file{etc/SERVICE} in the GNU Emacs distribution. - -In any event, we also recommend that you send bug reports for _GDBN__ to one -of these addresses: - -@example -bug-gdb@@prep.ai.mit.edu -@{ucbvax|mit-eddie|uunet@}!prep.ai.mit.edu!bug-gdb -@end example - -@strong{Do not send bug reports to @samp{info-gdb}, or to -@samp{help-gdb}, or to any newsgroups.} Most users of _GDBN__ do not want to -receive bug reports. Those that do, have arranged to receive @samp{bug-gdb}. - -The mailing list @samp{bug-gdb} has a newsgroup which serves as a -repeater. The mailing list and the newsgroup carry exactly the same -messages. Often people think of posting bug reports to the newsgroup -instead of mailing them. This appears to work, but it has one problem -which can be crucial: a newsgroup posting often lacks a mail path -back to the sender. Thus, if we need to ask for more information, we -may be unable to reach you. For this reason, it is better to send bug -reports to the mailing list. - -As a last resort, send bug reports on paper to: - -@example -GNU Debugger Bugs -545 Tech Square -Cambridge, MA 02139 -@end example - -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 assume 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 debugger 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 us to fix -the bug if it is new to us. It isn't as important what happens if -the bug is already known. Therefore, always write your bug reports on -the assumption that the bug has not been reported previously. - -Sometimes people give a few sketchy facts and ask, ``Does this ring a -bell?'' Those bug reports are useless, and we urge everyone to -@emph{refuse to respond to them} except to chide the sender to report -bugs properly. - -To enable us to fix the bug, you should include all these things: - -@itemize @bullet -@item -The version of _GDBN__. _GDBN__ announces it if you start with no -arguments; you can also print it at any time using @code{show version}. - -Without this, we won't know whether there is any point in looking for -the bug in the current version of _GDBN__. - -@item -A complete input script, and all necessary source files, that will -reproduce the bug. - -@item -What compiler (and its version) was used to compile _GDBN__---e.g. -``_GCC__-1.37.1''. - -@item -The command arguments you gave the compiler to compile your example and -observe the bug. For example, did you use @samp{-O}? To guarantee -you won't omit something important, list them all. - -If we were to try to guess the arguments, we would probably guess wrong -and then we might not encounter the bug. - -@item -The type of machine you are using, and the operating system name and -version number. - -@item -A description of what behavior you observe that you believe is -incorrect. For example, ``It gets a fatal signal.'' - -Of course, if the bug is that _GDBN__ gets a fatal signal, then we will -certainly notice it. But if the bug is incorrect output, we might not -notice unless it is glaringly wrong. We are human, after all. You -might as well not give us a chance to make a mistake. - -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 _GDBN__ 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 ours would not. If you told us to expect a crash, -then when ours fails to crash, we would know that the bug was not -happening for us. If you had not told us to expect a crash, then we -would not be able to draw any conclusion from our observations. - -@item -If you wish to suggest changes to the _GDBN__ source, send us context -diffs. If you even discuss something in the _GDBN__ source, refer to -it by context, not by line number. - -The line numbers in our development sources won't match those in your -sources. Your line numbers would convey no useful information to us. - -@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. -We recommend that you 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 for us. Errors in the -output will be easier to spot, running under the debugger will take -less time, etc. - -However, simplification is not vital; if you don't want to do this, -report the bug anyway and send us the entire test case you used. - -@item -A patch for the bug. - -A patch for the bug does help us 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 _GDBN__ 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 us 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. - -@item -A guess about what the bug is or what it depends on. - -Such guesses are usually wrong. Even we can't guess right about such -things without first using the debugger to find the facts. -@end itemize |