Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | .\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "PERLBUG 1" | |
132 | .TH PERLBUG 1 "2002-08-28" "perl v5.8.0" "Perl Programmers Reference Guide" | |
133 | .SH "NAME" | |
134 | perlbug \- how to submit bug reports on Perl | |
135 | .SH "SYNOPSIS" | |
136 | .IX Header "SYNOPSIS" | |
137 | \&\fBperlbug\fR [\ \fB\-v\fR\ ] [\ \fB\-a\fR\ \fIaddress\fR\ ] [\ \fB\-s\fR\ \fIsubject\fR\ ] | |
138 | [\ \fB\-b\fR\ \fIbody\fR\ |\ \fB\-f\fR\ \fIinputfile\fR\ ] [\ \fB\-F\fR\ \fIoutputfile\fR\ ] | |
139 | [\ \fB\-r\fR\ \fIreturnaddress\fR\ ] | |
140 | [\ \fB\-e\fR\ \fIeditor\fR\ ] [\ \fB\-c\fR\ \fIadminaddress\fR\ |\ \fB\-C\fR\ ] | |
141 | [\ \fB\-S\fR\ ] [\ \fB\-t\fR\ ] [\ \fB\-d\fR\ ] [\ \fB\-A\fR\ ] [\ \fB\-h\fR\ ] | |
142 | .PP | |
143 | \&\fBperlbug\fR [\ \fB\-v\fR\ ] [\ \fB\-r\fR\ \fIreturnaddress\fR\ ] | |
144 | [\ \fB\-A\fR\ ] [\ \fB\-ok\fR\ |\ \fB\-okay\fR\ |\ \fB\-nok\fR\ |\ \fB\-nokay\fR\ ] | |
145 | .SH "DESCRIPTION" | |
146 | .IX Header "DESCRIPTION" | |
147 | A program to help generate bug reports about perl or the modules that | |
148 | come with it, and mail them. | |
149 | .PP | |
150 | If you have found a bug with a non-standard port (one that was not part | |
151 | of the \fIstandard distribution\fR), a binary distribution, or a | |
152 | non-standard module (such as Tk, \s-1CGI\s0, etc), then please see the | |
153 | documentation that came with that distribution to determine the correct | |
154 | place to report bugs. | |
155 | .PP | |
156 | \&\f(CW\*(C`perlbug\*(C'\fR is designed to be used interactively. Normally no arguments | |
157 | will be needed. Simply run it, and follow the prompts. | |
158 | .PP | |
159 | If you are unable to run \fBperlbug\fR (most likely because you don't have | |
160 | a working setup to send mail that perlbug recognizes), you may have to | |
161 | compose your own report, and email it to \fBperlbug@perl.org\fR. You might | |
162 | find the \fB\-d\fR option useful to get summary information in that case. | |
163 | .PP | |
164 | In any case, when reporting a bug, please make sure you have run through | |
165 | this checklist: | |
166 | .IP "What version of Perl you are running?" 4 | |
167 | .IX Item "What version of Perl you are running?" | |
168 | Type \f(CW\*(C`perl \-v\*(C'\fR at the command line to find out. | |
169 | .IP "Are you running the latest released version of perl?" 4 | |
170 | .IX Item "Are you running the latest released version of perl?" | |
171 | Look at http://www.perl.com/ to find out. If it is not the latest | |
172 | released version, get that one and see whether your bug has been | |
173 | fixed. Note that bug reports about old versions of Perl, especially | |
174 | those prior to the 5.0 release, are likely to fall upon deaf ears. | |
175 | You are on your own if you continue to use perl1 .. perl4. | |
176 | .IP "Are you sure what you have is a bug?" 4 | |
177 | .IX Item "Are you sure what you have is a bug?" | |
178 | A significant number of the bug reports we get turn out to be documented | |
179 | features in Perl. Make sure the behavior you are witnessing doesn't fall | |
180 | under that category, by glancing through the documentation that comes | |
181 | with Perl (we'll admit this is no mean task, given the sheer volume of | |
182 | it all, but at least have a look at the sections that \fIseem\fR relevant). | |
183 | .Sp | |
184 | Be aware of the familiar traps that perl programmers of various hues | |
185 | fall into. See perltrap. | |
186 | .Sp | |
187 | Check in perldiag to see what any Perl error message(s) mean. | |
188 | If message isn't in perldiag, it probably isn't generated by Perl. | |
189 | Consult your operating system documentation instead. | |
190 | .Sp | |
191 | If you are on a non-UNIX platform check also perlport, as some | |
192 | features may be unimplemented or work differently. | |
193 | .Sp | |
194 | Try to study the problem under the Perl debugger, if necessary. | |
195 | See perldebug. | |
196 | .IP "Do you have a proper test case?" 4 | |
197 | .IX Item "Do you have a proper test case?" | |
198 | The easier it is to reproduce your bug, the more likely it will be | |
199 | fixed, because if no one can duplicate the problem, no one can fix it. | |
200 | A good test case has most of these attributes: fewest possible number | |
201 | of lines; few dependencies on external commands, modules, or | |
202 | libraries; runs on most platforms unimpeded; and is self\-documenting. | |
203 | .Sp | |
204 | A good test case is almost always a good candidate to be on the perl | |
205 | test suite. If you have the time, consider making your test case so | |
206 | that it will readily fit into the standard test suite. | |
207 | .Sp | |
208 | Remember also to include the \fBexact\fR error messages, if any. | |
209 | \&\*(L"Perl complained something\*(R" is not an exact error message. | |
210 | .Sp | |
211 | If you get a core dump (or equivalent), you may use a debugger | |
212 | (\fBdbx\fR, \fBgdb\fR, etc) to produce a stack trace to include in the bug | |
213 | report. \s-1NOTE:\s0 unless your Perl has been compiled with debug info | |
214 | (often \fB\-g\fR), the stack trace is likely to be somewhat hard to use | |
215 | because it will most probably contain only the function names and not | |
216 | their arguments. If possible, recompile your Perl with debug info and | |
217 | reproduce the dump and the stack trace. | |
218 | .IP "Can you describe the bug in plain English?" 4 | |
219 | .IX Item "Can you describe the bug in plain English?" | |
220 | The easier it is to understand a reproducible bug, the more likely it | |
221 | will be fixed. Anything you can provide by way of insight into the | |
222 | problem helps a great deal. In other words, try to analyze the | |
223 | problem (to the extent you can) and report your discoveries. | |
224 | .IP "Can you fix the bug yourself?" 4 | |
225 | .IX Item "Can you fix the bug yourself?" | |
226 | A bug report which \fIincludes a patch to fix it\fR will almost | |
227 | definitely be fixed. Use the \f(CW\*(C`diff\*(C'\fR program to generate your patches | |
228 | (\f(CW\*(C`diff\*(C'\fR is being maintained by the \s-1GNU\s0 folks as part of the \fBdiffutils\fR | |
229 | package, so you should be able to get it from any of the \s-1GNU\s0 software | |
230 | repositories). If you do submit a patch, the cool-dude counter at | |
231 | perlbug@perl.org will register you as a savior of the world. Your | |
232 | patch may be returned with requests for changes, or requests for more | |
233 | detailed explanations about your fix. | |
234 | .Sp | |
235 | Here are some clues for creating quality patches: Use the \fB\-c\fR or | |
236 | \&\fB\-u\fR switches to the diff program (to create a so-called context or | |
237 | unified diff). Make sure the patch is not reversed (the first | |
238 | argument to diff is typically the original file, the second argument | |
239 | your changed file). Make sure you test your patch by applying it with | |
240 | the \f(CW\*(C`patch\*(C'\fR program before you send it on its way. Try to follow the | |
241 | same style as the code you are trying to patch. Make sure your patch | |
242 | really does work (\f(CW\*(C`make test\*(C'\fR, if the thing you're patching supports | |
243 | it). | |
244 | .ie n .IP "Can you use ""perlbug"" to submit the report?" 4 | |
245 | .el .IP "Can you use \f(CWperlbug\fR to submit the report?" 4 | |
246 | .IX Item "Can you use perlbug to submit the report?" | |
247 | \&\fBperlbug\fR will, amongst other things, ensure your report includes | |
248 | crucial information about your version of perl. If \f(CW\*(C`perlbug\*(C'\fR is unable | |
249 | to mail your report after you have typed it in, you may have to compose | |
250 | the message yourself, add the output produced by \f(CW\*(C`perlbug \-d\*(C'\fR and email | |
251 | it to \fBperlbug@perl.org\fR. If, for some reason, you cannot run | |
252 | \&\f(CW\*(C`perlbug\*(C'\fR at all on your system, be sure to include the entire output | |
253 | produced by running \f(CW\*(C`perl \-V\*(C'\fR (note the uppercase V). | |
254 | .Sp | |
255 | Whether you use \f(CW\*(C`perlbug\*(C'\fR or send the email manually, please make | |
256 | your Subject line informative. \*(L"a bug\*(R" not informative. Neither is | |
257 | \&\*(L"perl crashes\*(R" nor \*(L"\s-1HELP\s0!!!\*(R". These don't help. | |
258 | A compact description of what's wrong is fine. | |
259 | .PP | |
260 | Having done your bit, please be prepared to wait, to be told the bug | |
261 | is in your code, or even to get no reply at all. The Perl maintainers | |
262 | are busy folks, so if your problem is a small one or if it is difficult | |
263 | to understand or already known, they may not respond with a personal reply. | |
264 | If it is important to you that your bug be fixed, do monitor the | |
265 | \&\f(CW\*(C`Changes\*(C'\fR file in any development releases since the time you submitted | |
266 | the bug, and encourage the maintainers with kind words (but never any | |
267 | flames!). Feel free to resend your bug report if the next released | |
268 | version of perl comes out and your bug is still present. | |
269 | .SH "OPTIONS" | |
270 | .IX Header "OPTIONS" | |
271 | .IP "\fB\-a\fR" 8 | |
272 | .IX Item "-a" | |
273 | Address to send the report to. Defaults to \fBperlbug@perl.org\fR. | |
274 | .IP "\fB\-A\fR" 8 | |
275 | .IX Item "-A" | |
276 | Don't send a bug received acknowledgement to the reply address. | |
277 | Generally it is only a sensible to use this option if you are a | |
278 | perl maintainer actively watching perl porters for your message to | |
279 | arrive. | |
280 | .IP "\fB\-b\fR" 8 | |
281 | .IX Item "-b" | |
282 | Body of the report. If not included on the command line, or | |
283 | in a file with \fB\-f\fR, you will get a chance to edit the message. | |
284 | .IP "\fB\-C\fR" 8 | |
285 | .IX Item "-C" | |
286 | Don't send copy to administrator. | |
287 | .IP "\fB\-c\fR" 8 | |
288 | .IX Item "-c" | |
289 | Address to send copy of report to. Defaults to the address of the | |
290 | local perl administrator (recorded when perl was built). | |
291 | .IP "\fB\-d\fR" 8 | |
292 | .IX Item "-d" | |
293 | Data mode (the default if you redirect or pipe output). This prints out | |
294 | your configuration data, without mailing anything. You can use this | |
295 | with \fB\-v\fR to get more complete data. | |
296 | .IP "\fB\-e\fR" 8 | |
297 | .IX Item "-e" | |
298 | Editor to use. | |
299 | .IP "\fB\-f\fR" 8 | |
300 | .IX Item "-f" | |
301 | File containing the body of the report. Use this to quickly send a | |
302 | prepared message. | |
303 | .IP "\fB\-F\fR" 8 | |
304 | .IX Item "-F" | |
305 | File to output the results to instead of sending as an email. Useful | |
306 | particularly when running perlbug on a machine with no direct internet | |
307 | connection. | |
308 | .IP "\fB\-h\fR" 8 | |
309 | .IX Item "-h" | |
310 | Prints a brief summary of the options. | |
311 | .IP "\fB\-ok\fR" 8 | |
312 | .IX Item "-ok" | |
313 | Report successful build on this system to perl porters. Forces \fB\-S\fR | |
314 | and \fB\-C\fR. Forces and supplies values for \fB\-s\fR and \fB\-b\fR. Only | |
315 | prompts for a return address if it cannot guess it (for use with | |
316 | \&\fBmake\fR). Honors return address specified with \fB\-r\fR. You can use this | |
317 | with \fB\-v\fR to get more complete data. Only makes a report if this | |
318 | system is less than 60 days old. | |
319 | .IP "\fB\-okay\fR" 8 | |
320 | .IX Item "-okay" | |
321 | As \fB\-ok\fR except it will report on older systems. | |
322 | .IP "\fB\-nok\fR" 8 | |
323 | .IX Item "-nok" | |
324 | Report unsuccessful build on this system. Forces \fB\-C\fR. Forces and | |
325 | supplies a value for \fB\-s\fR, then requires you to edit the report | |
326 | and say what went wrong. Alternatively, a prepared report may be | |
327 | supplied using \fB\-f\fR. Only prompts for a return address if it | |
328 | cannot guess it (for use with \fBmake\fR). Honors return address | |
329 | specified with \fB\-r\fR. You can use this with \fB\-v\fR to get more | |
330 | complete data. Only makes a report if this system is less than 60 | |
331 | days old. | |
332 | .IP "\fB\-nokay\fR" 8 | |
333 | .IX Item "-nokay" | |
334 | As \fB\-nok\fR except it will report on older systems. | |
335 | .IP "\fB\-r\fR" 8 | |
336 | .IX Item "-r" | |
337 | Your return address. The program will ask you to confirm its default | |
338 | if you don't use this option. | |
339 | .IP "\fB\-S\fR" 8 | |
340 | .IX Item "-S" | |
341 | Send without asking for confirmation. | |
342 | .IP "\fB\-s\fR" 8 | |
343 | .IX Item "-s" | |
344 | Subject to include with the message. You will be prompted if you don't | |
345 | supply one on the command line. | |
346 | .IP "\fB\-t\fR" 8 | |
347 | .IX Item "-t" | |
348 | Test mode. The target address defaults to \fBperlbug\-test@perl.org\fR. | |
349 | .IP "\fB\-v\fR" 8 | |
350 | .IX Item "-v" | |
351 | Include verbose configuration data in the report. | |
352 | .SH "AUTHORS" | |
353 | .IX Header "AUTHORS" | |
354 | Kenneth Albanowski (<kjahds@kjahds.com>), subsequently \fIdoc\fRtored | |
355 | by Gurusamy Sarathy (<gsar@activestate.com>), Tom Christiansen | |
356 | (<tchrist@perl.com>), Nathan Torkington (<gnat@frii.com>), | |
357 | Charles F. Randall (<cfr@pobox.com>), Mike Guy | |
358 | (<mjtg@cam.a.uk>), Dominic Dunlop (<domo@computer.org>), | |
359 | Hugo van der Sanden (<hv@crypt.org<gt>), | |
360 | Jarkko Hietaniemi (<jhi@iki.fi>), Chris Nandor | |
361 | (<pudge@pobox.com>), Jon Orwant (<orwant@media.mit.edu>, | |
362 | and Richard Foley (<richard@rfi.net>). | |
363 | .SH "SEE ALSO" | |
364 | .IX Header "SEE ALSO" | |
365 | \&\fIperl\fR\|(1), \fIperldebug\fR\|(1), \fIperldiag\fR\|(1), \fIperlport\fR\|(1), \fIperltrap\fR\|(1), | |
366 | \&\fIdiff\fR\|(1), \fIpatch\fR\|(1), \fIdbx\fR\|(1), \fIgdb\fR\|(1) | |
367 | .SH "BUGS" | |
368 | .IX Header "BUGS" | |
369 | None known (guess what must have been used to report them?) |