This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldelta for 901ee108fe
[perl5.git] / utils / perlbug.PL
CommitLineData
37fa004c
PP
1#!/usr/local/bin/perl
2
3use Config;
4use File::Basename qw(&basename &dirname);
8a5546a1 5use Cwd;
1948c06a 6use File::Spec::Functions;
37fa004c
PP
7
8# List explicitly here the variables you want Configure to
9# generate. Metaconfig only looks for shell variables, so you
10# have to mention them as if they were shell variables, not
11# %Config entries. Thus you write
12# $startperl
13# to ensure Configure will look for $Config{startperl}.
84902520 14# $perlpath
37fa004c
PP
15
16# This forces PL files to create target in same directory as PL file.
17# This is so that make depend always knows where to find PL derivatives.
8a5546a1 18$origdir = cwd;
44a8e56a
PP
19chdir dirname($0);
20$file = basename($0, '.PL');
774d564b 21$file .= '.com' if $^O eq 'VMS';
37fa004c 22
55d729e4 23open OUT, ">$file" or die "Can't create $file: $!";
37fa004c 24
3541c11a
NT
25# get patchlevel.h timestamp
26
27-e catfile(updir, "patchlevel.h")
28 or die "Can't find patchlevel.h: $!";
84902520 29
3541c11a 30my $patchlevel_date = (stat _)[9];
84902520 31
e8a97f29 32# TO DO (perhaps): store/embed $Config::config_sh into perlbug. When perlbug is
5edeba26
TB
33# used, compare $Config::config_sh with the stored version. If they differ then
34# append a list of individual differences to the bug report.
35
84902520 36
37fa004c
PP
37print "Extracting $file (with variable substitutions)\n";
38
39# In this section, perl variables will be expanded during extraction.
40# You can use $Config{...} to use Configure variables.
41
fa510083 42my $extract_version = sprintf("%vd", $^V);
1ec03f31 43
37fa004c 44print OUT <<"!GROK!THIS!";
5f05dabc
PP
45$Config{startperl}
46 eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}'
47 if \$running_under_some_shell;
84902520 48
1ec03f31 49my \$config_tag1 = '$extract_version - $Config{cf_time}';
fb73857a 50
84902520 51my \$patchlevel_date = $patchlevel_date;
37fa004c
PP
52!GROK!THIS!
53
54# In the following, perl variables are not expanded during extraction.
55
56print OUT <<'!NO!SUBS!';
3541c11a
NT
57my @patches = Config::local_patches();
58my $patch_tags = join "", map /(\S+)/ ? "+$1 " : (), @patches;
37fa004c 59
54c90be1 60use warnings;
721e2275 61use strict;
37fa004c 62use Config;
1ec03f31 63use File::Spec; # keep perlbug Perl 5.005 compatible
37fa004c 64use Getopt::Std;
721e2275 65use File::Basename 'basename';
37fa004c
PP
66
67sub paraprint;
68
55d729e4 69BEGIN {
54c90be1 70 eval { require Mail::Send;};
55d729e4 71 $::HaveSend = ($@ eq "");
54c90be1 72 eval { require Mail::Util; } ;
55d729e4 73 $::HaveUtil = ($@ eq "");
003a92ef 74 # use secure tempfiles wherever possible
54c90be1 75 eval { require File::Temp; };
003a92ef 76 $::HaveTemp = ($@ eq "");
13f4c5e4
AC
77 eval { require Module::CoreList; };
78 $::HaveCoreList = ($@ eq "");
55d729e4 79};
c07a80fd 80
54c90be1 81my $Version = "1.39";
c07a80fd 82
54c90be1
J
83#TODO:
84# make sure failure (transmission-wise) of Mail::Send is accounted for.
85# (This may work now. Unsure of the original author's issue -JESSE 2008-06-08)
1b0e3b9e 86# - Test -b option
37fa004c 87
721e2275
NC
88my( $file, $usefile, $cc, $address, $bugaddress, $testaddress, $thanksaddress,
89 $filename, $messageid, $domain, $subject, $from, $verbose, $ed, $outfile,
54c90be1 90 $fh, $me, $body, $andcc, %REP, $ok, $thanks, $progname,
8ced8222 91 $Is_MSWin32, $Is_Linux, $Is_VMS, $Is_OpenBSD,
54c90be1 92 $report_about_module, $category, $severity,
4c62848c 93 %opt,
54c90be1 94);
37fa004c 95
fa510083 96my $perl_version = $^V ? sprintf("%vd", $^V) : $];
1ec03f31
GS
97
98my $config_tag2 = "$perl_version - $Config{cf_time}";
fb73857a 99
37fa004c
PP
100Init();
101
4c62848c
JC
102if ($opt{h}) { Help(); exit; }
103if ($opt{d}) { Dump(*STDOUT); exit; }
104if (!-t STDIN && !($ok and not $opt{n})) {
721e2275
NC
105 paraprint <<"EOF";
106Please use $progname interactively. If you want to
84478119
PP
107include a file, you can use the -f switch.
108EOF
55d729e4 109 die "\n";
84478119 110}
c07a80fd 111
37fa004c 112Query();
4c62848c 113Edit() unless $usefile || ($ok and not $opt{n});
37fa004c 114NowWhat();
54c90be1
J
115if ($outfile) {
116 save_message_to_disk($outfile);
117} else {
118 Send();
4dbf56a0
NC
119 if ($thanks) {
120 print "\nThank you for taking the time to send a thank-you message!\n\n";
c983ad79
RS
121
122 paraprint <<EOF
123Please note that mailing lists are moderated, your message may take a while to
124show up.
125EOF
4dbf56a0
NC
126 } else {
127 print "\nThank you for taking the time to file a bug report!\n\n";
a9d7774b 128
c983ad79 129 paraprint <<EOF
a9d7774b
MM
130Please note that mailing lists are moderated, your message may take a while to
131show up. If you do not receive an automated response acknowledging your message
132within a few hours (check your SPAM folder and outgoing mail) please consider
23dfa308 133sending an email directly from your mail client to perlbug\@perl.org.
a9d7774b 134EOF
c983ad79
RS
135 }
136
54c90be1 137}
37fa004c
PP
138
139exit;
140
975b416b 141sub ask_for_alternatives { # (category|severity)
50d3c28b 142 my $name = shift;
975b416b
GS
143 my %alts = (
144 'category' => {
145 'default' => 'core',
146 'ok' => 'install',
721e2275
NC
147 # Inevitably some of these will end up in RT whatever we do:
148 'thanks' => 'thanks',
975b416b
GS
149 'opts' => [qw(core docs install library utilities)], # patch, notabug
150 },
151 'severity' => {
152 'default' => 'low',
153 'ok' => 'none',
dda32041 154 'thanks' => 'none',
975b416b 155 'opts' => [qw(critical high medium low wishlist none)], # zero
7f2de2d2 156 },
975b416b 157 );
54c90be1 158 die "Invalid alternative ($name) requested\n" unless grep(/^$name$/, keys %alts);
50d3c28b 159 my $alt = "";
721e2275
NC
160 my $what = $ok || $thanks;
161 if ($what) {
162 $alt = $alts{$name}{$what};
975b416b
GS
163 } else {
164 my @alts = @{$alts{$name}{'opts'}};
54c90be1 165 print "\n\n";
975b416b 166 paraprint <<EOF;
54c90be1 167Please pick a $name from the following list:
50d3c28b
GS
168
169 @alts
50d3c28b 170EOF
975b416b
GS
171 my $err = 0;
172 do {
173 if ($err++ > 5) {
174 die "Invalid $name: aborting.\n";
175 }
54c90be1
J
176 $alt = _prompt('', "\u$name", $alts{$name}{'default'});
177 $alt ||= $alts{$name}{'default'};
975b416b
GS
178 } while !((($alt) = grep(/^$alt/i, @alts)));
179 }
50d3c28b
GS
180 lc $alt;
181}
182
37fa004c 183sub Init {
55d729e4
GS
184 # -------- Setup --------
185
186 $Is_MSWin32 = $^O eq 'MSWin32';
187 $Is_VMS = $^O eq 'VMS';
afc5e478 188 $Is_Linux = lc($^O) eq 'linux';
8843dda6 189 $Is_OpenBSD = lc($^O) eq 'openbsd';
55d729e4 190
4c62848c 191 if (!getopts("Adhva:s:b:f:F:r:e:SCc:to:n:T", \%opt)) { Help(); exit; };
55d729e4
GS
192
193 # This comment is needed to notify metaconfig that we are
194 # using the $perladmin, $cf_by, and $cf_time definitions.
195
196 # -------- Configuration ---------
197
198 # perlbug address
721e2275 199 $bugaddress = 'perlbug@perl.org';
55d729e4
GS
200
201 # Test address
3e79b69b 202 $testaddress = 'perlbug-test@perl.org';
55d729e4 203
721e2275
NC
204 # Thanks address
205 $thanksaddress = 'perl-thanks@perl.org';
206
207 if (basename ($0) =~ /^perlthanks/i) {
208 # invoked as perlthanks
4c62848c
JC
209 $opt{T} = 1;
210 $opt{C} = 1; # don't send a copy to the local admin
721e2275
NC
211 }
212
4c62848c 213 if ($opt{T}) {
721e2275
NC
214 $thanks = 'thanks';
215 }
216
217 $progname = $thanks ? 'perlthanks' : 'perlbug';
55d729e4 218 # Target address
4c62848c 219 $address = $opt{a} || ($opt{t} ? $testaddress
721e2275 220 : $thanks ? $thanksaddress : $bugaddress);
55d729e4 221
e4ef3332 222 # Users address, used in message and in From and Reply-To headers
4c62848c 223 $from = $opt{r} || "";
55d729e4
GS
224
225 # Include verbose configuration information
4c62848c 226 $verbose = $opt{v} || 0;
55d729e4
GS
227
228 # Subject of bug-report message
4c62848c 229 $subject = $opt{s} || "";
55d729e4
GS
230
231 # Send a file
4c62848c 232 $usefile = ($opt{f} || 0);
55d729e4
GS
233
234 # File to send as report
4c62848c 235 $file = $opt{f} || "";
55d729e4 236
105f9295 237 # File to output to
4c62848c 238 $outfile = $opt{F} || "";
105f9295 239
55d729e4 240 # Body of report
4c62848c 241 $body = $opt{b} || "";
de94c9df 242
55d729e4 243 # Editor
4c62848c 244 $ed = $opt{e} || $ENV{VISUAL} || $ENV{EDITOR} || $ENV{EDIT}
55d729e4
GS
245 || ($Is_VMS && "edit/tpu")
246 || ($Is_MSWin32 && "notepad")
247 || "vi";
248
249 # Not OK - provide build failure template by finessing OK report
4c62848c
JC
250 if ($opt{n}) {
251 if (substr($opt{n}, 0, 2) eq 'ok' ) {
252 $opt{o} = substr($opt{n}, 1);
55d729e4
GS
253 } else {
254 Help();
255 exit();
256 }
257 }
258
259 # OK - send "OK" report for build on this system
721e2275 260 $ok = '';
4c62848c
JC
261 if ($opt{o}) {
262 if ($opt{o} eq 'k' or $opt{o} eq 'kay') {
55d729e4 263 my $age = time - $patchlevel_date;
4c62848c 264 if ($opt{o} eq 'k' and $age > 60 * 24 * 60 * 60 ) {
55d729e4
GS
265 my $date = localtime $patchlevel_date;
266 print <<"EOF";
267"perlbug -ok" and "perlbug -nok" do not report on Perl versions which
268are more than 60 days old. This Perl version was constructed on
269$date. If you really want to report this, use
270"perlbug -okay" or "perlbug -nokay".
84902520 271EOF
1b0e3b9e
CR
272 exit();
273 }
55d729e4 274 # force these options
4c62848c
JC
275 unless ($opt{n}) {
276 $opt{S} = 1; # don't prompt for send
277 $opt{b} = 1; # we have a body
55d729e4
GS
278 $body = "Perl reported to build OK on this system.\n";
279 }
4c62848c
JC
280 $opt{C} = 1; # don't send a copy to the local admin
281 $opt{s} = 1; # we have a subject line
282 $subject = ($opt{n} ? 'Not ' : '')
1ec03f31 283 . "OK: perl $perl_version ${patch_tags}on"
55d729e4 284 ." $::Config{'archname'} $::Config{'osvers'} $subject";
721e2275 285 $ok = 'ok';
55d729e4
GS
286 } else {
287 Help();
288 exit();
1b0e3b9e 289 }
55d729e4 290 }
37fa004c 291
55d729e4
GS
292 # Possible administrator addresses, in order of confidence
293 # (Note that cf_email is not mentioned to metaconfig, since
294 # we don't really want it. We'll just take it if we have to.)
295 #
296 # This has to be after the $ok stuff above because of the way
4c62848c
JC
297 # that $opt{C} is forced.
298 $cc = $opt{C} ? "" : (
299 $opt{c} || $::Config{'perladmin'}
55d729e4
GS
300 || $::Config{'cf_email'} || $::Config{'cf_by'}
301 );
302
de94c9df
RF
303 if ($::HaveUtil) {
304 $domain = Mail::Util::maildomain();
305 } elsif ($Is_MSWin32) {
306 $domain = $ENV{'USERDOMAIN'};
307 } else {
308 require Sys::Hostname;
309 $domain = Sys::Hostname::hostname();
310 }
311
312 # Message-Id - rjsf
313 $messageid = "<$::Config{'version'}_${$}_".time."\@$domain>";
314
55d729e4
GS
315 # My username
316 $me = $Is_MSWin32 ? $ENV{'USERNAME'}
317 : $^O eq 'os2' ? $ENV{'USER'} || $ENV{'LOGNAME'}
318 : eval { getpwuid($<) }; # May be missing
c0830f08
RB
319
320 $from = $::Config{'cf_email'}
321 if !$from && $::Config{'cf_email'} && $::Config{'cf_by'} && $me &&
322 ($me eq $::Config{'cf_by'});
55d729e4 323} # sub Init
37fa004c
PP
324
325sub Query {
55d729e4
GS
326 # Explain what perlbug is
327 unless ($ok) {
721e2275
NC
328 if ($thanks) {
329 paraprint <<'EOF';
330This program provides an easy way to send a thank-you message back to the
331authors and maintainers of perl.
332
333If you wish to submit a bug report, please run it without the -T flag
334(or run the program perlbug rather than perlthanks)
335EOF
336 } else {
337 paraprint <<"EOF";
54c90be1
J
338This program provides an easy way to create a message reporting a
339bug in the core perl distribution (along with tests or patches)
340to the volunteers who maintain perl at $address. To send a thank-you
341note to $thanksaddress instead of a bug report, please run 'perlthanks'.
342
343Please do not use $0 to send test messages, test whether perl
344works, or to report bugs in perl modules from CPAN.
345
a152f763
AC
346Suggestions for how to find help using Perl can be found at
347http://perldoc.perl.org/perlcommunity.html
37fa004c 348EOF
721e2275 349 }
1b0e3b9e 350 }
37fa004c 351
55d729e4 352 # Prompt for subject of message, if needed
2e7f46bf 353
54c90be1 354 if ($subject && TrivialSubject($subject)) {
2e7f46bf
JH
355 $subject = '';
356 }
357
55d729e4 358 unless ($subject) {
54c90be1
J
359 print
360"First of all, please provide a subject for the message.\n";
361 if ( not $thanks) {
721e2275 362 paraprint <<EOF;
54c90be1
J
363This should be a concise description of your bug or problem
364which will help the volunteers working to improve perl to categorize
365and resolve the issue. Be as specific and descriptive as
366you can. A subject like "perl bug" or "perl problem" will make it
367much less likely that your issue gets the attention it deserves.
37fa004c 368EOF
721e2275 369 }
55d729e4
GS
370
371 my $err = 0;
2e7f46bf 372 do {
54c90be1 373 $subject = _prompt('','Subject');
2e7f46bf 374 if ($err++ == 5) {
721e2275
NC
375 if ($thanks) {
376 $subject = 'Thanks for Perl';
377 } else {
378 die "Aborting.\n";
379 }
55d729e4 380 }
2e7f46bf 381 } while (TrivialSubject($subject));
55d729e4
GS
382 }
383
384 # Prompt for return address, if needed
4c62848c 385 unless ($opt{r}) {
55d729e4
GS
386 # Try and guess return address
387 my $guess;
388
e6eb9020
DM
389 $guess = $ENV{'REPLY-TO'} || $ENV{'REPLYTO'} || $ENV{'EMAIL'}
390 || $from || '';
1948c06a 391
55d729e4 392 unless ($guess) {
de94c9df
RF
393 # move $domain to where we can use it elsewhere
394 if ($domain) {
55d729e4
GS
395 if ($Is_VMS && !$::Config{'d_socket'}) {
396 $guess = "$domain\:\:$me";
41f926b8 397 } else {
55d729e4 398 $guess = "$me\@$domain" if $domain;
c07a80fd 399 }
55d729e4
GS
400 }
401 }
37fa004c 402
55d729e4
GS
403 if ($guess) {
404 unless ($ok) {
405 paraprint <<EOF;
54c90be1
J
406Perl's developers may need your email address to contact you for
407further information about your issue or to inform you when it is
408resolved. If the default shown is not your email address, please
409correct it.
37fa004c 410EOF
55d729e4
GS
411 }
412 } else {
413 paraprint <<EOF;
54c90be1
J
414Please enter your full internet email address so that Perl's
415developers can contact you with questions about your issue or to
416inform you that it has been resolved.
37fa004c 417EOF
37fa004c 418 }
37fa004c 419
55d729e4
GS
420 if ($ok && $guess) {
421 # use it
422 $from = $guess;
423 } else {
424 # verify it
54c90be1 425 $from = _prompt('','Your address',$guess);
55d729e4
GS
426 $from = $guess if $from eq '';
427 }
428 }
37fa004c 429
55d729e4
GS
430 if ($from eq $cc or $me eq $cc) {
431 # Try not to copy ourselves
432 $cc = "yourself";
433 }
37fa004c 434
55d729e4 435 # Prompt for administrator address, unless an override was given
4c62848c 436 if( !$opt{C} and !$opt{c} ) {
54c90be1
J
437 my $description = <<EOF;
438$0 can send a copy of this report to your local perl
439administrator. If the address below is wrong, please correct it,
440or enter 'none' or 'yourself' to not send a copy.
37fa004c 441EOF
54c90be1 442 my $entry = _prompt($description, "Local perl administrator", $cc);
37fa004c 443
55d729e4
GS
444 if ($entry ne "") {
445 $cc = $entry;
446 $cc = '' if $me eq $cc;
37fa004c 447 }
55d729e4 448 }
37fa004c 449
55d729e4 450 $cc = '' if $cc =~ /^(none|yourself|me|myself|ourselves)$/i;
54c90be1
J
451 if ($cc) {
452 $andcc = " and $cc"
453 } else {
454 $andcc = ''
455 }
37fa004c 456
55d729e4 457 # Prompt for editor, if no override is given
ab3ef367 458editor:
4c62848c 459 unless ($opt{e} || $opt{f} || $opt{b}) {
26ab4e07 460
54c90be1 461 my $description;
26ab4e07 462
54c90be1
J
463 chomp (my $common_end = <<"EOF");
464You will probably want to use a text editor to enter the body of
465your report. If "$ed" is the editor you want to use, then just press
466Enter, otherwise type in the name of the editor you would like to
467use.
468
469If you have already composed the body of your report, you may enter
470"file", and $0 will prompt you to enter the name of the file
471containing your report.
721e2275
NC
472EOF
473
474 if ($thanks) {
54c90be1
J
475 $description = <<"EOF";
476It's now time to compose your thank-you message.
721e2275 477
54c90be1
J
478Some information about your local perl configuration will automatically
479be included at the end of your message, because we're curious about
480the different ways that people build and use perl. If you'd rather
481not share this information, you're welcome to delete it.
721e2275
NC
482
483$common_end
484EOF
485 } else {
54c90be1
J
486 $description = <<"EOF";
487It's now time to compose your bug report. Try to make the report
488concise but descriptive. Please include any detail which you think
489might be relevant or might help the volunteers working to improve
490perl. If you are reporting something that does not work as you think
491it should, please try to include examples of the actual result and of
492what you expected.
493
494Some information about your local perl configuration will automatically
495be included at the end of your report. If you are using an unusual
496version of perl, it would be useful if you could confirm that you
497can replicate the problem on a standard build of perl as well.
37fa004c 498
721e2275 499$common_end
37fa004c 500EOF
721e2275
NC
501 }
502
54c90be1 503 my $entry = _prompt($description, "Editor", $ed);
55d729e4
GS
504 $usefile = 0;
505 if ($entry eq "file") {
506 $usefile = 1;
507 } elsif ($entry ne "") {
508 $ed = $entry;
37fa004c 509 }
55d729e4 510 }
721e2275 511 if ($::HaveCoreList && !$ok && !$thanks) {
54c90be1
J
512 my $description = <<EOF;
513If your bug is about a Perl module rather than a core language
514feature, please enter its name here. If it's not, just hit Enter
515to skip this question.
13f4c5e4 516EOF
54c90be1
J
517
518 my $entry = '';
519 while ($entry eq '') {
520 $entry = _prompt($description, 'Module');
13f4c5e4 521 my $first_release = Module::CoreList->first_release($entry);
54c90be1 522 if ($entry and not $first_release) {
13f4c5e4 523 paraprint <<EOF;
54c90be1
J
524$entry is not a "core" Perl module. Please check that you entered
525its name correctly. If it is correct, quit this program, try searching
526for $entry on http://rt.cpan.org, and report your issue there.
13f4c5e4 527EOF
54c90be1
J
528
529 $entry = '';
0accdd48
NC
530 } elsif (my $bug_tracker = $Module::CoreList::bug_tracker{$entry}) {
531 paraprint <<"EOF";
532$entry included with core Perl is copied directly from the CPAN distribution.
533Please report bugs in $entry directly to its maintainers using $bug_tracker
534EOF
535 $entry = '';
54c90be1
J
536 } elsif ($entry) {
537 $category ||= 'library';
538 $report_about_module = $entry;
539 last;
540 } else {
541 last;
542 }
13f4c5e4
AC
543 }
544 }
37fa004c 545
50d3c28b 546 # Prompt for category of bug
975b416b 547 $category ||= ask_for_alternatives('category');
50d3c28b
GS
548
549 # Prompt for severity of bug
975b416b 550 $severity ||= ask_for_alternatives('severity');
50d3c28b 551
55d729e4
GS
552 # Generate scratch file to edit report in
553 $filename = filename();
37fa004c 554
55d729e4
GS
555 # Prompt for file to read report from, if needed
556 if ($usefile and !$file) {
ab3ef367 557filename:
54c90be1 558 my $description = <<EOF;
37fa004c 559What is the name of the file that contains your report?
37fa004c 560EOF
54c90be1 561 my $entry = _prompt($description, "Filename");
37fa004c 562
55d729e4
GS
563 if ($entry eq "") {
564 paraprint <<EOF;
54c90be1
J
565It seems you didn't enter a filename. Please choose to use a text
566editor or enter a filename.
ab3ef367 567EOF
55d729e4
GS
568 goto editor;
569 }
570
571 unless (-f $entry and -r $entry) {
572 paraprint <<EOF;
54c90be1
J
573'$entry' doesn't seem to be a readable file. You may have mistyped
574its name or may not have permission to read it.
575
576If you don't want to use a file as the content of your report, just
577hit Enter and you'll be able to select a text editor instead.
ab3ef367 578EOF
55d729e4 579 goto filename;
37fa004c 580 }
55d729e4
GS
581 $file = $entry;
582 }
37fa004c 583
55d729e4 584 # Generate report
c9967ac8 585 open(REP,">$filename") or die "Unable to create report file '$filename': $!\n";
721e2275 586 my $reptype = !$ok ? ($thanks ? 'thank-you' : 'bug')
4c62848c 587 : $opt{n} ? "build failure" : "success";
37fa004c 588
55d729e4 589 print REP <<EOF;
84902520 590This is a $reptype report for perl from $from,
1ec03f31 591generated with the help of perlbug $Version running under perl $perl_version.
37fa004c
PP
592
593EOF
594
55d729e4
GS
595 if ($body) {
596 print REP $body;
597 } elsif ($usefile) {
598 open(F, "<$file")
c9967ac8 599 or die "Unable to read report file from '$file': $!\n";
55d729e4
GS
600 while (<F>) {
601 print REP $_
602 }
c9967ac8 603 close(F) or die "Error closing '$file': $!";
55d729e4 604 } else {
721e2275
NC
605 if ($thanks) {
606 print REP <<'EOF';
607
608-----------------------------------------------------------------
54c90be1 609[Please enter your thank-you message here]
721e2275
NC
610
611
612
54c90be1 613[You're welcome to delete anything below this line]
721e2275
NC
614-----------------------------------------------------------------
615EOF
616 } else {
617 print REP <<'EOF';
774d564b
PP
618
619-----------------------------------------------------------------
54c90be1 620[Please describe your issue here]
774d564b
PP
621
622
623
624[Please do not change anything below this line]
625-----------------------------------------------------------------
626EOF
721e2275 627 }
55d729e4
GS
628 }
629 Dump(*REP);
c0a6bf09 630 close(REP) or die "Error closing report file: $!";
55d729e4 631
54c90be1
J
632 # Set up an initial report fingerprint so we can compare it later
633 _fingerprint_lines_in_report();
634
55d729e4 635} # sub Query
c07a80fd
PP
636
637sub Dump {
55d729e4 638 local(*OUT) = @_;
37fa004c 639
4ea8010a
DM
640 # these won't have been set if run with -d
641 $category ||= 'core';
642 $severity ||= 'low';
643
50d3c28b
GS
644 print OUT <<EFF;
645---
646Flags:
647 category=$category
648 severity=$severity
890b8eb0 649EFF
54c90be1
J
650
651 if ($report_about_module ) {
652 print OUT <<EFF;
653 module=$report_about_module
654EFF
655 }
4c62848c 656 if ($opt{A}) {
890b8eb0
NC
657 print OUT <<EFF;
658 ack=no
659EFF
660 }
661 print OUT <<EFF;
50d3c28b
GS
662---
663EFF
664 print OUT "This perlbug was built using Perl $config_tag1\n",
1ec03f31 665 "It is being executed now by Perl $config_tag2.\n\n"
55d729e4 666 if $config_tag2 ne $config_tag1;
fb73857a 667
55d729e4 668 print OUT <<EOF;
1ec03f31 669Site configuration information for perl $perl_version:
37fa004c
PP
670
671EOF
55d729e4
GS
672 if ($::Config{cf_by} and $::Config{cf_time}) {
673 print OUT "Configured by $::Config{cf_by} at $::Config{cf_time}.\n\n";
674 }
675 print OUT Config::myconfig;
37fa004c 676
55d729e4
GS
677 if (@patches) {
678 print OUT join "\n ", "Locally applied patches:", @patches;
679 print OUT "\n";
680 };
84902520 681
55d729e4 682 print OUT <<EOF;
8ecf1a0c 683
774d564b 684---
1ec03f31 685\@INC for perl $perl_version:
774d564b 686EOF
55d729e4
GS
687 for my $i (@INC) {
688 print OUT " $i\n";
689 }
774d564b 690
55d729e4 691 print OUT <<EOF;
8ecf1a0c 692
774d564b 693---
1ec03f31 694Environment for perl $perl_version:
8ecf1a0c 695EOF
5cf1d1f1
JH
696 my @env =
697 qw(PATH LD_LIBRARY_PATH LANG PERL_BADLANG SHELL HOME LOGDIR LANGUAGE);
698 push @env, $Config{ldlibpthname} if $Config{ldlibpthname} ne '';
27414c22 699 push @env, grep /^(?:PERL|LC_|LANG|CYGWIN)/, keys %ENV;
8876aa85
JH
700 my %env;
701 @env{@env} = @env;
702 for my $env (sort keys %env) {
55d729e4
GS
703 print OUT " $env",
704 exists $ENV{$env} ? "=$ENV{$env}" : ' (unset)',
705 "\n";
706 }
707 if ($verbose) {
1ec03f31 708 print OUT "\nComplete configuration data for perl $perl_version:\n\n";
55d729e4
GS
709 my $value;
710 foreach (sort keys %::Config) {
711 $value = $::Config{$_};
4ea8010a 712 $value = '' unless defined $value;
55d729e4
GS
713 $value =~ s/'/\\'/g;
714 print OUT "$_='$value'\n";
84902520 715 }
55d729e4
GS
716 }
717} # sub Dump
37fa004c
PP
718
719sub Edit {
55d729e4
GS
720 # Edit the report
721 if ($usefile || $body) {
54c90be1
J
722 my $description = "Please make sure that the name of the editor you want to use is correct.";
723 my $entry = _prompt($description, 'Editor', $ed);
55d729e4
GS
724 $ed = $entry unless $entry eq '';
725 }
a5f75d66 726
54c90be1
J
727 _edit_file($ed);
728}
729
730sub _edit_file {
731 my $editor = shift;
732
733 my $report_written = 0;
734
735 while ( !$report_written ) {
8ced8222
NC
736 my $exit_status = system("$editor $filename");
737 if ($exit_status) {
738 my $desc = <<EOF;
54c90be1
J
739The editor you chose ('$editor') could not be run!
740
741If you mistyped its name, please enter it now, otherwise just press Enter.
1948c06a 742EOF
8ced8222
NC
743 my $entry = _prompt( $desc, 'Editor', $editor );
744 if ( $entry ne "" ) {
745 $editor = $entry;
746 next;
747 } else {
748 paraprint <<EOF;
54c90be1
J
749You may want to save your report to a file, so you can edit and
750mail it later.
a5f75d66 751EOF
8ced8222 752 return;
54c90be1
J
753 }
754 }
4c62848c 755 return if ( $ok and not $opt{n} ) || $body;
a5f75d66 756
54c90be1 757 # Check that we have a report that has some, eh, report in it.
774d564b 758
54c90be1
J
759 unless ( _fingerprint_lines_in_report() ) {
760 my $description = <<EOF;
761It looks like you didn't enter a report. You may [r]etry your edit
762or [c]ancel this report.
763EOF
764 my $action = _prompt( $description, "Action (Retry/Cancel) " );
765 if ( $action =~ /^[re]/i ) { # <R>etry <E>dit
766 next;
767 } elsif ( $action =~ /^[cq]/i ) { # <C>ancel, <Q>uit
768 Cancel(); # cancel exits
769 }
770 }
771 # Ok. the user did what they needed to;
772 return;
55d729e4 773
55d729e4 774 }
54c90be1 775}
774d564b 776
774d564b
PP
777
778sub Cancel {
779 1 while unlink($filename); # remove all versions under VMS
54c90be1 780 print "\nQuitting without sending your message.\n";
774d564b 781 exit(0);
37fa004c
PP
782}
783
784sub NowWhat {
55d729e4 785 # Report is done, prompt for further action
4c62848c 786 if( !$opt{S} ) {
55d729e4 787 while(1) {
54c90be1
J
788 my $menu = <<EOF;
789
790
791You have finished composing your message. At this point, you have
792a few options. You can:
793
6821e383 794 * [Se]nd the message to $address$andcc,
54c90be1
J
795 * [D]isplay the message on the screen,
796 * [R]e-edit the message
797 * Display or change the message's [su]bject
798 * Save the message to a [f]ile to mail at another time
799 * [Q]uit without sending a message
800
37fa004c 801EOF
8b49bb9a 802 retry:
54c90be1
J
803 print $menu;
804 my $action = _prompt('', "Action (Send/Display/Edit/Subject/Save to File)");;
805 print "\n";
55d729e4 806 if ($action =~ /^(f|sa)/i) { # <F>ile/<Sa>ve
54c90be1 807 if ( SaveMessage() ) { exit }
55d729e4
GS
808 } elsif ($action =~ /^(d|l|sh)/i ) { # <D>isplay, <L>ist, <Sh>ow
809 # Display the message
c9967ac8 810 open(REP, "<$filename") or die "Couldn't open file '$filename': $!\n";
55d729e4 811 while (<REP>) { print $_ }
c9967ac8 812 close(REP) or die "Error closing report file '$filename': $!";
2e7f46bf 813 } elsif ($action =~ /^su/i) { # <Su>bject
54c90be1 814 my $reply = _prompt( "Subject: $subject", "If the above subject is fine, press Enter. Otherwise, type a replacement now\nSubject");
2e7f46bf
JH
815 if ($reply ne '') {
816 unless (TrivialSubject($reply)) {
817 $subject = $reply;
818 print "Subject: $subject\n";
819 }
820 }
55d729e4
GS
821 } elsif ($action =~ /^se/i) { # <S>end
822 # Send the message
54c90be1
J
823 my $reply = _prompt( "Are you certain you want to send this message?", 'Please type "yes" if you are','no');
824 if ($reply =~ /^yes$/) {
55d729e4
GS
825 last;
826 } else {
827 paraprint <<EOF;
54c90be1 828You didn't type "yes", so your message has not yet been sent.
ab3ef367 829EOF
55d729e4
GS
830 }
831 } elsif ($action =~ /^[er]/i) { # <E>dit, <R>e-edit
832 # edit the message
833 Edit();
834 } elsif ($action =~ /^[qc]/i) { # <C>ancel, <Q>uit
835 Cancel();
01544859 836 } elsif ($action =~ /^s/i) {
55d729e4 837 paraprint <<EOF;
54c90be1 838The command you entered was ambiguous. Please type "send", "save" or "subject".
84478119 839EOF
55d729e4 840 }
37fa004c 841 }
55d729e4
GS
842 }
843} # sub NowWhat
37fa004c 844
2e7f46bf
JH
845sub TrivialSubject {
846 my $subject = shift;
847 if ($subject =~
848 /^(y(es)?|no?|help|perl( (bug|problem))?|bug|problem)$/i ||
849 length($subject) < 4 ||
850 $subject !~ /\s/) {
54c90be1 851 print "\nThe subject you entered wasn't very descriptive. Please try again.\n\n";
2e7f46bf
JH
852 return 1;
853 } else {
854 return 0;
855 }
856}
857
54c90be1
J
858sub SaveMessage {
859 my $file_save = $outfile || "$progname.rep";
860 my $file = _prompt( '', "Name of file to save message in", $file_save );
861 save_message_to_disk($file) || return undef;
862 print "\n";
863 paraprint <<EOF;
864A copy of your message has been saved in '$file' for you to
865send to '$address' with your normal mail client.
866EOF
867}
868
37fa004c 869sub Send {
54c90be1 870
55d729e4 871 # Message has been accepted for transmission -- Send the message
afc5e478 872
54c90be1 873 # on linux certain "mail" implementations won't accept the subject
afc5e478
SB
874 # as "~s subject" and thus the Subject header will be corrupted
875 # so don't use Mail::Send to be safe
54c90be1
J
876 eval {
877 if ( $::HaveSend && !$Is_Linux && !$Is_OpenBSD ) {
878 _send_message_mailsend();
879 } elsif ($Is_VMS) {
880 _send_message_vms();
881 } else {
882 _send_message_sendmail();
883 }
884 };
37fa004c 885
54c90be1
J
886 if ( my $error = $@ ) {
887 paraprint <<EOF;
888$0 has detected an error while trying to send your message: $error.
c07a80fd 889
54c90be1 890Your message may not have been sent. You will now have a chance to save a copy to disk.
c07a80fd 891EOF
54c90be1
J
892 SaveMessage();
893 return;
55d729e4 894 }
54c90be1
J
895
896 1 while unlink($filename); # remove all versions under VMS
897} # sub Send
37fa004c
PP
898
899sub Help {
55d729e4 900 print <<EOF;
37fa004c 901
54c90be1
J
902This program is designed to help you generate and send bug reports
903(and thank-you notes) about perl5 and the modules which ship with it.
904
905In most cases, you can just run "$0" interactively from a command
906line without any special arguments and follow the prompts.
907
908Advanced usage:
55d729e4 909
105f9295 910$0 [-v] [-a address] [-s subject] [-b body | -f inpufile ] [ -F outputfile ]
d121ca8c 911 [-r returnaddress] [-e editor] [-c adminaddress | -C] [-S] [-t] [-h]
890b8eb0 912$0 [-v] [-r returnaddress] [-A] [-ok | -okay | -nok | -nokay]
55d729e4 913
37fa004c
PP
914
915Options:
916
917 -v Include Verbose configuration data in the report
55d729e4 918 -f File containing the body of the report. Use this to
37fa004c 919 quickly send a prepared message.
1948c06a 920 -F File to output the resulting mail message to, instead of mailing.
37fa004c 921 -S Send without asking for confirmation.
c9967ac8
NC
922 -a Address to send the report to. Defaults to '$address'.
923 -c Address to send copy of report to. Defaults to '$cc'.
37fa004c 924 -C Don't send copy to administrator.
55d729e4 925 -s Subject to include with the message. You will be prompted
37fa004c
PP
926 if you don't supply one on the command line.
927 -b Body of the report. If not included on the command line, or
928 in a file with -f, you will get a chance to edit the message.
929 -r Your return address. The program will ask you to confirm
930 this if you don't give it here.
55d729e4 931 -e Editor to use.
c9967ac8
NC
932 -t Test mode. The target address defaults to '$testaddress'.
933 -T Thank-you mode. The target address defaults to '$thanksaddress'.
489b74f8 934 -d Data mode. This prints out your configuration data, without mailing
c07a80fd 935 anything. You can use this with -v to get more complete data.
890b8eb0 936 -A Don't send a bug received acknowledgement to the return address.
84902520 937 -ok Report successful build on this system to perl porters
55d729e4
GS
938 (use alone or with -v). Only use -ok if *everything* was ok:
939 if there were *any* problems at all, use -nok.
fb73857a 940 -okay As -ok but allow report from old builds.
55d729e4
GS
941 -nok Report unsuccessful build on this system to perl porters
942 (use alone or with -v). You must describe what went wrong
943 in the body of the report which you will be asked to edit.
944 -nokay As -nok but allow report from old builds.
945 -h Print this help message.
946
37fa004c
PP
947EOF
948}
949
55d729e4 950sub filename {
003a92ef
NC
951 if ($::HaveTemp) {
952 # Good. Use a secure temp file
953 my ($fh, $filename) = File::Temp::tempfile(UNLINK => 1);
954 close($fh);
955 return $filename;
956 } else {
957 # Bah. Fall back to doing things less securely.
958 my $dir = File::Spec->tmpdir();
959 $filename = "bugrep0$$";
960 $filename++ while -e File::Spec->catfile($dir, $filename);
961 $filename = File::Spec->catfile($dir, $filename);
962 }
55d729e4
GS
963}
964
37fa004c
PP
965sub paraprint {
966 my @paragraphs = split /\n{2,}/, "@_";
37fa004c 967 for (@paragraphs) { # implicit local $_
55d729e4
GS
968 s/(\S)\s*\n/$1 /g;
969 write;
970 print "\n";
37fa004c 971 }
37fa004c 972}
37fa004c 973
54c90be1
J
974sub _prompt {
975 my ($explanation, $prompt, $default) = (@_);
976 if ($explanation) {
977 print "\n\n";
978 paraprint $explanation;
979 }
980 print $prompt. ($default ? " [$default]" :''). ": ";
981 my $result = scalar(<>);
982 chomp($result);
983 $result =~ s/^\s*(.*?)\s*$/$1/s;
984 if ($default && $result eq '') {
985 return $default;
986 } else {
987 return $result;
988 }
989}
990
991sub _build_header {
992 my %attr = (@_);
993
994 my $head = '';
995 for my $header (keys %attr) {
996 $head .= "$header: ".$attr{$header}."\n";
997 }
998 return $head;
999}
1000
1001sub _message_headers {
1002 my %headers = ( To => $address, Subject => $subject );
1003 $headers{'Cc'} = $cc if ($cc);
1004 $headers{'Message-Id'} = $messageid if ($messageid);
1005 $headers{'Reply-To'} = $from if ($from);
e4ef3332 1006 $headers{'From'} = $from if ($from);
54c90be1
J
1007 return \%headers;
1008}
1009
1010sub build_complete_message {
1011 my $content = _build_header(%{_message_headers()}) . "\n\n";
1012 open( REP, "<$filename" ) or die "Couldn't open file '$filename': $!\n";
1013 while (<REP>) { $content .= $_; }
1014 close(REP) or die "Error closing report file '$filename': $!";
1015 return $content;
1016}
1017
1018sub save_message_to_disk {
1019 my $file = shift;
1020
1021 open OUTFILE, ">$file" or do { warn "Couldn't open '$file': $!\n"; return undef};
1022 print OUTFILE build_complete_message();
1023 close(OUTFILE) or do { warn "Error closing $file: $!"; return undef };
1024 print "\nMessage saved.\n";
1025 return 1;
1026}
1027
1028sub _send_message_vms {
1029 if ( ( $address =~ /@/ and $address !~ /^\w+%"/ )
1030 or ( $cc =~ /@/ and $cc !~ /^\w+%"/ ) ) {
1031 my $prefix;
1032 foreach ( qw[ IN MX SMTP UCX PONY WINS ], '' ) {
1033 $prefix = "$_%", last if $ENV{"MAIL\$PROTOCOL_$_"};
1034 }
1035 $address = qq[${prefix}"$address"] unless $address =~ /^\w+%"/;
1036 $cc = qq[${prefix}"$cc"] unless !$cc || $cc =~ /^\w+%"/;
1037 }
1038 $subject =~ s/"/""/g;
1039 $address =~ s/"/""/g;
1040 $cc =~ s/"/""/g;
1041 my $sts = system(qq[mail/Subject="$subject" $filename. "$address","$cc"]);
1042 if ($sts) {
1043 die "Can't spawn off mail (leaving bug report in $filename): $sts";
1044 }
1045}
1046
1047sub _send_message_mailsend {
1048 my $msg = Mail::Send->new();
1049 my %headers = %{_message_headers()};
1050 for my $key ( keys %headers) {
1051 $msg->add($key => $headers{$key});
1052 }
1053
1054 $fh = $msg->open;
1055 open(REP, "<$filename") or die "Couldn't open '$filename': $!\n";
1056 while (<REP>) { print $fh $_ }
1057 close(REP) or die "Error closing $filename: $!";
e90b02b9 1058 $fh->close or die "Error sending mail: $!";
54c90be1
J
1059
1060 print "\nMessage sent.\n";
1061}
1062
1063sub _probe_for_sendmail {
1064 my $sendmail = "";
1065 for (qw(/usr/lib/sendmail /usr/sbin/sendmail /usr/ucblib/sendmail)) {
1066 $sendmail = $_, last if -e $_;
1067 }
1068 if ( $^O eq 'os2' and $sendmail eq "" ) {
1069 my $path = $ENV{PATH};
1070 $path =~ s:\\:/:;
1071 my @path = split /$Config{'path_sep'}/, $path;
1072 for (@path) {
1073 $sendmail = "$_/sendmail", last if -e "$_/sendmail";
1074 $sendmail = "$_/sendmail.exe", last if -e "$_/sendmail.exe";
1075 }
1076 }
1077 return $sendmail;
1078}
1079
1080sub _send_message_sendmail {
1081 my $sendmail = _probe_for_sendmail();
1082 unless ($sendmail) {
e90d6148 1083 my $message_start = !$Is_Linux && !$Is_OpenBSD ? <<'EOT' : <<'EOT';
54c90be1
J
1084It appears that there is no program which looks like "sendmail" on
1085your system and that the Mail::Send library from CPAN isn't available.
e90d6148
A
1086EOT
1087It appears that there is no program which looks like "sendmail" on
1088your system.
1089EOT
1090 paraprint(<<"EOF"), die "\n";
1091$message_start
54c90be1
J
1092Because of this, there's no easy way to automatically send your
1093message.
1094
1095A copy of your message has been saved in '$filename' for you to
1096send to '$address' with your normal mail client.
1097EOF
1098 }
1099
019cfd23
DL
1100 open( SENDMAIL, "|-", $sendmail, "-t", "-oi", "-f", $from )
1101 || die "'|$sendmail -t -oi -f $from' failed: $!";
54c90be1
J
1102 print SENDMAIL build_complete_message();
1103 if ( close(SENDMAIL) ) {
1104 print "\nMessage sent\n";
1105 } else {
1106 warn "\nSendmail returned status '", $? >> 8, "'\n";
1107 }
1108}
1109
1110
1111
1112# a strange way to check whether any significant editing
1113# has been done: check whether any new non-empty lines
1114# have been added.
1115
1116sub _fingerprint_lines_in_report {
1117 my $new_lines = 0;
1118 # read in the report template once so that
1119 # we can track whether the user does any editing.
1120 # yes, *all* whitespace is ignored.
1121
1122 open(REP, "<$filename") or die "Unable to open report file '$filename': $!\n";
1123 while (my $line = <REP>) {
1124 $line =~ s/\s+//g;
1125 $new_lines++ if (!$REP{$line});
1126
1127 }
1128 close(REP) or die "Error closing report file '$filename': $!";
1129 # returns the number of lines with content that wasn't there when last we looked
1130 return $new_lines;
1131}
1132
1133
1134
37fa004c
PP
1135format STDOUT =
1136^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~~
1137$_
1138.
d121ca8c
CS
1139
1140__END__
1141
1142=head1 NAME
1143
1144perlbug - how to submit bug reports on Perl
1145
1146=head1 SYNOPSIS
1147
54c90be1
J
1148B<perlbug>
1149
d121ca8c 1150B<perlbug> S<[ B<-v> ]> S<[ B<-a> I<address> ]> S<[ B<-s> I<subject> ]>
105f9295
HS
1151S<[ B<-b> I<body> | B<-f> I<inputfile> ]> S<[ B<-F> I<outputfile> ]>
1152S<[ B<-r> I<returnaddress> ]>
d121ca8c 1153S<[ B<-e> I<editor> ]> S<[ B<-c> I<adminaddress> | B<-C> ]>
985dc10a 1154S<[ B<-S> ]> S<[ B<-t> ]> S<[ B<-d> ]> S<[ B<-A> ]> S<[ B<-h> ]> S<[ B<-T> ]>
d121ca8c 1155
55d729e4 1156B<perlbug> S<[ B<-v> ]> S<[ B<-r> I<returnaddress> ]>
890b8eb0 1157 S<[ B<-A> ]> S<[ B<-ok> | B<-okay> | B<-nok> | B<-nokay> ]>
1b0e3b9e 1158
985dc10a
SP
1159B<perlthanks>
1160
d121ca8c
CS
1161=head1 DESCRIPTION
1162
d121ca8c 1163
54c90be1
J
1164This program is designed to help you generate and send bug reports
1165(and thank-you notes) about perl5 and the modules which ship with it.
1166
1167In most cases, you can just run it interactively from a command
1168line without any special arguments and follow the prompts.
1169
1170If you have found a bug with a non-standard port (one that was not
1171part of the I<standard distribution>), a binary distribution, or a
1172non-core module (such as Tk, DBI, etc), then please see the
1173documentation that came with that distribution to determine the
1174correct place to report bugs.
d121ca8c 1175
54c90be1
J
1176If you are unable to send your report using B<perlbug> (most likely
1177because your system doesn't have a way to send mail that perlbug
1178recognizes), you may be able to use this tool to compose your report
1179and save it to a file which you can then send to B<perlbug@perl.org>
1180using your regular mail client.
d121ca8c 1181
54c90be1
J
1182In extreme cases, B<perlbug> may not work well enough on your system
1183to guide you through composing a bug report. In those cases, you
1184may be able to use B<perlbug -d> to get system configuration
1185information to include in a manually composed bug report to
1186B<perlbug@perl.org>.
d121ca8c 1187
54c90be1
J
1188
1189When reporting a bug, please run through this checklist:
d121ca8c
CS
1190
1191=over 4
1192
884baa66 1193=item What version of Perl you are running?
d121ca8c
CS
1194
1195Type C<perl -v> at the command line to find out.
1196
1197=item Are you running the latest released version of perl?
1198
54c90be1
J
1199Look at http://www.perl.org/ to find out. If you are not using the
1200latest released version, please try to replicate your bug on the
1201latest stable release.
1202
1203Note that reports about bugs in old versions of Perl, especially
1204those which indicate you haven't also tested the current stable
1205release of Perl, are likely to receive less attention from the
1206volunteers who build and maintain Perl than reports about bugs in
1207the current release.
1208
5538372e 1209This tool isn't appropriate for reporting bugs in any version
54c90be1 1210prior to Perl 5.0.
d121ca8c
CS
1211
1212=item Are you sure what you have is a bug?
1213
54c90be1
J
1214A significant number of the bug reports we get turn out to be
1215documented features in Perl. Make sure the issue you've run into
1216isn't intentional by glancing through the documentation that comes
1217with the Perl distribution.
d121ca8c 1218
54c90be1
J
1219Given the sheer volume of Perl documentation, this isn't a trivial
1220undertaking, but if you can point to documentation that suggests
1221the behaviour you're seeing is I<wrong>, your issue is likely to
1222receive more attention. You may want to start with B<perldoc>
1223L<perltrap> for pointers to common traps that new (and experienced)
1224Perl programmers run into.
d121ca8c 1225
54c90be1
J
1226If you're unsure of the meaning of an error message you've run
1227across, B<perldoc> L<perldiag> for an explanation. If the message
1228isn't in perldiag, it probably isn't generated by Perl. You may
1229have luck consulting your operating system documentation instead.
bdcdfa19 1230
54c90be1 1231If you are on a non-UNIX platform B<perldoc> L<perlport>, as some
1948c06a 1232features may be unimplemented or work differently.
bdcdfa19 1233
54c90be1
J
1234You may be able to figure out what's going wrong using the Perl
1235debugger. For information about how to use the debugger B<perldoc>
1236L<perldebug>.
d121ca8c
CS
1237
1238=item Do you have a proper test case?
1239
1240The easier it is to reproduce your bug, the more likely it will be
985dc10a 1241fixed -- if nobody can duplicate your problem, it probably won't be
54c90be1
J
1242addressed.
1243
1244A good test case has most of these attributes: short, simple code;
1245few dependencies on external commands, modules, or libraries; no
1246platform-dependent code (unless it's a platform-specific bug);
1247clear, simple documentation.
1248
1249A good test case is almost always a good candidate to be included in
1250Perl's test suite. If you have the time, consider writing your test case so
1251that it can be easily included into the standard test suite.
d121ca8c 1252
54c90be1 1253=item Have you included all relevant information?
d121ca8c 1254
54c90be1
J
1255Be sure to include the B<exact> error messages, if any.
1256"Perl gave an error" is not an exact error message.
bdcdfa19
JH
1257
1258If you get a core dump (or equivalent), you may use a debugger
1259(B<dbx>, B<gdb>, etc) to produce a stack trace to include in the bug
54c90be1
J
1260report.
1261
1262NOTE: unless your Perl has been compiled with debug info
bdcdfa19 1263(often B<-g>), the stack trace is likely to be somewhat hard to use
884baa66 1264because it will most probably contain only the function names and not
bdcdfa19 1265their arguments. If possible, recompile your Perl with debug info and
54c90be1 1266reproduce the crash and the stack trace.
bdcdfa19 1267
d121ca8c
CS
1268=item Can you describe the bug in plain English?
1269
54c90be1
J
1270The easier it is to understand a reproducible bug, the more likely
1271it will be fixed. Any insight you can provide into the problem
1272will help a great deal. In other words, try to analyze the problem
1273(to the extent you can) and report your discoveries.
d121ca8c
CS
1274
1275=item Can you fix the bug yourself?
1276
1277A bug report which I<includes a patch to fix it> will almost
54c90be1
J
1278definitely be fixed. When sending a patch, please use the C<diff>
1279program with the C<-u> option to generate "unified" diff files.
1280Bug reports with patches are likely to receive significantly more
1281attention and interest than those without patches.
1282
1283Your patch may be returned with requests for changes, or requests for more
d121ca8c
CS
1284detailed explanations about your fix.
1285
54c90be1
J
1286Here are a few hints for creating high-quality patches:
1287
1288Make sure the patch is not reversed (the first argument to diff is
1289typically the original file, the second argument your changed file).
1290Make sure you test your patch by applying it with the C<patch>
1291program before you send it on its way. Try to follow the same style
1292as the code you are trying to patch. Make sure your patch really
1293does work (C<make test>, if the thing you're patching is covered
1294by Perl's test suite).
d121ca8c
CS
1295
1296=item Can you use C<perlbug> to submit the report?
1297
1298B<perlbug> will, amongst other things, ensure your report includes
54c90be1
J
1299crucial information about your version of perl. If C<perlbug> is
1300unable to mail your report after you have typed it in, you may have
1301to compose the message yourself, add the output produced by C<perlbug
1302-d> and email it to B<perlbug@perl.org>. If, for some reason, you
1303cannot run C<perlbug> at all on your system, be sure to include the
1304entire output produced by running C<perl -V> (note the uppercase V).
d121ca8c 1305
bdcdfa19 1306Whether you use C<perlbug> or send the email manually, please make
54c90be1
J
1307your Subject line informative. "a bug" is not informative. Neither
1308is "perl crashes" nor is "HELP!!!". These don't help. A compact
1309description of what's wrong is fine.
bdcdfa19 1310
985dc10a
SP
1311=item Can you use C<perlbug> to submit a thank-you note?
1312
1313Yes, you can do this by either using the C<-T> option, or by invoking
1314the program as C<perlthanks>. Thank-you notes are good. It makes people
1315smile.
1316
d121ca8c
CS
1317=back
1318
54c90be1
J
1319Having done your bit, please be prepared to wait, to be told the
1320bug is in your code, or possibly to get no reply at all. The
1321volunteers who maintain Perl are busy folks, so if your problem is
1322an obvious bug in your own code, is difficult to understand or is
1323a duplicate of an existing report, you may not receive a personal
1324reply.
1325
26ab4e07 1326If it is important to you that your bug be fixed, do monitor the
a9d7774b
MM
1327perl5-porters@perl.org mailing list (mailing lists are moderated, your
1328message may take a while to show up) and the commit logs to development
54c90be1
J
1329versions of Perl, and encourage the maintainers with kind words or
1330offers of frosty beverages. (Please do be kind to the maintainers.
a9d7774b
MM
1331Harassing or flaming them is likely to have the opposite effect of the
1332one you want.)
54c90be1
J
1333
1334Feel free to update the ticket about your bug on http://rt.perl.org
1335if a new version of Perl is released and your bug is still present.
d121ca8c
CS
1336
1337=head1 OPTIONS
1338
1339=over 8
1340
1341=item B<-a>
1342
3e79b69b 1343Address to send the report to. Defaults to B<perlbug@perl.org>.
d121ca8c 1344
890b8eb0
NC
1345=item B<-A>
1346
1347Don't send a bug received acknowledgement to the reply address.
1348Generally it is only a sensible to use this option if you are a
1349perl maintainer actively watching perl porters for your message to
1350arrive.
1351
d121ca8c
CS
1352=item B<-b>
1353
1354Body of the report. If not included on the command line, or
1355in a file with B<-f>, you will get a chance to edit the message.
1356
1357=item B<-C>
1358
1359Don't send copy to administrator.
1360
1361=item B<-c>
1362
1363Address to send copy of report to. Defaults to the address of the
1364local perl administrator (recorded when perl was built).
1365
1366=item B<-d>
1367
1368Data mode (the default if you redirect or pipe output). This prints out
1369your configuration data, without mailing anything. You can use this
1370with B<-v> to get more complete data.
1371
1372=item B<-e>
1373
55d729e4 1374Editor to use.
d121ca8c
CS
1375
1376=item B<-f>
1377
1378File containing the body of the report. Use this to quickly send a
1379prepared message.
1380
105f9295
HS
1381=item B<-F>
1382
1383File to output the results to instead of sending as an email. Useful
1384particularly when running perlbug on a machine with no direct internet
1385connection.
1386
d121ca8c
CS
1387=item B<-h>
1388
1389Prints a brief summary of the options.
1390
1b0e3b9e
CR
1391=item B<-ok>
1392
84902520
TB
1393Report successful build on this system to perl porters. Forces B<-S>
1394and B<-C>. Forces and supplies values for B<-s> and B<-b>. Only
1b0e3b9e 1395prompts for a return address if it cannot guess it (for use with
84902520
TB
1396B<make>). Honors return address specified with B<-r>. You can use this
1397with B<-v> to get more complete data. Only makes a report if this
1398system is less than 60 days old.
1399
1400=item B<-okay>
1401
1402As B<-ok> except it will report on older systems.
1b0e3b9e 1403
55d729e4
GS
1404=item B<-nok>
1405
1406Report unsuccessful build on this system. Forces B<-C>. Forces and
1407supplies a value for B<-s>, then requires you to edit the report
1408and say what went wrong. Alternatively, a prepared report may be
1409supplied using B<-f>. Only prompts for a return address if it
1410cannot guess it (for use with B<make>). Honors return address
1411specified with B<-r>. You can use this with B<-v> to get more
1412complete data. Only makes a report if this system is less than 60
1413days old.
1414
1415=item B<-nokay>
1416
1417As B<-nok> except it will report on older systems.
1418
d121ca8c
CS
1419=item B<-r>
1420
1421Your return address. The program will ask you to confirm its default
1422if you don't use this option.
1423
1424=item B<-S>
1425
1426Send without asking for confirmation.
1427
1428=item B<-s>
1429
1430Subject to include with the message. You will be prompted if you don't
1431supply one on the command line.
1432
1433=item B<-t>
1434
3e79b69b 1435Test mode. The target address defaults to B<perlbug-test@perl.org>.
d121ca8c 1436
985dc10a
SP
1437=item B<-T>
1438
1439Send a thank-you note instead of a bug report.
1440
d121ca8c
CS
1441=item B<-v>
1442
1443Include verbose configuration data in the report.
1444
1445=back
1446
1447=head1 AUTHORS
1448
54c90be1
J
1449Kenneth Albanowski (E<lt>kjahds@kjahds.comE<gt>), subsequently
1450I<doc>tored by Gurusamy Sarathy (E<lt>gsar@activestate.comE<gt>),
1451Tom Christiansen (E<lt>tchrist@perl.comE<gt>), Nathan Torkington
1452(E<lt>gnat@frii.comE<gt>), Charles F. Randall (E<lt>cfr@pobox.comE<gt>),
9e533305
DH
1453Mike Guy (E<lt>mjtg@cam.ac.ukE<gt>), Dominic Dunlop
1454(E<lt>domo@computer.orgE<gt>), Hugo van der Sanden (E<lt>hv@crypt.orgE<gt>),
50d3c28b
GS
1455Jarkko Hietaniemi (E<lt>jhi@iki.fiE<gt>), Chris Nandor
1456(E<lt>pudge@pobox.comE<gt>), Jon Orwant (E<lt>orwant@media.mit.eduE<gt>,
2402d92a 1457Richard Foley (E<lt>richard.foley@rfi.netE<gt>), and Jesse Vincent
9e533305 1458(E<lt>jesse@bestpractical.comE<gt>).
d121ca8c
CS
1459
1460=head1 SEE ALSO
1461
bdcdfa19
JH
1462perl(1), perldebug(1), perldiag(1), perlport(1), perltrap(1),
1463diff(1), patch(1), dbx(1), gdb(1)
d121ca8c
CS
1464
1465=head1 BUGS
1466
1467None known (guess what must have been used to report them?)
1468
1469=cut
1470
37fa004c
PP
1471!NO!SUBS!
1472
1473close OUT or die "Can't close $file: $!";
1474chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
1475exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
8a5546a1 1476chdir $origdir;