Commit | Line | Data |
---|---|---|
9bcc06ef RP |
1 | _dnl__ Copyright (c) 1990 1991 Free Software Foundation, Inc. |
2 | _dnl__ This file is part of the source for the GDB manual. | |
16e58d91 | 3 | @c M4 FRAGMENT: $Id$ |
9bcc06ef RP |
4 | @node _GDBN__ Bugs, Renamed Commands, Emacs, Top |
5 | @chapter Reporting Bugs in _GDBN__ | |
6 | @cindex Bugs in _GDBN__ | |
7 | @cindex Reporting Bugs in _GDBN__ | |
8 | ||
9 | Your bug reports play an essential role in making _GDBN__ reliable. | |
10 | ||
11 | Reporting a bug may help you by bringing a solution to your problem, or it | |
12 | may not. But in any case the principal function of a bug report is to help | |
13 | the entire community by making the next version of _GDBN__ work better. Bug | |
14 | reports are your contribution to the maintenance of _GDBN__. | |
15 | ||
16 | In order for a bug report to serve its purpose, you must include the | |
17 | information that enables us to fix the bug. | |
18 | ||
19 | @menu | |
20 | * Bug Criteria:: Have You Found a Bug? | |
21 | * Bug Reporting:: How to Report Bugs | |
22 | @end menu | |
23 | ||
24 | @node Bug Criteria, Bug Reporting, _GDBN__ Bugs, _GDBN__ Bugs | |
25 | @section Have You Found a Bug? | |
26 | @cindex Bug Criteria | |
27 | ||
28 | If you are not sure whether you have found a bug, here are some guidelines: | |
29 | ||
30 | @itemize @bullet | |
31 | @item | |
32 | @cindex Fatal Signal | |
33 | @cindex Core Dump | |
34 | If the debugger gets a fatal signal, for any input whatever, that is a | |
35 | _GDBN__ bug. Reliable debuggers never crash. | |
36 | ||
37 | @item | |
38 | @cindex error on Valid Input | |
39 | If _GDBN__ produces an error message for valid input, that is a bug. | |
40 | ||
41 | @item | |
42 | @cindex Invalid Input | |
43 | If _GDBN__ does not produce an error message for invalid input, | |
44 | that is a bug. However, you should note that your idea of | |
45 | ``invalid input'' might be our idea of ``an extension'' or ``support | |
46 | for traditional practice''. | |
47 | ||
48 | @item | |
49 | If you are an experienced user of debugging tools, your suggestions | |
50 | for improvement of _GDBN__ are welcome in any case. | |
51 | @end itemize | |
52 | ||
53 | @node Bug Reporting, , Bug Criteria, _GDBN__ Bugs | |
54 | @section How to Report Bugs | |
55 | @cindex Bug Reports | |
56 | @cindex Compiler Bugs, Reporting | |
57 | ||
58 | A number of companies and individuals offer support for GNU products. | |
59 | If you obtained _GDBN__ from a support organization, we recommend you | |
60 | contact that organization first. | |
61 | ||
62 | Contact information for many support companies and individuals is | |
63 | available in the file @file{etc/SERVICE} in the GNU Emacs distribution. | |
64 | ||
65 | In any event, we also recommend that you send bug reports for _GDBN__ to one | |
66 | of these addresses: | |
67 | ||
68 | @example | |
69 | bug-gdb@@prep.ai.mit.edu | |
70 | @{ucbvax|mit-eddie|uunet@}!prep.ai.mit.edu!bug-gdb | |
71 | @end example | |
72 | ||
73 | @strong{Do not send bug reports to @samp{info-gdb}, or to | |
74 | @samp{help-gdb}, or to any newsgroups.} Most users of _GDBN__ do not want to | |
75 | receive bug reports. Those that do, have arranged to receive @samp{bug-gdb}. | |
76 | ||
77 | The mailing list @samp{bug-gdb} has a newsgroup which serves as a | |
78 | repeater. The mailing list and the newsgroup carry exactly the same | |
79 | messages. Often people think of posting bug reports to the newsgroup | |
80 | instead of mailing them. This appears to work, but it has one problem | |
81 | which can be crucial: a newsgroup posting often lacks a mail path | |
82 | back to the sender. Thus, if we need to ask for more information, we | |
83 | may be unable to reach you. For this reason, it is better to send bug | |
84 | reports to the mailing list. | |
85 | ||
86 | As a last resort, send bug reports on paper to: | |
87 | ||
88 | @example | |
89 | GNU Debugger Bugs | |
90 | 545 Tech Square | |
91 | Cambridge, MA 02139 | |
92 | @end example | |
93 | ||
94 | The fundamental principle of reporting bugs usefully is this: | |
95 | @strong{report all the facts}. If you are not sure whether to state a | |
96 | fact or leave it out, state it! | |
97 | ||
98 | Often people omit facts because they think they know what causes the | |
99 | problem and assume that some details don't matter. Thus, you might | |
100 | assume that the name of the variable you use in an example does not matter. | |
101 | Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a | |
102 | stray memory reference which happens to fetch from the location where that | |
103 | name is stored in memory; perhaps, if the name were different, the contents | |
104 | of that location would fool the debugger into doing the right thing despite | |
105 | the bug. Play it safe and give a specific, complete example. That is the | |
106 | easiest thing for you to do, and the most helpful. | |
107 | ||
108 | Keep in mind that the purpose of a bug report is to enable us to fix | |
109 | the bug if it is new to us. It isn't as important what happens if | |
110 | the bug is already known. Therefore, always write your bug reports on | |
111 | the assumption that the bug has not been reported previously. | |
112 | ||
113 | Sometimes people give a few sketchy facts and ask, ``Does this ring a | |
114 | bell?'' Those bug reports are useless, and we urge everyone to | |
115 | @emph{refuse to respond to them} except to chide the sender to report | |
116 | bugs properly. | |
117 | ||
118 | To enable us to fix the bug, you should include all these things: | |
119 | ||
120 | @itemize @bullet | |
121 | @item | |
122 | The version of _GDBN__. _GDBN__ announces it if you start with no | |
123 | arguments; you can also print it at any time using @code{show version}. | |
124 | ||
125 | Without this, we won't know whether there is any point in looking for | |
126 | the bug in the current version of _GDBN__. | |
127 | ||
128 | @item | |
129 | A complete input script, and all necessary source files, that will | |
130 | reproduce the bug. | |
131 | ||
132 | @item | |
133 | What compiler (and its version) was used to compile _GDBN__---e.g. | |
134 | ``_GCC__-1.37.1''. | |
135 | ||
136 | @item | |
137 | The command arguments you gave the compiler to compile your example and | |
138 | observe the bug. For example, did you use @samp{-O}? To guarantee | |
139 | you won't omit something important, list them all. | |
140 | ||
141 | If we were to try to guess the arguments, we would probably guess wrong | |
142 | and then we might not encounter the bug. | |
143 | ||
144 | @item | |
145 | The type of machine you are using, and the operating system name and | |
146 | version number. | |
147 | ||
148 | @item | |
149 | A description of what behavior you observe that you believe is | |
150 | incorrect. For example, ``It gets a fatal signal.'' | |
151 | ||
152 | Of course, if the bug is that _GDBN__ gets a fatal signal, then we will | |
153 | certainly notice it. But if the bug is incorrect output, we might not | |
154 | notice unless it is glaringly wrong. We are human, after all. You | |
155 | might as well not give us a chance to make a mistake. | |
156 | ||
157 | Even if the problem you experience is a fatal signal, you should still | |
158 | say so explicitly. Suppose something strange is going on, such as, | |
159 | your copy of _GDBN__ is out of synch, or you have encountered a | |
160 | bug in the C library on your system. (This has happened!) Your copy | |
161 | might crash and ours would not. If you told us to expect a crash, | |
162 | then when ours fails to crash, we would know that the bug was not | |
163 | happening for us. If you had not told us to expect a crash, then we | |
164 | would not be able to draw any conclusion from our observations. | |
165 | ||
166 | @item | |
167 | If you wish to suggest changes to the _GDBN__ source, send us context | |
168 | diffs. If you even discuss something in the _GDBN__ source, refer to | |
169 | it by context, not by line number. | |
170 | ||
171 | The line numbers in our development sources won't match those in your | |
172 | sources. Your line numbers would convey no useful information to us. | |
173 | ||
174 | @end itemize | |
175 | ||
176 | Here are some things that are not necessary: | |
177 | ||
178 | @itemize @bullet | |
179 | @item | |
180 | A description of the envelope of the bug. | |
181 | ||
182 | Often people who encounter a bug spend a lot of time investigating | |
183 | which changes to the input file will make the bug go away and which | |
184 | changes will not affect it. | |
185 | ||
186 | This is often time consuming and not very useful, because the way we | |
187 | will find the bug is by running a single example under the debugger | |
188 | with breakpoints, not by pure deduction from a series of examples. | |
189 | We recommend that you save your time for something else. | |
190 | ||
191 | Of course, if you can find a simpler example to report @emph{instead} | |
192 | of the original one, that is a convenience for us. Errors in the | |
193 | output will be easier to spot, running under the debugger will take | |
194 | less time, etc. | |
195 | ||
196 | However, simplification is not vital; if you don't want to do this, | |
197 | report the bug anyway and send us the entire test case you used. | |
198 | ||
199 | @item | |
200 | A patch for the bug. | |
201 | ||
202 | A patch for the bug does help us if it is a good one. But don't omit | |
203 | the necessary information, such as the test case, on the assumption that | |
204 | a patch is all we need. We might see problems with your patch and decide | |
205 | to fix the problem another way, or we might not understand it at all. | |
206 | ||
207 | Sometimes with a program as complicated as _GDBN__ it is very hard to | |
208 | construct an example that will make the program follow a certain path | |
209 | through the code. If you don't send us the example, we won't be able | |
210 | to construct one, so we won't be able to verify that the bug is fixed. | |
211 | ||
212 | And if we can't understand what bug you are trying to fix, or why your | |
213 | patch should be an improvement, we won't install it. A test case will | |
214 | help us to understand. | |
215 | ||
216 | @item | |
217 | A guess about what the bug is or what it depends on. | |
218 | ||
219 | Such guesses are usually wrong. Even we can't guess right about such | |
220 | things without first using the debugger to find the facts. | |
221 | @end itemize |