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