This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Make lib/open.t under -Duseperlio
[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*}/;
84902520 43 chomp;
5963b987
GS
44 s/^\s+,?\s*"?//;
45 s/"?\s*,?$//;
84902520 46 s/(['\\])/\\$1/g;
fb73857a 47 push @patches, $_ unless $_ eq 'NULL';
55d729e4
GS
48}
49my $patch_desc = "'" . join("',\n '", @patches) . "'";
50my $patch_tags = join "", map /(\S+)/ ? "+$1 " : (), @patches;
84902520 51
c0a6bf09 52close(PATCH_LEVEL) or die "Error closing patchlevel.h: $!";
84902520 53
5edeba26
TB
54# TO DO (prehaps): store/embed $Config::config_sh into perlbug. When perlbug is
55# used, compare $Config::config_sh with the stored version. If they differ then
56# append a list of individual differences to the bug report.
57
84902520 58
37fa004c
PP
59print "Extracting $file (with variable substitutions)\n";
60
61# In this section, perl variables will be expanded during extraction.
62# You can use $Config{...} to use Configure variables.
63
fa510083 64my $extract_version = sprintf("%vd", $^V);
1ec03f31 65
37fa004c 66print OUT <<"!GROK!THIS!";
5f05dabc
PP
67$Config{startperl}
68 eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}'
69 if \$running_under_some_shell;
84902520 70
1ec03f31 71my \$config_tag1 = '$extract_version - $Config{cf_time}';
fb73857a 72
84902520 73my \$patchlevel_date = $patchlevel_date;
fb73857a
PP
74my \$patch_tags = '$patch_tags';
75my \@patches = (
55d729e4 76 $patch_desc
fb73857a 77);
37fa004c
PP
78!GROK!THIS!
79
80# In the following, perl variables are not expanded during extraction.
81
82print OUT <<'!NO!SUBS!';
83
721e2275 84use strict;
37fa004c 85use Config;
1ec03f31 86use File::Spec; # keep perlbug Perl 5.005 compatible
37fa004c 87use Getopt::Std;
721e2275 88use File::Basename 'basename';
37fa004c
PP
89
90sub paraprint;
91
55d729e4 92BEGIN {
26ab4e07 93 eval "use Mail::Send;";
55d729e4 94 $::HaveSend = ($@ eq "");
26ab4e07 95 eval "use Mail::Util;";
55d729e4 96 $::HaveUtil = ($@ eq "");
003a92ef 97 # use secure tempfiles wherever possible
26ab4e07 98 eval "require File::Temp;";
003a92ef 99 $::HaveTemp = ($@ eq "");
13f4c5e4
AC
100 eval { require Module::CoreList; };
101 $::HaveCoreList = ($@ eq "");
55d729e4 102};
c07a80fd 103
26ab4e07 104my $Version = "1.36";
c07a80fd
PP
105
106# Changed in 1.06 to skip Mail::Send and Mail::Util if not available.
a5f75d66
AD
107# Changed in 1.07 to see more sendmail execs, and added pipe output.
108# Changed in 1.08 to use correct address for sendmail.
c07a80fd
PP
109# Changed in 1.09 to close the REP file before calling it up in the editor.
110# Also removed some old comments duplicated elsewhere.
111# Changed in 1.10 to run under VMS without Mail::Send; also fixed
a5f75d66 112# temp filename generation.
c07a80fd 113# Changed in 1.11 to clean up some text and removed Mail::Send deactivator.
a5f75d66
AD
114# Changed in 1.12 to check for editor errors, make save/send distinction
115# clearer and add $ENV{REPLYTO}.
84478119
PP
116# Changed in 1.13 to hopefully make it more difficult to accidentally
117# send mail
ab3ef367
PP
118# Changed in 1.14 to make the prompts a little more clear on providing
119# helpful information. Also let file read fail gracefully.
8ecf1a0c
KA
120# Changed in 1.15 to add warnings to stop people using perlbug for non-bugs.
121# Also report selected environment variables.
774d564b 122# Changed in 1.16 to include @INC, and allow user to re-edit if no changes.
137443ea 123# Changed in 1.17 Win32 support added. GSAR 97-04-12
1b0e3b9e 124# Changed in 1.18 add '-ok' option for reporting build success. CFR 97-06-18
84902520
TB
125# Changed in 1.19 '-ok' default not '-v'
126# add local patch information
127# warn on '-ok' if this is an old system; add '-okay'
fb73857a 128# Changed in 1.20 Added patchlevel.h reading and version/config checks
55d729e4
GS
129# Changed in 1.21 Added '-nok' for reporting build failure DFD 98-05-05
130# Changed in 1.22 Heavy reformatting & minor bugfixes HVDS 98-05-10
cca87523 131# Changed in 1.23 Restore -ok(ay): say 'success'; don't prompt
105f9295 132# Changed in 1.24 Added '-F<file>' to save report HVDS 98-07-01
8b49bb9a 133# Changed in 1.25 Warn on failure to open save file. HVDS 98-07-12
eedd3c36 134# Changed in 1.26 Don't require -t STDIN for -ok. HVDS 98-07-15
1948c06a 135# Changed in 1.27 Added Mac OS and File::Spec support CNANDOR 99-07-27
50d3c28b 136# Changed in 1.28 Additional questions for Perlbugtron RFOLEY 20.03.2000
975b416b 137# Changed in 1.29 Perlbug(tron): auto(-ok), short prompts RFOLEY 05-05-2000
b0c10877 138# Changed in 1.30 Added warnings on failure to open files MSTEVENS 13-07-2000
c0a6bf09 139# Changed in 1.31 Add checks on close().Fix my $var unless. TJENNESS 26-07-2000
93b42772 140# Changed in 1.32 Use File::Spec->tmpdir TJENNESS 20-08-2000
489b74f8 141# Changed in 1.33 Don't require -t STDOUT for -ok.
de94c9df 142# Changed in 1.34 Added Message-Id RFOLEY 18-06-2002
003a92ef 143# Changed in 1.35 Use File::Temp (patch from Solar Designer) NWCLARK 28-02-2004
13f4c5e4 144# Changed in 1.36 Initial Module::CoreList support Alexandr Ciornii 11-07-2007
26ab4e07 145
1b0e3b9e 146# TODO: - Allow the user to re-name the file on mail failure, and
55d729e4 147# make sure failure (transmission-wise) of Mail::Send is
c07a80fd 148# accounted for.
1b0e3b9e 149# - Test -b option
37fa004c 150
721e2275
NC
151my( $file, $usefile, $cc, $address, $bugaddress, $testaddress, $thanksaddress,
152 $filename, $messageid, $domain, $subject, $from, $verbose, $ed, $outfile,
153 $Is_MacOS, $category, $severity, $fh, $me, $Is_MSWin32, $Is_Linux, $Is_VMS,
154 $msg, $body, $andcc, %REP, $ok, $thanks, $Is_OpenBSD, $progname);
37fa004c 155
fa510083 156my $perl_version = $^V ? sprintf("%vd", $^V) : $];
1ec03f31
GS
157
158my $config_tag2 = "$perl_version - $Config{cf_time}";
fb73857a 159
37fa004c
PP
160Init();
161
55d729e4
GS
162if ($::opt_h) { Help(); exit; }
163if ($::opt_d) { Dump(*STDOUT); exit; }
eedd3c36 164if (!-t STDIN && !($ok and not $::opt_n)) {
721e2275
NC
165 paraprint <<"EOF";
166Please use $progname interactively. If you want to
84478119
PP
167include a file, you can use the -f switch.
168EOF
55d729e4 169 die "\n";
84478119 170}
c07a80fd 171
37fa004c 172Query();
cca87523 173Edit() unless $usefile || ($ok and not $::opt_n);
37fa004c
PP
174NowWhat();
175Send();
176
177exit;
178
975b416b 179sub ask_for_alternatives { # (category|severity)
50d3c28b 180 my $name = shift;
975b416b
GS
181 my %alts = (
182 'category' => {
183 'default' => 'core',
184 'ok' => 'install',
721e2275
NC
185 # Inevitably some of these will end up in RT whatever we do:
186 'thanks' => 'thanks',
975b416b
GS
187 'opts' => [qw(core docs install library utilities)], # patch, notabug
188 },
189 'severity' => {
190 'default' => 'low',
191 'ok' => 'none',
dda32041 192 'thanks' => 'none',
975b416b 193 'opts' => [qw(critical high medium low wishlist none)], # zero
7f2de2d2 194 },
975b416b 195 );
7f2de2d2 196 die "Invalid alternative($name) requested\n" unless grep(/^$name$/, keys %alts);
50d3c28b 197 my $alt = "";
721e2275
NC
198 my $what = $ok || $thanks;
199 if ($what) {
200 $alt = $alts{$name}{$what};
975b416b
GS
201 } else {
202 my @alts = @{$alts{$name}{'opts'}};
203 paraprint <<EOF;
50d3c28b
GS
204Please pick a \u$name from the following:
205
206 @alts
207
208EOF
975b416b
GS
209 my $err = 0;
210 do {
211 if ($err++ > 5) {
212 die "Invalid $name: aborting.\n";
213 }
214 print "Please enter a \u$name [$alts{$name}{'default'}]: ";
215 $alt = <>;
216 chomp $alt;
217 if ($alt =~ /^\s*$/) {
218 $alt = $alts{$name}{'default'};
219 }
220 } while !((($alt) = grep(/^$alt/i, @alts)));
221 }
50d3c28b
GS
222 lc $alt;
223}
224
37fa004c 225sub Init {
55d729e4
GS
226 # -------- Setup --------
227
228 $Is_MSWin32 = $^O eq 'MSWin32';
229 $Is_VMS = $^O eq 'VMS';
afc5e478 230 $Is_Linux = lc($^O) eq 'linux';
8843dda6 231 $Is_OpenBSD = lc($^O) eq 'openbsd';
1948c06a
CN
232 $Is_MacOS = $^O eq 'MacOS';
233
234 @ARGV = split m/\s+/,
26ab4e07 235 MacPerl::Ask('Provide command-line args here (-h for help):')
1948c06a 236 if $Is_MacOS && $MacPerl::Version =~ /App/;
55d729e4 237
721e2275 238 if (!getopts("Adhva:s:b:f:F:r:e:SCc:to:n:T")) { Help(); exit; };
55d729e4
GS
239
240 # This comment is needed to notify metaconfig that we are
241 # using the $perladmin, $cf_by, and $cf_time definitions.
242
243 # -------- Configuration ---------
244
245 # perlbug address
721e2275 246 $bugaddress = 'perlbug@perl.org';
55d729e4
GS
247
248 # Test address
3e79b69b 249 $testaddress = 'perlbug-test@perl.org';
55d729e4 250
721e2275
NC
251 # Thanks address
252 $thanksaddress = 'perl-thanks@perl.org';
253
254 if (basename ($0) =~ /^perlthanks/i) {
255 # invoked as perlthanks
256 $::opt_T = 1;
257 $::opt_C = 1; # don't send a copy to the local admin
258 }
259
260 if ($::opt_T) {
261 $thanks = 'thanks';
262 }
263
264 $progname = $thanks ? 'perlthanks' : 'perlbug';
55d729e4 265 # Target address
721e2275
NC
266 $address = $::opt_a || ($::opt_t ? $testaddress
267 : $thanks ? $thanksaddress : $bugaddress);
55d729e4
GS
268
269 # Users address, used in message and in Reply-To header
270 $from = $::opt_r || "";
271
272 # Include verbose configuration information
273 $verbose = $::opt_v || 0;
274
275 # Subject of bug-report message
276 $subject = $::opt_s || "";
277
278 # Send a file
279 $usefile = ($::opt_f || 0);
280
281 # File to send as report
282 $file = $::opt_f || "";
283
105f9295
HS
284 # File to output to
285 $outfile = $::opt_F || "";
286
55d729e4
GS
287 # Body of report
288 $body = $::opt_b || "";
de94c9df 289
55d729e4
GS
290 # Editor
291 $ed = $::opt_e || $ENV{VISUAL} || $ENV{EDITOR} || $ENV{EDIT}
292 || ($Is_VMS && "edit/tpu")
293 || ($Is_MSWin32 && "notepad")
1948c06a 294 || ($Is_MacOS && '')
55d729e4
GS
295 || "vi";
296
297 # Not OK - provide build failure template by finessing OK report
298 if ($::opt_n) {
299 if (substr($::opt_n, 0, 2) eq 'ok' ) {
300 $::opt_o = substr($::opt_n, 1);
301 } else {
302 Help();
303 exit();
304 }
305 }
306
307 # OK - send "OK" report for build on this system
721e2275 308 $ok = '';
55d729e4
GS
309 if ($::opt_o) {
310 if ($::opt_o eq 'k' or $::opt_o eq 'kay') {
311 my $age = time - $patchlevel_date;
312 if ($::opt_o eq 'k' and $age > 60 * 24 * 60 * 60 ) {
313 my $date = localtime $patchlevel_date;
314 print <<"EOF";
315"perlbug -ok" and "perlbug -nok" do not report on Perl versions which
316are more than 60 days old. This Perl version was constructed on
317$date. If you really want to report this, use
318"perlbug -okay" or "perlbug -nokay".
84902520 319EOF
1b0e3b9e
CR
320 exit();
321 }
55d729e4
GS
322 # force these options
323 unless ($::opt_n) {
324 $::opt_S = 1; # don't prompt for send
325 $::opt_b = 1; # we have a body
326 $body = "Perl reported to build OK on this system.\n";
327 }
328 $::opt_C = 1; # don't send a copy to the local admin
329 $::opt_s = 1; # we have a subject line
330 $subject = ($::opt_n ? 'Not ' : '')
1ec03f31 331 . "OK: perl $perl_version ${patch_tags}on"
55d729e4 332 ." $::Config{'archname'} $::Config{'osvers'} $subject";
721e2275 333 $ok = 'ok';
55d729e4
GS
334 } else {
335 Help();
336 exit();
1b0e3b9e 337 }
55d729e4 338 }
37fa004c 339
55d729e4
GS
340 # Possible administrator addresses, in order of confidence
341 # (Note that cf_email is not mentioned to metaconfig, since
342 # we don't really want it. We'll just take it if we have to.)
343 #
344 # This has to be after the $ok stuff above because of the way
345 # that $::opt_C is forced.
346 $cc = $::opt_C ? "" : (
347 $::opt_c || $::Config{'perladmin'}
348 || $::Config{'cf_email'} || $::Config{'cf_by'}
349 );
350
de94c9df
RF
351 if ($::HaveUtil) {
352 $domain = Mail::Util::maildomain();
353 } elsif ($Is_MSWin32) {
354 $domain = $ENV{'USERDOMAIN'};
355 } else {
356 require Sys::Hostname;
357 $domain = Sys::Hostname::hostname();
358 }
359
360 # Message-Id - rjsf
361 $messageid = "<$::Config{'version'}_${$}_".time."\@$domain>";
362
55d729e4
GS
363 # My username
364 $me = $Is_MSWin32 ? $ENV{'USERNAME'}
365 : $^O eq 'os2' ? $ENV{'USER'} || $ENV{'LOGNAME'}
1948c06a 366 : $Is_MacOS ? $ENV{'USER'}
55d729e4 367 : eval { getpwuid($<) }; # May be missing
c0830f08
RB
368
369 $from = $::Config{'cf_email'}
370 if !$from && $::Config{'cf_email'} && $::Config{'cf_by'} && $me &&
371 ($me eq $::Config{'cf_by'});
55d729e4 372} # sub Init
37fa004c
PP
373
374sub Query {
55d729e4
GS
375 # Explain what perlbug is
376 unless ($ok) {
721e2275
NC
377 if ($thanks) {
378 paraprint <<'EOF';
379This program provides an easy way to send a thank-you message back to the
380authors and maintainers of perl.
381
382If you wish to submit a bug report, please run it without the -T flag
383(or run the program perlbug rather than perlthanks)
384EOF
385 } else {
386 paraprint <<"EOF";
26ab4e07
RGS
387This program provides an easy way to create a message reporting a bug
388in perl, and e-mail it to $address. It is *NOT* intended for
389sending test messages or simply verifying that perl works, *NOR* is it
390intended for reporting bugs in third-party perl modules. It is *ONLY*
391a means of reporting verifiable problems with the core perl distribution,
392and any solutions to such problems, to the people who maintain perl.
393
394If you're just looking for help with perl, try posting to the Usenet
395newsgroup comp.lang.perl.misc. If you're looking for help with using
396perl with CGI, try posting to comp.infosystems.www.programming.cgi.
397
398When invoked as perlthanks (or with the -T option) it can be used to
399send a thank-you message to $thanksaddress.
37fa004c 400EOF
721e2275 401 }
1b0e3b9e 402 }
37fa004c 403
55d729e4 404 # Prompt for subject of message, if needed
2e7f46bf 405
26ab4e07 406 if (TrivialSubject($subject)) {
2e7f46bf
JH
407 $subject = '';
408 }
409
55d729e4 410 unless ($subject) {
26ab4e07
RGS
411 if ($thanks) {
412 paraprint "First of all, please provide a subject for the message.\n";
413 } else {
721e2275 414 paraprint <<EOF;
26ab4e07
RGS
415First of all, please provide a subject for the
416message. It should be a concise description of
417the bug or problem. "perl bug" or "perl problem"
418is not a concise description.
37fa004c 419EOF
721e2275 420 }
55d729e4
GS
421
422 my $err = 0;
2e7f46bf
JH
423 do {
424 print "Subject: ";
55d729e4 425 $subject = <>;
2e7f46bf
JH
426 chomp $subject;
427 if ($err++ == 5) {
721e2275
NC
428 if ($thanks) {
429 $subject = 'Thanks for Perl';
430 } else {
431 die "Aborting.\n";
432 }
55d729e4 433 }
2e7f46bf 434 } while (TrivialSubject($subject));
55d729e4
GS
435 }
436
437 # Prompt for return address, if needed
438 unless ($from) {
439 # Try and guess return address
440 my $guess;
441
442 $guess = $ENV{'REPLY-TO'} || $ENV{'REPLYTO'} || '';
1948c06a
CN
443 if ($Is_MacOS) {
444 require Mac::InternetConfig;
445 $guess = $Mac::InternetConfig::InternetConfig{
446 Mac::InternetConfig::kICEmail()
447 };
448 }
449
55d729e4 450 unless ($guess) {
de94c9df
RF
451 # move $domain to where we can use it elsewhere
452 if ($domain) {
55d729e4
GS
453 if ($Is_VMS && !$::Config{'d_socket'}) {
454 $guess = "$domain\:\:$me";
41f926b8 455 } else {
55d729e4 456 $guess = "$me\@$domain" if $domain;
c07a80fd 457 }
55d729e4
GS
458 }
459 }
37fa004c 460
55d729e4
GS
461 if ($guess) {
462 unless ($ok) {
463 paraprint <<EOF;
26ab4e07
RGS
464Your e-mail address will be useful if you need to be contacted. If the
465default shown is not your full internet e-mail address, please correct it.
37fa004c 466EOF
55d729e4
GS
467 }
468 } else {
469 paraprint <<EOF;
26ab4e07
RGS
470So that you may be contacted if necessary, please enter
471your full internet e-mail address here.
37fa004c 472EOF
37fa004c 473 }
37fa004c 474
55d729e4
GS
475 if ($ok && $guess) {
476 # use it
477 $from = $guess;
478 } else {
479 # verify it
480 print "Your address [$guess]: ";
481 $from = <>;
2e7f46bf 482 chomp $from;
55d729e4
GS
483 $from = $guess if $from eq '';
484 }
485 }
37fa004c 486
55d729e4
GS
487 if ($from eq $cc or $me eq $cc) {
488 # Try not to copy ourselves
489 $cc = "yourself";
490 }
37fa004c 491
55d729e4
GS
492 # Prompt for administrator address, unless an override was given
493 if( !$::opt_C and !$::opt_c ) {
494 paraprint <<EOF;
26ab4e07
RGS
495A copy of this report can be sent to your local
496perl administrator. If the address is wrong, please
497correct it, or enter 'none' or 'yourself' to not send
498a copy.
37fa004c 499EOF
55d729e4
GS
500 print "Local perl administrator [$cc]: ";
501 my $entry = scalar <>;
2e7f46bf 502 chomp $entry;
37fa004c 503
55d729e4
GS
504 if ($entry ne "") {
505 $cc = $entry;
506 $cc = '' if $me eq $cc;
37fa004c 507 }
55d729e4 508 }
37fa004c 509
55d729e4
GS
510 $cc = '' if $cc =~ /^(none|yourself|me|myself|ourselves)$/i;
511 $andcc = " and $cc" if $cc;
37fa004c 512
55d729e4 513 # Prompt for editor, if no override is given
ab3ef367 514editor:
55d729e4 515 unless ($::opt_e || $::opt_f || $::opt_b) {
721e2275 516 chomp (my $common_end = <<"EOF");
26ab4e07
RGS
517
518You will probably want to use an editor to enter
519the report. If "$ed" is the editor you want
520to use, then just press Enter, otherwise type in
521the name of the editor you would like to use.
522
523If you would like to use a prepared file, type
524"file", and you will be asked for the filename.
721e2275
NC
525EOF
526
527 if ($thanks) {
528 paraprint <<"EOF";
26ab4e07 529Now you need to supply your thank-you message.
721e2275 530
26ab4e07
RGS
531Some information about your local perl configuration
532will automatically be included at the end of the message,
533because we're curious about the different ways that people
534build perl, but you're welcome to delete it if you wish.
721e2275
NC
535
536$common_end
537EOF
538 } else {
539 paraprint <<"EOF";
26ab4e07
RGS
540Now you need to supply the bug report. Try to make
541the report concise but descriptive. Include any
542relevant detail. If you are reporting something
543that does not work as you think it should, please
544try to include example of both the actual
545result, and what you expected.
546
547Some information about your local
548perl configuration will automatically be included
549at the end of the report. If you are using any
550unusual version of perl, please try and confirm
551exactly which versions are relevant.
37fa004c 552
721e2275 553$common_end
37fa004c 554EOF
721e2275
NC
555 }
556
55d729e4
GS
557 print "Editor [$ed]: ";
558 my $entry =scalar <>;
2e7f46bf 559 chomp $entry;
55d729e4
GS
560
561 $usefile = 0;
562 if ($entry eq "file") {
563 $usefile = 1;
564 } elsif ($entry ne "") {
565 $ed = $entry;
37fa004c 566 }
55d729e4 567 }
13f4c5e4 568 my $report_about_module = '';
721e2275 569 if ($::HaveCoreList && !$ok && !$thanks) {
13f4c5e4 570 paraprint <<EOF;
26ab4e07 571Is your report about a Perl module? If yes, enter its name. If not, skip.
13f4c5e4
AC
572EOF
573 print "Module []: ";
574 my $entry = scalar <>;
575 $entry =~ s/^\s+//s;
576 $entry =~ s/\s+$//s;
577 if ($entry ne q{}) {
578 $category ||= 'library';
579 $report_about_module = $entry;
580 my $first_release = Module::CoreList->first_release($entry);
581 unless ($first_release) {
582 paraprint <<EOF;
26ab4e07
RGS
583Module $entry is not a core module. Please check that
584you entered its name correctly. If it is correct,
585abort this program, try searching for $entry on
586search.cpan.org, and report it there.
13f4c5e4
AC
587EOF
588 }
589 }
590 }
37fa004c 591
50d3c28b 592 # Prompt for category of bug
975b416b 593 $category ||= ask_for_alternatives('category');
50d3c28b
GS
594
595 # Prompt for severity of bug
975b416b 596 $severity ||= ask_for_alternatives('severity');
50d3c28b 597
55d729e4
GS
598 # Generate scratch file to edit report in
599 $filename = filename();
37fa004c 600
55d729e4
GS
601 # Prompt for file to read report from, if needed
602 if ($usefile and !$file) {
ab3ef367 603filename:
55d729e4 604 paraprint <<EOF;
37fa004c 605What is the name of the file that contains your report?
37fa004c 606EOF
55d729e4
GS
607 print "Filename: ";
608 my $entry = scalar <>;
2e7f46bf 609 chomp $entry;
37fa004c 610
55d729e4
GS
611 if ($entry eq "") {
612 paraprint <<EOF;
26ab4e07 613No filename? I'll let you go back and choose an editor again.
ab3ef367 614EOF
55d729e4
GS
615 goto editor;
616 }
617
618 unless (-f $entry and -r $entry) {
619 paraprint <<EOF;
26ab4e07
RGS
620I'm sorry, but I can't read from '$entry'. Maybe you mistyped the name of
621the file? If you don't want to send a file, just enter a blank line and you
622can get back to the editor selection.
ab3ef367 623EOF
55d729e4 624 goto filename;
37fa004c 625 }
55d729e4
GS
626 $file = $entry;
627 }
37fa004c 628
55d729e4 629 # Generate report
c9967ac8 630 open(REP,">$filename") or die "Unable to create report file '$filename': $!\n";
721e2275
NC
631 my $reptype = !$ok ? ($thanks ? 'thank-you' : 'bug')
632 : $::opt_n ? "build failure" : "success";
37fa004c 633
55d729e4 634 print REP <<EOF;
84902520 635This is a $reptype report for perl from $from,
1ec03f31 636generated with the help of perlbug $Version running under perl $perl_version.
37fa004c
PP
637
638EOF
639
55d729e4
GS
640 if ($body) {
641 print REP $body;
642 } elsif ($usefile) {
643 open(F, "<$file")
c9967ac8 644 or die "Unable to read report file from '$file': $!\n";
55d729e4
GS
645 while (<F>) {
646 print REP $_
647 }
c9967ac8 648 close(F) or die "Error closing '$file': $!";
55d729e4 649 } else {
721e2275
NC
650 if ($thanks) {
651 print REP <<'EOF';
652
653-----------------------------------------------------------------
26ab4e07 654[Please enter your thank you message here]
721e2275
NC
655
656
657
26ab4e07 658[You're welcome to delete anything below this line if you prefer]
721e2275
NC
659-----------------------------------------------------------------
660EOF
661 } else {
662 print REP <<'EOF';
774d564b
PP
663
664-----------------------------------------------------------------
26ab4e07 665[Please enter your report here]
774d564b
PP
666
667
668
669[Please do not change anything below this line]
670-----------------------------------------------------------------
671EOF
721e2275 672 }
55d729e4
GS
673 }
674 Dump(*REP);
c0a6bf09 675 close(REP) or die "Error closing report file: $!";
55d729e4
GS
676
677 # read in the report template once so that
678 # we can track whether the user does any editing.
679 # yes, *all* whitespace is ignored.
c9967ac8 680 open(REP, "<$filename") or die "Unable to open report file '$filename': $!\n";
55d729e4
GS
681 while (<REP>) {
682 s/\s+//g;
683 $REP{$_}++;
684 }
c9967ac8 685 close(REP) or die "Error closing report file '$filename': $!";
55d729e4 686} # sub Query
c07a80fd
PP
687
688sub Dump {
55d729e4 689 local(*OUT) = @_;
37fa004c 690
50d3c28b
GS
691 print OUT <<EFF;
692---
693Flags:
694 category=$category
695 severity=$severity
890b8eb0
NC
696EFF
697 if ($::opt_A) {
698 print OUT <<EFF;
699 ack=no
700EFF
701 }
702 print OUT <<EFF;
50d3c28b
GS
703---
704EFF
705 print OUT "This perlbug was built using Perl $config_tag1\n",
1ec03f31 706 "It is being executed now by Perl $config_tag2.\n\n"
55d729e4 707 if $config_tag2 ne $config_tag1;
fb73857a 708
55d729e4 709 print OUT <<EOF;
1ec03f31 710Site configuration information for perl $perl_version:
37fa004c
PP
711
712EOF
55d729e4
GS
713 if ($::Config{cf_by} and $::Config{cf_time}) {
714 print OUT "Configured by $::Config{cf_by} at $::Config{cf_time}.\n\n";
715 }
716 print OUT Config::myconfig;
37fa004c 717
55d729e4
GS
718 if (@patches) {
719 print OUT join "\n ", "Locally applied patches:", @patches;
720 print OUT "\n";
721 };
84902520 722
55d729e4 723 print OUT <<EOF;
8ecf1a0c 724
774d564b 725---
1ec03f31 726\@INC for perl $perl_version:
774d564b 727EOF
55d729e4
GS
728 for my $i (@INC) {
729 print OUT " $i\n";
730 }
774d564b 731
55d729e4 732 print OUT <<EOF;
8ecf1a0c 733
774d564b 734---
1ec03f31 735Environment for perl $perl_version:
8ecf1a0c 736EOF
5cf1d1f1
JH
737 my @env =
738 qw(PATH LD_LIBRARY_PATH LANG PERL_BADLANG SHELL HOME LOGDIR LANGUAGE);
739 push @env, $Config{ldlibpthname} if $Config{ldlibpthname} ne '';
27414c22 740 push @env, grep /^(?:PERL|LC_|LANG|CYGWIN)/, keys %ENV;
8876aa85
JH
741 my %env;
742 @env{@env} = @env;
743 for my $env (sort keys %env) {
55d729e4
GS
744 print OUT " $env",
745 exists $ENV{$env} ? "=$ENV{$env}" : ' (unset)',
746 "\n";
747 }
748 if ($verbose) {
1ec03f31 749 print OUT "\nComplete configuration data for perl $perl_version:\n\n";
55d729e4
GS
750 my $value;
751 foreach (sort keys %::Config) {
752 $value = $::Config{$_};
753 $value =~ s/'/\\'/g;
754 print OUT "$_='$value'\n";
84902520 755 }
55d729e4
GS
756 }
757} # sub Dump
37fa004c
PP
758
759sub Edit {
55d729e4
GS
760 # Edit the report
761 if ($usefile || $body) {
762 paraprint <<EOF;
ab3ef367 763Please make sure that the name of the editor you want to use is correct.
ab3ef367 764EOF
55d729e4
GS
765 print "Editor [$ed]: ";
766 my $entry =scalar <>;
2e7f46bf 767 chomp $entry;
55d729e4
GS
768 $ed = $entry unless $entry eq '';
769 }
a5f75d66 770
55d729e4 771tryagain:
c0a6bf09
TJ
772 my $sts;
773 $sts = system("$ed $filename") unless $Is_MacOS;
1948c06a
CN
774 if ($Is_MacOS) {
775 require ExtUtils::MakeMaker;
776 ExtUtils::MM_MacOS::launch_file($filename);
777 paraprint <<EOF;
778Press Enter when done.
779EOF
780 scalar <>;
781 }
55d729e4
GS
782 if ($sts) {
783 paraprint <<EOF;
26ab4e07
RGS
784The editor you chose ('$ed') could apparently not be run!
785Did you mistype the name of your editor? If so, please
786correct it here, otherwise just press Enter.
a5f75d66 787EOF
55d729e4
GS
788 print "Editor [$ed]: ";
789 my $entry =scalar <>;
2e7f46bf 790 chomp $entry;
a5f75d66 791
55d729e4
GS
792 if ($entry ne "") {
793 $ed = $entry;
794 goto tryagain;
795 } else {
796 paraprint <<EOF;
26ab4e07
RGS
797You may want to save your report to a file, so you can edit and mail it
798yourself.
a5f75d66 799EOF
774d564b 800 }
55d729e4 801 }
774d564b 802
55d729e4
GS
803 return if ($ok and not $::opt_n) || $body;
804 # Check that we have a report that has some, eh, report in it.
805 my $unseen = 0;
806
c9967ac8 807 open(REP, "<$filename") or die "Couldn't open '$filename': $!\n";
55d729e4
GS
808 # a strange way to check whether any significant editing
809 # have been done: check whether any new non-empty lines
810 # have been added. Yes, the below code ignores *any* space
811 # in *any* line.
812 while (<REP>) {
813 s/\s+//g;
814 $unseen++ if $_ ne '' and not exists $REP{$_};
815 }
774d564b 816
55d729e4
GS
817 while ($unseen == 0) {
818 paraprint <<EOF;
26ab4e07 819I am sorry but it looks like you did not report anything.
774d564b 820EOF
55d729e4
GS
821 print "Action (Retry Edit/Cancel) ";
822 my ($action) = scalar(<>);
823 if ($action =~ /^[re]/i) { # <R>etry <E>dit
824 goto tryagain;
825 } elsif ($action =~ /^[cq]/i) { # <C>ancel, <Q>uit
826 Cancel();
827 }
828 }
829} # sub Edit
774d564b
PP
830
831sub Cancel {
832 1 while unlink($filename); # remove all versions under VMS
833 print "\nCancelling.\n";
834 exit(0);
37fa004c
PP
835}
836
837sub NowWhat {
55d729e4
GS
838 # Report is done, prompt for further action
839 if( !$::opt_S ) {
840 while(1) {
26ab4e07
RGS
841 paraprint <<EOF;
842Now that you have completed your report, would you like to send
843the message to $address$andcc, display the message on
844the screen, re-edit it, display/change the subject,
845or cancel without sending anything?
846You may also save the message as a file to mail at another time.
37fa004c 847EOF
8b49bb9a 848 retry:
2e7f46bf 849 print "Action (Send/Display/Edit/Subject/Save to File): ";
55d729e4 850 my $action = scalar <>;
2e7f46bf 851 chomp $action;
26ab4e07 852
55d729e4 853 if ($action =~ /^(f|sa)/i) { # <F>ile/<Sa>ve
721e2275 854 my $file_save = $outfile || "$progname.rep";
fd49642c 855 print "\n\nName of file to save message in [$file_save]: ";
55d729e4 856 my $file = scalar <>;
2e7f46bf 857 chomp $file;
fd49642c 858 $file = $file_save if $file eq "";
55d729e4 859
8b49bb9a
HS
860 unless (open(FILE, ">$file")) {
861 print "\nError opening $file: $!\n\n";
862 goto retry;
863 }
c9967ac8 864 open(REP, "<$filename") or die "Couldn't open file '$filename': $!\n";
55d729e4
GS
865 print FILE "To: $address\nSubject: $subject\n";
866 print FILE "Cc: $cc\n" if $cc;
867 print FILE "Reply-To: $from\n" if $from;
de94c9df 868 print FILE "Message-Id: $messageid\n" if $messageid;
55d729e4
GS
869 print FILE "\n";
870 while (<REP>) { print FILE }
c9967ac8 871 close(REP) or die "Error closing report file '$filename': $!";
c0a6bf09 872 close(FILE) or die "Error closing $file: $!";
55d729e4 873
26ab4e07 874 print "\nMessage saved in '$file'.\n";
55d729e4
GS
875 exit;
876 } elsif ($action =~ /^(d|l|sh)/i ) { # <D>isplay, <L>ist, <Sh>ow
877 # Display the message
c9967ac8 878 open(REP, "<$filename") or die "Couldn't open file '$filename': $!\n";
55d729e4 879 while (<REP>) { print $_ }
c9967ac8 880 close(REP) or die "Error closing report file '$filename': $!";
2e7f46bf 881 } elsif ($action =~ /^su/i) { # <Su>bject
26ab4e07
RGS
882 print "Subject: $subject\n";
883 print "If the above subject is fine, just press Enter.\n";
884 print "If not, type in the new subject.\n";
2e7f46bf
JH
885 print "Subject: ";
886 my $reply = scalar <STDIN>;
887 chomp $reply;
888 if ($reply ne '') {
889 unless (TrivialSubject($reply)) {
890 $subject = $reply;
891 print "Subject: $subject\n";
892 }
893 }
55d729e4
GS
894 } elsif ($action =~ /^se/i) { # <S>end
895 # Send the message
896 print "Are you certain you want to send this message?\n"
897 . 'Please type "yes" if you are: ';
898 my $reply = scalar <STDIN>;
2e7f46bf 899 chomp $reply;
26ab4e07 900 if ($reply eq "yes") {
55d729e4
GS
901 last;
902 } else {
903 paraprint <<EOF;
26ab4e07
RGS
904That wasn't a clear "yes", so I won't send your message. If you are sure
905your message should be sent, type in "yes" (without the quotes) at the
906confirmation prompt.
ab3ef367 907EOF
55d729e4
GS
908 }
909 } elsif ($action =~ /^[er]/i) { # <E>dit, <R>e-edit
910 # edit the message
911 Edit();
912 } elsif ($action =~ /^[qc]/i) { # <C>ancel, <Q>uit
913 Cancel();
01544859 914 } elsif ($action =~ /^s/i) {
55d729e4 915 paraprint <<EOF;
26ab4e07 916I'm sorry, but I didn't understand that. Please type "send" or "save".
84478119 917EOF
55d729e4 918 }
37fa004c 919 }
55d729e4
GS
920 }
921} # sub NowWhat
37fa004c 922
2e7f46bf
JH
923sub TrivialSubject {
924 my $subject = shift;
925 if ($subject =~
926 /^(y(es)?|no?|help|perl( (bug|problem))?|bug|problem)$/i ||
927 length($subject) < 4 ||
928 $subject !~ /\s/) {
26ab4e07 929 print "\nThat doesn't look like a good subject. Please be more verbose.\n\n";
2e7f46bf
JH
930 return 1;
931 } else {
932 return 0;
933 }
934}
935
37fa004c 936sub Send {
55d729e4 937 # Message has been accepted for transmission -- Send the message
105f9295
HS
938 if ($outfile) {
939 open SENDMAIL, ">$outfile" or die "Couldn't open '$outfile': $!\n";
940 goto sendout;
941 }
afc5e478
SB
942
943 # on linux certain mail implementations won't accept the subject
944 # as "~s subject" and thus the Subject header will be corrupted
945 # so don't use Mail::Send to be safe
8843dda6 946 if ($::HaveSend && !$Is_Linux && !$Is_OpenBSD) {
55d729e4
GS
947 $msg = new Mail::Send Subject => $subject, To => $address;
948 $msg->cc($cc) if $cc;
949 $msg->add("Reply-To",$from) if $from;
950
951 $fh = $msg->open;
c9967ac8 952 open(REP, "<$filename") or die "Couldn't open '$filename': $!\n";
55d729e4 953 while (<REP>) { print $fh $_ }
c0a6bf09 954 close(REP) or die "Error closing $filename: $!";
55d729e4
GS
955 $fh->close;
956
957 print "\nMessage sent.\n";
958 } elsif ($Is_VMS) {
959 if ( ($address =~ /@/ and $address !~ /^\w+%"/) or
960 ($cc =~ /@/ and $cc !~ /^\w+%"/) ) {
961 my $prefix;
962 foreach (qw[ IN MX SMTP UCX PONY WINS ], '') {
963 $prefix = "$_%", last if $ENV{"MAIL\$PROTOCOL_$_"};
964 }
965 $address = qq[${prefix}"$address"] unless $address =~ /^\w+%"/;
966 $cc = qq[${prefix}"$cc"] unless !$cc || $cc =~ /^\w+%"/;
967 }
968 $subject =~ s/"/""/g; $address =~ s/"/""/g; $cc =~ s/"/""/g;
969 my $sts = system(qq[mail/Subject="$subject" $filename. "$address","$cc"]);
970 if ($sts) {
971 die <<EOF;
972Can't spawn off mail
973 (leaving bug report in $filename): $sts
974EOF
975 }
976 } else {
977 my $sendmail = "";
978 for (qw(/usr/lib/sendmail /usr/sbin/sendmail /usr/ucblib/sendmail)) {
979 $sendmail = $_, last if -e $_;
980 }
981 if ($^O eq 'os2' and $sendmail eq "") {
982 my $path = $ENV{PATH};
983 $path =~ s:\\:/: ;
984 my @path = split /$Config{'path_sep'}/, $path;
985 for (@path) {
986 $sendmail = "$_/sendmail", last if -e "$_/sendmail";
987 $sendmail = "$_/sendmail.exe", last if -e "$_/sendmail.exe";
988 }
989 }
37fa004c 990
55d729e4 991 paraprint(<<"EOF"), die "\n" if $sendmail eq "";
26ab4e07
RGS
992I am terribly sorry, but I cannot find sendmail, or a close equivalent, and
993the perl package Mail::Send has not been installed, so I can't send your bug
994report. We apologize for the inconvenience.
c07a80fd 995
26ab4e07
RGS
996So you may attempt to find some way of sending your message, it has
997been left in the file '$filename'.
c07a80fd 998EOF
01544859 999 open(SENDMAIL, "|$sendmail -t -oi") || die "'|$sendmail -t -oi' failed: $!";
105f9295 1000sendout:
55d729e4
GS
1001 print SENDMAIL "To: $address\n";
1002 print SENDMAIL "Subject: $subject\n";
1003 print SENDMAIL "Cc: $cc\n" if $cc;
1004 print SENDMAIL "Reply-To: $from\n" if $from;
de94c9df 1005 print SENDMAIL "Message-Id: $messageid\n" if $messageid;
55d729e4 1006 print SENDMAIL "\n\n";
c9967ac8 1007 open(REP, "<$filename") or die "Couldn't open '$filename': $!\n";
55d729e4 1008 while (<REP>) { print SENDMAIL $_ }
c0a6bf09 1009 close(REP) or die "Error closing $filename: $!";
37fa004c 1010
55d729e4 1011 if (close(SENDMAIL)) {
105f9295 1012 printf "\nMessage %s.\n", $outfile ? "saved" : "sent";
55d729e4
GS
1013 } else {
1014 warn "\nSendmail returned status '", $? >> 8, "'\n";
1015 }
1016 }
1017 1 while unlink($filename); # remove all versions under VMS
1018} # sub Send
37fa004c
PP
1019
1020sub Help {
55d729e4 1021 print <<EOF;
37fa004c 1022
26ab4e07
RGS
1023A program to help generate bug reports about perl5, and mail them.
1024It is designed to be used interactively. Normally no arguments will
1025be needed.
55d729e4 1026
26ab4e07 1027Usage:
105f9295 1028$0 [-v] [-a address] [-s subject] [-b body | -f inpufile ] [ -F outputfile ]
d121ca8c 1029 [-r returnaddress] [-e editor] [-c adminaddress | -C] [-S] [-t] [-h]
890b8eb0 1030$0 [-v] [-r returnaddress] [-A] [-ok | -okay | -nok | -nokay]
55d729e4 1031
26ab4e07 1032Simplest usage: run "$0", and follow the prompts.
37fa004c
PP
1033
1034Options:
1035
1036 -v Include Verbose configuration data in the report
55d729e4 1037 -f File containing the body of the report. Use this to
37fa004c 1038 quickly send a prepared message.
1948c06a 1039 -F File to output the resulting mail message to, instead of mailing.
37fa004c 1040 -S Send without asking for confirmation.
c9967ac8
NC
1041 -a Address to send the report to. Defaults to '$address'.
1042 -c Address to send copy of report to. Defaults to '$cc'.
37fa004c 1043 -C Don't send copy to administrator.
55d729e4 1044 -s Subject to include with the message. You will be prompted
37fa004c
PP
1045 if you don't supply one on the command line.
1046 -b Body of the report. If not included on the command line, or
1047 in a file with -f, you will get a chance to edit the message.
1048 -r Your return address. The program will ask you to confirm
1049 this if you don't give it here.
55d729e4 1050 -e Editor to use.
c9967ac8
NC
1051 -t Test mode. The target address defaults to '$testaddress'.
1052 -T Thank-you mode. The target address defaults to '$thanksaddress'.
489b74f8 1053 -d Data mode. This prints out your configuration data, without mailing
c07a80fd 1054 anything. You can use this with -v to get more complete data.
890b8eb0 1055 -A Don't send a bug received acknowledgement to the return address.
84902520 1056 -ok Report successful build on this system to perl porters
55d729e4
GS
1057 (use alone or with -v). Only use -ok if *everything* was ok:
1058 if there were *any* problems at all, use -nok.
fb73857a 1059 -okay As -ok but allow report from old builds.
55d729e4
GS
1060 -nok Report unsuccessful build on this system to perl porters
1061 (use alone or with -v). You must describe what went wrong
1062 in the body of the report which you will be asked to edit.
1063 -nokay As -nok but allow report from old builds.
1064 -h Print this help message.
1065
37fa004c
PP
1066EOF
1067}
1068
55d729e4 1069sub filename {
003a92ef
NC
1070 if ($::HaveTemp) {
1071 # Good. Use a secure temp file
1072 my ($fh, $filename) = File::Temp::tempfile(UNLINK => 1);
1073 close($fh);
1074 return $filename;
1075 } else {
1076 # Bah. Fall back to doing things less securely.
1077 my $dir = File::Spec->tmpdir();
1078 $filename = "bugrep0$$";
1079 $filename++ while -e File::Spec->catfile($dir, $filename);
1080 $filename = File::Spec->catfile($dir, $filename);
1081 }
55d729e4
GS
1082}
1083
37fa004c
PP
1084sub paraprint {
1085 my @paragraphs = split /\n{2,}/, "@_";
26ab4e07 1086 print "\n\n";
37fa004c 1087 for (@paragraphs) { # implicit local $_
55d729e4
GS
1088 s/(\S)\s*\n/$1 /g;
1089 write;
1090 print "\n";
37fa004c 1091 }
37fa004c 1092}
37fa004c
PP
1093
1094format STDOUT =
1095^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~~
1096$_
1097.
d121ca8c
CS
1098
1099__END__
1100
1101=head1 NAME
1102
1103perlbug - how to submit bug reports on Perl
1104
1105=head1 SYNOPSIS
1106
1107B<perlbug> S<[ B<-v> ]> S<[ B<-a> I<address> ]> S<[ B<-s> I<subject> ]>
105f9295
HS
1108S<[ B<-b> I<body> | B<-f> I<inputfile> ]> S<[ B<-F> I<outputfile> ]>
1109S<[ B<-r> I<returnaddress> ]>
d121ca8c 1110S<[ B<-e> I<editor> ]> S<[ B<-c> I<adminaddress> | B<-C> ]>
890b8eb0 1111S<[ B<-S> ]> S<[ B<-t> ]> S<[ B<-d> ]> S<[ B<-A> ]> S<[ B<-h> ]>
d121ca8c 1112
55d729e4 1113B<perlbug> S<[ B<-v> ]> S<[ B<-r> I<returnaddress> ]>
890b8eb0 1114 S<[ B<-A> ]> S<[ B<-ok> | B<-okay> | B<-nok> | B<-nokay> ]>
1b0e3b9e 1115
d121ca8c
CS
1116=head1 DESCRIPTION
1117
26ab4e07
RGS
1118A program to help generate bug reports about perl or the modules that
1119come with it, and mail them.
d121ca8c 1120
26ab4e07
RGS
1121If you have found a bug with a non-standard port (one that was not part
1122of the I<standard distribution>), a binary distribution, or a
1123non-standard module (such as Tk, CGI, etc), then please see the
1124documentation that came with that distribution to determine the correct
1125place to report bugs.
d121ca8c 1126
26ab4e07
RGS
1127C<perlbug> is designed to be used interactively. Normally no arguments
1128will be needed. Simply run it, and follow the prompts.
d121ca8c 1129
26ab4e07
RGS
1130If you are unable to run B<perlbug> (most likely because you don't have
1131a working setup to send mail that perlbug recognizes), you may have to
1132compose your own report, and email it to B<perlbug@perl.org>. You might
1133find the B<-d> option useful to get summary information in that case.
d121ca8c 1134
26ab4e07
RGS
1135In any case, when reporting a bug, please make sure you have run through
1136this checklist:
d121ca8c
CS
1137
1138=over 4
1139
884baa66 1140=item What version of Perl you are running?
d121ca8c
CS
1141
1142Type C<perl -v> at the command line to find out.
1143
1144=item Are you running the latest released version of perl?
1145
26ab4e07
RGS
1146Look at http://www.perl.com/ to find out. If it is not the latest
1147released version, get that one and see whether your bug has been
1148fixed. Note that bug reports about old versions of Perl, especially
1149those prior to the 5.0 release, are likely to fall upon deaf ears.
1150You are on your own if you continue to use perl1 .. perl4.
d121ca8c
CS
1151
1152=item Are you sure what you have is a bug?
1153
26ab4e07
RGS
1154A significant number of the bug reports we get turn out to be documented
1155features in Perl. Make sure the behavior you are witnessing doesn't fall
1156under that category, by glancing through the documentation that comes
1157with Perl (we'll admit this is no mean task, given the sheer volume of
1158it all, but at least have a look at the sections that I<seem> relevant).
d121ca8c 1159
26ab4e07
RGS
1160Be aware of the familiar traps that perl programmers of various hues
1161fall into. See L<perltrap>.
d121ca8c 1162
26ab4e07
RGS
1163Check in L<perldiag> to see what any Perl error message(s) mean.
1164If message isn't in perldiag, it probably isn't generated by Perl.
1165Consult your operating system documentation instead.
bdcdfa19 1166
26ab4e07 1167If you are on a non-UNIX platform check also L<perlport>, as some
1948c06a 1168features may be unimplemented or work differently.
bdcdfa19 1169
26ab4e07
RGS
1170Try to study the problem under the Perl debugger, if necessary.
1171See L<perldebug>.
d121ca8c
CS
1172
1173=item Do you have a proper test case?
1174
1175The easier it is to reproduce your bug, the more likely it will be
26ab4e07
RGS
1176fixed, because if no one can duplicate the problem, no one can fix it.
1177A good test case has most of these attributes: fewest possible number
1178of lines; few dependencies on external commands, modules, or
1179libraries; runs on most platforms unimpeded; and is self-documenting.
d121ca8c 1180
26ab4e07
RGS
1181A good test case is almost always a good candidate to be on the perl
1182test suite. If you have the time, consider making your test case so
1183that it will readily fit into the standard test suite.
d121ca8c 1184
26ab4e07
RGS
1185Remember also to include the B<exact> error messages, if any.
1186"Perl complained something" is not an exact error message.
bdcdfa19
JH
1187
1188If you get a core dump (or equivalent), you may use a debugger
1189(B<dbx>, B<gdb>, etc) to produce a stack trace to include in the bug
26ab4e07 1190report. NOTE: unless your Perl has been compiled with debug info
bdcdfa19 1191(often B<-g>), the stack trace is likely to be somewhat hard to use
884baa66 1192because it will most probably contain only the function names and not
bdcdfa19 1193their arguments. If possible, recompile your Perl with debug info and
26ab4e07 1194reproduce the dump and the stack trace.
bdcdfa19 1195
d121ca8c
CS
1196=item Can you describe the bug in plain English?
1197
26ab4e07
RGS
1198The easier it is to understand a reproducible bug, the more likely it
1199will be fixed. Anything you can provide by way of insight into the
1200problem helps a great deal. In other words, try to analyze the
1201problem (to the extent you can) and report your discoveries.
d121ca8c
CS
1202
1203=item Can you fix the bug yourself?
1204
1205A bug report which I<includes a patch to fix it> will almost
26ab4e07
RGS
1206definitely be fixed. Use the C<diff> program to generate your patches
1207(C<diff> is being maintained by the GNU folks as part of the B<diffutils>
1208package, so you should be able to get it from any of the GNU software
1209repositories). If you do submit a patch, the cool-dude counter at
1210perlbug@perl.org will register you as a savior of the world. Your
1211patch may be returned with requests for changes, or requests for more
d121ca8c
CS
1212detailed explanations about your fix.
1213
26ab4e07
RGS
1214Here are some clues for creating quality patches: Use the B<-c> or
1215B<-u> switches to the diff program (to create a so-called context or
1216unified diff). Make sure the patch is not reversed (the first
1217argument to diff is typically the original file, the second argument
1218your changed file). Make sure you test your patch by applying it with
1219the C<patch> program before you send it on its way. Try to follow the
1220same style as the code you are trying to patch. Make sure your patch
1221really does work (C<make test>, if the thing you're patching supports
1222it).
d121ca8c
CS
1223
1224=item Can you use C<perlbug> to submit the report?
1225
1226B<perlbug> will, amongst other things, ensure your report includes
26ab4e07
RGS
1227crucial information about your version of perl. If C<perlbug> is unable
1228to mail your report after you have typed it in, you may have to compose
1229the message yourself, add the output produced by C<perlbug -d> and email
1230it to B<perlbug@perl.org>. If, for some reason, you cannot run
1231C<perlbug> at all on your system, be sure to include the entire output
1232produced by running C<perl -V> (note the uppercase V).
d121ca8c 1233
bdcdfa19 1234Whether you use C<perlbug> or send the email manually, please make
26ab4e07
RGS
1235your Subject line informative. "a bug" not informative. Neither is
1236"perl crashes" nor "HELP!!!". These don't help.
1237A compact description of what's wrong is fine.
bdcdfa19 1238
d121ca8c
CS
1239=back
1240
1241Having done your bit, please be prepared to wait, to be told the bug
26ab4e07
RGS
1242is in your code, or even to get no reply at all. The Perl maintainers
1243are busy folks, so if your problem is a small one or if it is difficult
1244to understand or already known, they may not respond with a personal reply.
1245If it is important to you that your bug be fixed, do monitor the
1246C<Changes> file in any development releases since the time you submitted
1247the bug, and encourage the maintainers with kind words (but never any
1248flames!). Feel free to resend your bug report if the next released
1249version of perl comes out and your bug is still present.
d121ca8c
CS
1250
1251=head1 OPTIONS
1252
1253=over 8
1254
1255=item B<-a>
1256
3e79b69b 1257Address to send the report to. Defaults to B<perlbug@perl.org>.
d121ca8c 1258
890b8eb0
NC
1259=item B<-A>
1260
1261Don't send a bug received acknowledgement to the reply address.
1262Generally it is only a sensible to use this option if you are a
1263perl maintainer actively watching perl porters for your message to
1264arrive.
1265
d121ca8c
CS
1266=item B<-b>
1267
1268Body of the report. If not included on the command line, or
1269in a file with B<-f>, you will get a chance to edit the message.
1270
1271=item B<-C>
1272
1273Don't send copy to administrator.
1274
1275=item B<-c>
1276
1277Address to send copy of report to. Defaults to the address of the
1278local perl administrator (recorded when perl was built).
1279
1280=item B<-d>
1281
1282Data mode (the default if you redirect or pipe output). This prints out
1283your configuration data, without mailing anything. You can use this
1284with B<-v> to get more complete data.
1285
1286=item B<-e>
1287
55d729e4 1288Editor to use.
d121ca8c
CS
1289
1290=item B<-f>
1291
1292File containing the body of the report. Use this to quickly send a
1293prepared message.
1294
105f9295
HS
1295=item B<-F>
1296
1297File to output the results to instead of sending as an email. Useful
1298particularly when running perlbug on a machine with no direct internet
1299connection.
1300
d121ca8c
CS
1301=item B<-h>
1302
1303Prints a brief summary of the options.
1304
1b0e3b9e
CR
1305=item B<-ok>
1306
84902520
TB
1307Report successful build on this system to perl porters. Forces B<-S>
1308and B<-C>. Forces and supplies values for B<-s> and B<-b>. Only
1b0e3b9e 1309prompts for a return address if it cannot guess it (for use with
84902520
TB
1310B<make>). Honors return address specified with B<-r>. You can use this
1311with B<-v> to get more complete data. Only makes a report if this
1312system is less than 60 days old.
1313
1314=item B<-okay>
1315
1316As B<-ok> except it will report on older systems.
1b0e3b9e 1317
55d729e4
GS
1318=item B<-nok>
1319
1320Report unsuccessful build on this system. Forces B<-C>. Forces and
1321supplies a value for B<-s>, then requires you to edit the report
1322and say what went wrong. Alternatively, a prepared report may be
1323supplied using B<-f>. Only prompts for a return address if it
1324cannot guess it (for use with B<make>). Honors return address
1325specified with B<-r>. You can use this with B<-v> to get more
1326complete data. Only makes a report if this system is less than 60
1327days old.
1328
1329=item B<-nokay>
1330
1331As B<-nok> except it will report on older systems.
1332
d121ca8c
CS
1333=item B<-r>
1334
1335Your return address. The program will ask you to confirm its default
1336if you don't use this option.
1337
1338=item B<-S>
1339
1340Send without asking for confirmation.
1341
1342=item B<-s>
1343
1344Subject to include with the message. You will be prompted if you don't
1345supply one on the command line.
1346
1347=item B<-t>
1348
3e79b69b 1349Test mode. The target address defaults to B<perlbug-test@perl.org>.
d121ca8c
CS
1350
1351=item B<-v>
1352
1353Include verbose configuration data in the report.
1354
1355=back
1356
1357=head1 AUTHORS
1358
26ab4e07
RGS
1359Kenneth Albanowski (E<lt>kjahds@kjahds.comE<gt>), subsequently I<doc>tored
1360by Gurusamy Sarathy (E<lt>gsar@activestate.comE<gt>), Tom Christiansen
1361(E<lt>tchrist@perl.comE<gt>), Nathan Torkington (E<lt>gnat@frii.comE<gt>),
1362Charles F. Randall (E<lt>cfr@pobox.comE<gt>), Mike Guy
1363(E<lt>mjtg@cam.a.ukE<gt>), Dominic Dunlop (E<lt>domo@computer.orgE<gt>),
1364Hugo van der Sanden (E<lt>hv@crypt.org<gt>),
50d3c28b
GS
1365Jarkko Hietaniemi (E<lt>jhi@iki.fiE<gt>), Chris Nandor
1366(E<lt>pudge@pobox.comE<gt>), Jon Orwant (E<lt>orwant@media.mit.eduE<gt>,
26ab4e07 1367and Richard Foley (E<lt>richard@rfi.netE<gt>).
d121ca8c
CS
1368
1369=head1 SEE ALSO
1370
bdcdfa19
JH
1371perl(1), perldebug(1), perldiag(1), perlport(1), perltrap(1),
1372diff(1), patch(1), dbx(1), gdb(1)
d121ca8c
CS
1373
1374=head1 BUGS
1375
1376None known (guess what must have been used to report them?)
1377
1378=cut
1379
37fa004c
PP
1380!NO!SUBS!
1381
1382close OUT or die "Can't close $file: $!";
1383chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
1384exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
8a5546a1 1385chdir $origdir;