4 use File::Basename qw(&basename &dirname);
6 use File::Spec::Functions;
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
13 # to ensure Configure will look for $Config{startperl}.
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.
20 $file = basename($0, '.PL');
21 $file .= '.com' if $^O eq 'VMS';
23 open OUT, ">$file" or die "Can't create $file: $!";
25 # extract patchlevel.h information
27 open PATCH_LEVEL, "<" . catfile(updir, "patchlevel.h")
28 or die "Can't open patchlevel.h: $!";
30 my $patchlevel_date = (stat PATCH_LEVEL)[9];
32 while (<PATCH_LEVEL>) {
33 last if $_ =~ /^\s*static\s+(?:const\s+)?char.*?local_patches\[\]\s*=\s*{\s*$/;
37 warn "Warning: local_patches section not found in patchlevel.h\n";
41 while (<PATCH_LEVEL>) {
43 next if /^\s*#/; # preprocessor stuff
48 push @patches, $_ unless $_ eq 'NULL';
50 my $patch_desc = "'" . join("',\n '", @patches) . "'";
51 my $patch_tags = join "", map /(\S+)/ ? "+$1 " : (), @patches;
53 close(PATCH_LEVEL) or die "Error closing patchlevel.h: $!";
55 # TO DO (prehaps): store/embed $Config::config_sh into perlbug. When perlbug is
56 # used, compare $Config::config_sh with the stored version. If they differ then
57 # append a list of individual differences to the bug report.
60 print "Extracting $file (with variable substitutions)\n";
62 # In this section, perl variables will be expanded during extraction.
63 # You can use $Config{...} to use Configure variables.
65 my $extract_version = sprintf("%vd", $^V);
67 print OUT <<"!GROK!THIS!";
69 eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}'
70 if \$running_under_some_shell;
72 my \$config_tag1 = '$extract_version - $Config{cf_time}';
74 my \$patchlevel_date = $patchlevel_date;
75 my \$patch_tags = '$patch_tags';
81 # In the following, perl variables are not expanded during extraction.
83 print OUT <<'!NO!SUBS!';
86 no warnings 'once'; # Eventually, the $::opt_ stuff should get cleaned up
89 use File::Spec; # keep perlbug Perl 5.005 compatible
91 use File::Basename 'basename';
96 eval { require Mail::Send;};
97 $::HaveSend = ($@ eq "");
98 eval { require Mail::Util; } ;
99 $::HaveUtil = ($@ eq "");
100 # use secure tempfiles wherever possible
101 eval { require File::Temp; };
102 $::HaveTemp = ($@ eq "");
103 eval { require Module::CoreList; };
104 $::HaveCoreList = ($@ eq "");
107 my $Version = "1.39";
109 # Changed in 1.06 to skip Mail::Send and Mail::Util if not available.
110 # Changed in 1.07 to see more sendmail execs, and added pipe output.
111 # Changed in 1.08 to use correct address for sendmail.
112 # Changed in 1.09 to close the REP file before calling it up in the editor.
113 # Also removed some old comments duplicated elsewhere.
114 # Changed in 1.10 to run under VMS without Mail::Send; also fixed
115 # temp filename generation.
116 # Changed in 1.11 to clean up some text and removed Mail::Send deactivator.
117 # Changed in 1.12 to check for editor errors, make save/send distinction
118 # clearer and add $ENV{REPLYTO}.
119 # Changed in 1.13 to hopefully make it more difficult to accidentally
121 # Changed in 1.14 to make the prompts a little more clear on providing
122 # helpful information. Also let file read fail gracefully.
123 # Changed in 1.15 to add warnings to stop people using perlbug for non-bugs.
124 # Also report selected environment variables.
125 # Changed in 1.16 to include @INC, and allow user to re-edit if no changes.
126 # Changed in 1.17 Win32 support added. GSAR 97-04-12
127 # Changed in 1.18 add '-ok' option for reporting build success. CFR 97-06-18
128 # Changed in 1.19 '-ok' default not '-v'
129 # add local patch information
130 # warn on '-ok' if this is an old system; add '-okay'
131 # Changed in 1.20 Added patchlevel.h reading and version/config checks
132 # Changed in 1.21 Added '-nok' for reporting build failure DFD 98-05-05
133 # Changed in 1.22 Heavy reformatting & minor bugfixes HVDS 98-05-10
134 # Changed in 1.23 Restore -ok(ay): say 'success'; don't prompt
135 # Changed in 1.24 Added '-F<file>' to save report HVDS 98-07-01
136 # Changed in 1.25 Warn on failure to open save file. HVDS 98-07-12
137 # Changed in 1.26 Don't require -t STDIN for -ok. HVDS 98-07-15
138 # Changed in 1.27 Added Mac OS and File::Spec support CNANDOR 99-07-27
139 # Changed in 1.28 Additional questions for Perlbugtron RFOLEY 20.03.2000
140 # Changed in 1.29 Perlbug(tron): auto(-ok), short prompts RFOLEY 05-05-2000
141 # Changed in 1.30 Added warnings on failure to open files MSTEVENS 13-07-2000
142 # Changed in 1.31 Add checks on close().Fix my $var unless. TJENNESS 26-07-2000
143 # Changed in 1.32 Use File::Spec->tmpdir TJENNESS 20-08-2000
144 # Changed in 1.33 Don't require -t STDOUT for -ok.
145 # Changed in 1.34 Added Message-Id RFOLEY 18-06-2002
146 # Changed in 1.35 Use File::Temp (patch from Solar Designer) NWCLARK 28-02-2004
147 # Changed in 1.36 Initial Module::CoreList support Alexandr Ciornii 11-07-2007
148 # Changed in 1.37 Killed some string evals, rewrote most prose JESSE 2008-06-08
149 # Changed in 1.38 Actually enforce the CoreList check,
150 # Record the module the user enters if they do so
151 # Refactor prompts to use common code JESSE 2008-06-08
152 # Changed in 1.39 Trap mail sending failures (simple ones) so JESSE 2008-06-08
153 # users might be able to recover their bug reports
154 # Refactor mail sending routines
155 # Unify message building code
156 # Unify message header building
157 # Fix "module" prompting to not squish "category" prompting
158 # use warnings; (except 'once' warnings)
159 # Unified report fingerprint/change detection code
160 # Removed some labeled 'gotos'
162 # make sure failure (transmission-wise) of Mail::Send is accounted for.
163 # (This may work now. Unsure of the original author's issue -JESSE 2008-06-08)
166 my( $file, $usefile, $cc, $address, $bugaddress, $testaddress, $thanksaddress,
167 $filename, $messageid, $domain, $subject, $from, $verbose, $ed, $outfile,
168 $fh, $me, $body, $andcc, %REP, $ok, $thanks, $progname,
169 $Is_MacOS, $Is_MSWin32, $Is_Linux, $Is_VMS, $Is_OpenBSD,
170 $report_about_module, $category, $severity,
174 my $perl_version = $^V ? sprintf("%vd", $^V) : $];
176 my $config_tag2 = "$perl_version - $Config{cf_time}";
180 if ($::opt_h) { Help(); exit; }
181 if ($::opt_d) { Dump(*STDOUT); exit; }
182 if (!-t STDIN && !($ok and not $::opt_n)) {
184 Please use $progname interactively. If you want to
185 include a file, you can use the -f switch.
191 Edit() unless $usefile || ($ok and not $::opt_n);
194 save_message_to_disk($outfile);
198 print "\nThank you for taking the time to send a thank-you message!\n\n";
200 print "\nThank you for taking the time to file a bug report!\n\n";
206 sub ask_for_alternatives { # (category|severity)
212 # Inevitably some of these will end up in RT whatever we do:
213 'thanks' => 'thanks',
214 'opts' => [qw(core docs install library utilities)], # patch, notabug
220 'opts' => [qw(critical high medium low wishlist none)], # zero
223 die "Invalid alternative ($name) requested\n" unless grep(/^$name$/, keys %alts);
225 my $what = $ok || $thanks;
227 $alt = $alts{$name}{$what};
229 my @alts = @{$alts{$name}{'opts'}};
232 Please pick a $name from the following list:
239 die "Invalid $name: aborting.\n";
241 $alt = _prompt('', "\u$name", $alts{$name}{'default'});
242 $alt ||= $alts{$name}{'default'};
243 } while !((($alt) = grep(/^$alt/i, @alts)));
249 # -------- Setup --------
251 $Is_MSWin32 = $^O eq 'MSWin32';
252 $Is_VMS = $^O eq 'VMS';
253 $Is_Linux = lc($^O) eq 'linux';
254 $Is_OpenBSD = lc($^O) eq 'openbsd';
255 $Is_MacOS = $^O eq 'MacOS';
257 @ARGV = split m/\s+/,
258 MacPerl::Ask('Provide command line args here (-h for help):')
259 if $Is_MacOS && $MacPerl::Version =~ /App/;
261 if (!getopts("Adhva:s:b:f:F:r:e:SCc:to:n:T")) { Help(); exit; };
263 # This comment is needed to notify metaconfig that we are
264 # using the $perladmin, $cf_by, and $cf_time definitions.
266 # -------- Configuration ---------
269 $bugaddress = 'perlbug@perl.org';
272 $testaddress = 'perlbug-test@perl.org';
275 $thanksaddress = 'perl-thanks@perl.org';
277 if (basename ($0) =~ /^perlthanks/i) {
278 # invoked as perlthanks
280 $::opt_C = 1; # don't send a copy to the local admin
287 $progname = $thanks ? 'perlthanks' : 'perlbug';
289 $address = $::opt_a || ($::opt_t ? $testaddress
290 : $thanks ? $thanksaddress : $bugaddress);
292 # Users address, used in message and in Reply-To header
293 $from = $::opt_r || "";
295 # Include verbose configuration information
296 $verbose = $::opt_v || 0;
298 # Subject of bug-report message
299 $subject = $::opt_s || "";
302 $usefile = ($::opt_f || 0);
304 # File to send as report
305 $file = $::opt_f || "";
308 $outfile = $::opt_F || "";
311 $body = $::opt_b || "";
314 $ed = $::opt_e || $ENV{VISUAL} || $ENV{EDITOR} || $ENV{EDIT}
315 || ($Is_VMS && "edit/tpu")
316 || ($Is_MSWin32 && "notepad")
320 # Not OK - provide build failure template by finessing OK report
322 if (substr($::opt_n, 0, 2) eq 'ok' ) {
323 $::opt_o = substr($::opt_n, 1);
330 # OK - send "OK" report for build on this system
333 if ($::opt_o eq 'k' or $::opt_o eq 'kay') {
334 my $age = time - $patchlevel_date;
335 if ($::opt_o eq 'k' and $age > 60 * 24 * 60 * 60 ) {
336 my $date = localtime $patchlevel_date;
338 "perlbug -ok" and "perlbug -nok" do not report on Perl versions which
339 are more than 60 days old. This Perl version was constructed on
340 $date. If you really want to report this, use
341 "perlbug -okay" or "perlbug -nokay".
345 # force these options
347 $::opt_S = 1; # don't prompt for send
348 $::opt_b = 1; # we have a body
349 $body = "Perl reported to build OK on this system.\n";
351 $::opt_C = 1; # don't send a copy to the local admin
352 $::opt_s = 1; # we have a subject line
353 $subject = ($::opt_n ? 'Not ' : '')
354 . "OK: perl $perl_version ${patch_tags}on"
355 ." $::Config{'archname'} $::Config{'osvers'} $subject";
363 # Possible administrator addresses, in order of confidence
364 # (Note that cf_email is not mentioned to metaconfig, since
365 # we don't really want it. We'll just take it if we have to.)
367 # This has to be after the $ok stuff above because of the way
368 # that $::opt_C is forced.
369 $cc = $::opt_C ? "" : (
370 $::opt_c || $::Config{'perladmin'}
371 || $::Config{'cf_email'} || $::Config{'cf_by'}
375 $domain = Mail::Util::maildomain();
376 } elsif ($Is_MSWin32) {
377 $domain = $ENV{'USERDOMAIN'};
379 require Sys::Hostname;
380 $domain = Sys::Hostname::hostname();
384 $messageid = "<$::Config{'version'}_${$}_".time."\@$domain>";
387 $me = $Is_MSWin32 ? $ENV{'USERNAME'}
388 : $^O eq 'os2' ? $ENV{'USER'} || $ENV{'LOGNAME'}
389 : $Is_MacOS ? $ENV{'USER'}
390 : eval { getpwuid($<) }; # May be missing
392 $from = $::Config{'cf_email'}
393 if !$from && $::Config{'cf_email'} && $::Config{'cf_by'} && $me &&
394 ($me eq $::Config{'cf_by'});
398 # Explain what perlbug is
402 This program provides an easy way to send a thank-you message back to the
403 authors and maintainers of perl.
405 If you wish to submit a bug report, please run it without the -T flag
406 (or run the program perlbug rather than perlthanks)
410 This program provides an easy way to create a message reporting a
411 bug in the core perl distribution (along with tests or patches)
412 to the volunteers who maintain perl at $address. To send a thank-you
413 note to $thanksaddress instead of a bug report, please run 'perlthanks'.
415 Please do not use $0 to send test messages, test whether perl
416 works, or to report bugs in perl modules from CPAN.
418 For help using perl, try posting to the Usenet newsgroup
424 # Prompt for subject of message, if needed
426 if ($subject && TrivialSubject($subject)) {
432 "First of all, please provide a subject for the message.\n";
435 This should be a concise description of your bug or problem
436 which will help the volunteers working to improve perl to categorize
437 and resolve the issue. Be as specific and descriptive as
438 you can. A subject like "perl bug" or "perl problem" will make it
439 much less likely that your issue gets the attention it deserves.
445 $subject = _prompt('','Subject');
448 $subject = 'Thanks for Perl';
453 } while (TrivialSubject($subject));
456 # Prompt for return address, if needed
458 # Try and guess return address
461 $guess = $ENV{'REPLY-TO'} || $ENV{'REPLYTO'} || '';
463 require Mac::InternetConfig;
464 $guess = $Mac::InternetConfig::InternetConfig{
465 Mac::InternetConfig::kICEmail()
470 # move $domain to where we can use it elsewhere
472 if ($Is_VMS && !$::Config{'d_socket'}) {
473 $guess = "$domain\:\:$me";
475 $guess = "$me\@$domain" if $domain;
483 Perl's developers may need your email address to contact you for
484 further information about your issue or to inform you when it is
485 resolved. If the default shown is not your email address, please
491 Please enter your full internet email address so that Perl's
492 developers can contact you with questions about your issue or to
493 inform you that it has been resolved.
502 $from = _prompt('','Your address',$guess);
503 $from = $guess if $from eq '';
507 if ($from eq $cc or $me eq $cc) {
508 # Try not to copy ourselves
512 # Prompt for administrator address, unless an override was given
513 if( !$::opt_C and !$::opt_c ) {
514 my $description = <<EOF;
515 $0 can send a copy of this report to your local perl
516 administrator. If the address below is wrong, please correct it,
517 or enter 'none' or 'yourself' to not send a copy.
519 my $entry = _prompt($description, "Local perl administrator", $cc);
523 $cc = '' if $me eq $cc;
527 $cc = '' if $cc =~ /^(none|yourself|me|myself|ourselves)$/i;
534 # Prompt for editor, if no override is given
536 unless ($::opt_e || $::opt_f || $::opt_b) {
540 chomp (my $common_end = <<"EOF");
541 You will probably want to use a text editor to enter the body of
542 your report. If "$ed" is the editor you want to use, then just press
543 Enter, otherwise type in the name of the editor you would like to
546 If you have already composed the body of your report, you may enter
547 "file", and $0 will prompt you to enter the name of the file
548 containing your report.
552 $description = <<"EOF";
553 It's now time to compose your thank-you message.
555 Some information about your local perl configuration will automatically
556 be included at the end of your message, because we're curious about
557 the different ways that people build and use perl. If you'd rather
558 not share this information, you're welcome to delete it.
563 $description = <<"EOF";
564 It's now time to compose your bug report. Try to make the report
565 concise but descriptive. Please include any detail which you think
566 might be relevant or might help the volunteers working to improve
567 perl. If you are reporting something that does not work as you think
568 it should, please try to include examples of the actual result and of
571 Some information about your local perl configuration will automatically
572 be included at the end of your report. If you are using an unusual
573 version of perl, it would be useful if you could confirm that you
574 can replicate the problem on a standard build of perl as well.
580 my $entry = _prompt($description, "Editor", $ed);
582 if ($entry eq "file") {
584 } elsif ($entry ne "") {
588 if ($::HaveCoreList && !$ok && !$thanks) {
589 my $description = <<EOF;
590 If your bug is about a Perl module rather than a core language
591 feature, please enter its name here. If it's not, just hit Enter
592 to skip this question.
596 while ($entry eq '') {
597 $entry = _prompt($description, 'Module');
598 my $first_release = Module::CoreList->first_release($entry);
599 if ($entry and not $first_release) {
601 $entry is not a "core" Perl module. Please check that you entered
602 its name correctly. If it is correct, quit this program, try searching
603 for $entry on http://rt.cpan.org, and report your issue there.
607 } elsif (my $bug_tracker = $Module::CoreList::bug_tracker{$entry}) {
609 $entry included with core Perl is copied directly from the CPAN distribution.
610 Please report bugs in $entry directly to its maintainers using $bug_tracker
614 $category ||= 'library';
615 $report_about_module = $entry;
623 # Prompt for category of bug
624 $category ||= ask_for_alternatives('category');
626 # Prompt for severity of bug
627 $severity ||= ask_for_alternatives('severity');
629 # Generate scratch file to edit report in
630 $filename = filename();
632 # Prompt for file to read report from, if needed
633 if ($usefile and !$file) {
635 my $description = <<EOF;
636 What is the name of the file that contains your report?
638 my $entry = _prompt($description, "Filename");
642 It seems you didn't enter a filename. Please choose to use a text
643 editor or enter a filename.
648 unless (-f $entry and -r $entry) {
650 '$entry' doesn't seem to be a readable file. You may have mistyped
651 its name or may not have permission to read it.
653 If you don't want to use a file as the content of your report, just
654 hit Enter and you'll be able to select a text editor instead.
662 open(REP,">$filename") or die "Unable to create report file '$filename': $!\n";
663 my $reptype = !$ok ? ($thanks ? 'thank-you' : 'bug')
664 : $::opt_n ? "build failure" : "success";
667 This is a $reptype report for perl from $from,
668 generated with the help of perlbug $Version running under perl $perl_version.
676 or die "Unable to read report file from '$file': $!\n";
680 close(F) or die "Error closing '$file': $!";
685 -----------------------------------------------------------------
686 [Please enter your thank-you message here]
690 [You're welcome to delete anything below this line]
691 -----------------------------------------------------------------
696 -----------------------------------------------------------------
697 [Please describe your issue here]
701 [Please do not change anything below this line]
702 -----------------------------------------------------------------
707 close(REP) or die "Error closing report file: $!";
709 # Set up an initial report fingerprint so we can compare it later
710 _fingerprint_lines_in_report();
724 if ($report_about_module ) {
726 module=$report_about_module
737 print OUT "This perlbug was built using Perl $config_tag1\n",
738 "It is being executed now by Perl $config_tag2.\n\n"
739 if $config_tag2 ne $config_tag1;
742 Site configuration information for perl $perl_version:
745 if ($::Config{cf_by} and $::Config{cf_time}) {
746 print OUT "Configured by $::Config{cf_by} at $::Config{cf_time}.\n\n";
748 print OUT Config::myconfig;
751 print OUT join "\n ", "Locally applied patches:", @patches;
758 \@INC for perl $perl_version:
767 Environment for perl $perl_version:
770 qw(PATH LD_LIBRARY_PATH LANG PERL_BADLANG SHELL HOME LOGDIR LANGUAGE);
771 push @env, $Config{ldlibpthname} if $Config{ldlibpthname} ne '';
772 push @env, grep /^(?:PERL|LC_|LANG|CYGWIN)/, keys %ENV;
775 for my $env (sort keys %env) {
777 exists $ENV{$env} ? "=$ENV{$env}" : ' (unset)',
781 print OUT "\nComplete configuration data for perl $perl_version:\n\n";
783 foreach (sort keys %::Config) {
784 $value = $::Config{$_};
786 print OUT "$_='$value'\n";
793 if ($usefile || $body) {
794 my $description = "Please make sure that the name of the editor you want to use is correct.";
795 my $entry = _prompt($description, 'Editor', $ed);
796 $ed = $entry unless $entry eq '';
805 my $report_written = 0;
807 while ( !$report_written ) {
809 require ExtUtils::MakeMaker;
810 ExtUtils::MM_MacOS::launch_file($filename);
811 _prompt('', "Press Enter when done." );
812 } else { # we're not on oldschool mac os
813 my $exit_status = system("$editor $filename");
816 The editor you chose ('$editor') could not be run!
818 If you mistyped its name, please enter it now, otherwise just press Enter.
820 my $entry = _prompt( $desc, 'Editor', $editor );
821 if ( $entry ne "" ) {
826 You may want to save your report to a file, so you can edit and
833 return if ( $ok and not $::opt_n ) || $body;
835 # Check that we have a report that has some, eh, report in it.
837 unless ( _fingerprint_lines_in_report() ) {
838 my $description = <<EOF;
839 It looks like you didn't enter a report. You may [r]etry your edit
840 or [c]ancel this report.
842 my $action = _prompt( $description, "Action (Retry/Cancel) " );
843 if ( $action =~ /^[re]/i ) { # <R>etry <E>dit
845 } elsif ( $action =~ /^[cq]/i ) { # <C>ancel, <Q>uit
846 Cancel(); # cancel exits
849 # Ok. the user did what they needed to;
857 1 while unlink($filename); # remove all versions under VMS
858 print "\nQuitting without sending your message.\n";
863 # Report is done, prompt for further action
869 You have finished composing your message. At this point, you have
870 a few options. You can:
872 * [Se]end the message to $address$andcc,
873 * [D]isplay the message on the screen,
874 * [R]e-edit the message
875 * Display or change the message's [su]bject
876 * Save the message to a [f]ile to mail at another time
877 * [Q]uit without sending a message
882 my $action = _prompt('', "Action (Send/Display/Edit/Subject/Save to File)");;
884 if ($action =~ /^(f|sa)/i) { # <F>ile/<Sa>ve
885 if ( SaveMessage() ) { exit }
886 } elsif ($action =~ /^(d|l|sh)/i ) { # <D>isplay, <L>ist, <Sh>ow
887 # Display the message
888 open(REP, "<$filename") or die "Couldn't open file '$filename': $!\n";
889 while (<REP>) { print $_ }
890 close(REP) or die "Error closing report file '$filename': $!";
891 } elsif ($action =~ /^su/i) { # <Su>bject
892 my $reply = _prompt( "Subject: $subject", "If the above subject is fine, press Enter. Otherwise, type a replacement now\nSubject");
894 unless (TrivialSubject($reply)) {
896 print "Subject: $subject\n";
899 } elsif ($action =~ /^se/i) { # <S>end
901 my $reply = _prompt( "Are you certain you want to send this message?", 'Please type "yes" if you are','no');
902 if ($reply =~ /^yes$/) {
906 You didn't type "yes", so your message has not yet been sent.
909 } elsif ($action =~ /^[er]/i) { # <E>dit, <R>e-edit
912 } elsif ($action =~ /^[qc]/i) { # <C>ancel, <Q>uit
914 } elsif ($action =~ /^s/i) {
916 The command you entered was ambiguous. Please type "send", "save" or "subject".
926 /^(y(es)?|no?|help|perl( (bug|problem))?|bug|problem)$/i ||
927 length($subject) < 4 ||
929 print "\nThe subject you entered wasn't very descriptive. Please try again.\n\n";
937 my $file_save = $outfile || "$progname.rep";
938 my $file = _prompt( '', "Name of file to save message in", $file_save );
939 save_message_to_disk($file) || return undef;
942 A copy of your message has been saved in '$file' for you to
943 send to '$address' with your normal mail client.
949 # Message has been accepted for transmission -- Send the message
951 # on linux certain "mail" implementations won't accept the subject
952 # as "~s subject" and thus the Subject header will be corrupted
953 # so don't use Mail::Send to be safe
955 if ( $::HaveSend && !$Is_Linux && !$Is_OpenBSD ) {
956 _send_message_mailsend();
960 _send_message_sendmail();
964 if ( my $error = $@ ) {
966 $0 has detected an error while trying to send your message: $error.
968 Your message may not have been sent. You will now have a chance to save a copy to disk.
974 1 while unlink($filename); # remove all versions under VMS
980 This program is designed to help you generate and send bug reports
981 (and thank-you notes) about perl5 and the modules which ship with it.
983 In most cases, you can just run "$0" interactively from a command
984 line without any special arguments and follow the prompts.
988 $0 [-v] [-a address] [-s subject] [-b body | -f inpufile ] [ -F outputfile ]
989 [-r returnaddress] [-e editor] [-c adminaddress | -C] [-S] [-t] [-h]
990 $0 [-v] [-r returnaddress] [-A] [-ok | -okay | -nok | -nokay]
995 -v Include Verbose configuration data in the report
996 -f File containing the body of the report. Use this to
997 quickly send a prepared message.
998 -F File to output the resulting mail message to, instead of mailing.
999 -S Send without asking for confirmation.
1000 -a Address to send the report to. Defaults to '$address'.
1001 -c Address to send copy of report to. Defaults to '$cc'.
1002 -C Don't send copy to administrator.
1003 -s Subject to include with the message. You will be prompted
1004 if you don't supply one on the command line.
1005 -b Body of the report. If not included on the command line, or
1006 in a file with -f, you will get a chance to edit the message.
1007 -r Your return address. The program will ask you to confirm
1008 this if you don't give it here.
1010 -t Test mode. The target address defaults to '$testaddress'.
1011 -T Thank-you mode. The target address defaults to '$thanksaddress'.
1012 -d Data mode. This prints out your configuration data, without mailing
1013 anything. You can use this with -v to get more complete data.
1014 -A Don't send a bug received acknowledgement to the return address.
1015 -ok Report successful build on this system to perl porters
1016 (use alone or with -v). Only use -ok if *everything* was ok:
1017 if there were *any* problems at all, use -nok.
1018 -okay As -ok but allow report from old builds.
1019 -nok Report unsuccessful build on this system to perl porters
1020 (use alone or with -v). You must describe what went wrong
1021 in the body of the report which you will be asked to edit.
1022 -nokay As -nok but allow report from old builds.
1023 -h Print this help message.
1030 # Good. Use a secure temp file
1031 my ($fh, $filename) = File::Temp::tempfile(UNLINK => 1);
1035 # Bah. Fall back to doing things less securely.
1036 my $dir = File::Spec->tmpdir();
1037 $filename = "bugrep0$$";
1038 $filename++ while -e File::Spec->catfile($dir, $filename);
1039 $filename = File::Spec->catfile($dir, $filename);
1044 my @paragraphs = split /\n{2,}/, "@_";
1045 for (@paragraphs) { # implicit local $_
1053 my ($explanation, $prompt, $default) = (@_);
1056 paraprint $explanation;
1058 print $prompt. ($default ? " [$default]" :''). ": ";
1059 my $result = scalar(<>);
1061 $result =~ s/^\s*(.*?)\s*$/$1/s;
1062 if ($default && $result eq '') {
1073 for my $header (keys %attr) {
1074 $head .= "$header: ".$attr{$header}."\n";
1079 sub _message_headers {
1080 my %headers = ( To => $address, Subject => $subject );
1081 $headers{'Cc'} = $cc if ($cc);
1082 $headers{'Message-Id'} = $messageid if ($messageid);
1083 $headers{'Reply-To'} = $from if ($from);
1087 sub build_complete_message {
1088 my $content = _build_header(%{_message_headers()}) . "\n\n";
1089 open( REP, "<$filename" ) or die "Couldn't open file '$filename': $!\n";
1090 while (<REP>) { $content .= $_; }
1091 close(REP) or die "Error closing report file '$filename': $!";
1095 sub save_message_to_disk {
1098 open OUTFILE, ">$file" or do { warn "Couldn't open '$file': $!\n"; return undef};
1099 print OUTFILE build_complete_message();
1100 close(OUTFILE) or do { warn "Error closing $file: $!"; return undef };
1101 print "\nMessage saved.\n";
1105 sub _send_message_vms {
1106 if ( ( $address =~ /@/ and $address !~ /^\w+%"/ )
1107 or ( $cc =~ /@/ and $cc !~ /^\w+%"/ ) ) {
1109 foreach ( qw[ IN MX SMTP UCX PONY WINS ], '' ) {
1110 $prefix = "$_%", last if $ENV{"MAIL\$PROTOCOL_$_"};
1112 $address = qq[${prefix}"$address"] unless $address =~ /^\w+%"/;
1113 $cc = qq[${prefix}"$cc"] unless !$cc || $cc =~ /^\w+%"/;
1115 $subject =~ s/"/""/g;
1116 $address =~ s/"/""/g;
1118 my $sts = system(qq[mail/Subject="$subject" $filename. "$address","$cc"]);
1120 die "Can't spawn off mail (leaving bug report in $filename): $sts";
1124 sub _send_message_mailsend {
1125 my $msg = Mail::Send->new();
1126 my %headers = %{_message_headers()};
1127 for my $key ( keys %headers) {
1128 $msg->add($key => $headers{$key});
1132 open(REP, "<$filename") or die "Couldn't open '$filename': $!\n";
1133 while (<REP>) { print $fh $_ }
1134 close(REP) or die "Error closing $filename: $!";
1137 print "\nMessage sent.\n";
1140 sub _probe_for_sendmail {
1142 for (qw(/usr/lib/sendmail /usr/sbin/sendmail /usr/ucblib/sendmail)) {
1143 $sendmail = $_, last if -e $_;
1145 if ( $^O eq 'os2' and $sendmail eq "" ) {
1146 my $path = $ENV{PATH};
1148 my @path = split /$Config{'path_sep'}/, $path;
1150 $sendmail = "$_/sendmail", last if -e "$_/sendmail";
1151 $sendmail = "$_/sendmail.exe", last if -e "$_/sendmail.exe";
1157 sub _send_message_sendmail {
1158 my $sendmail = _probe_for_sendmail();
1159 unless ($sendmail) {
1160 paraprint(<<"EOF"), die "\n";
1161 It appears that there is no program which looks like "sendmail" on
1162 your system and that the Mail::Send library from CPAN isn't available.
1163 Because of this, there's no easy way to automatically send your
1166 A copy of your message has been saved in '$filename' for you to
1167 send to '$address' with your normal mail client.
1171 open( SENDMAIL, "|$sendmail -t -oi" )
1172 || die "'|$sendmail -t -oi' failed: $!";
1173 print SENDMAIL build_complete_message();
1174 if ( close(SENDMAIL) ) {
1175 print "\nMessage sent\n";
1177 warn "\nSendmail returned status '", $? >> 8, "'\n";
1183 # a strange way to check whether any significant editing
1184 # has been done: check whether any new non-empty lines
1187 sub _fingerprint_lines_in_report {
1189 # read in the report template once so that
1190 # we can track whether the user does any editing.
1191 # yes, *all* whitespace is ignored.
1193 open(REP, "<$filename") or die "Unable to open report file '$filename': $!\n";
1194 while (my $line = <REP>) {
1196 $new_lines++ if (!$REP{$line});
1199 close(REP) or die "Error closing report file '$filename': $!";
1200 # returns the number of lines with content that wasn't there when last we looked
1207 ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~~
1215 perlbug - how to submit bug reports on Perl
1221 B<perlbug> S<[ B<-v> ]> S<[ B<-a> I<address> ]> S<[ B<-s> I<subject> ]>
1222 S<[ B<-b> I<body> | B<-f> I<inputfile> ]> S<[ B<-F> I<outputfile> ]>
1223 S<[ B<-r> I<returnaddress> ]>
1224 S<[ B<-e> I<editor> ]> S<[ B<-c> I<adminaddress> | B<-C> ]>
1225 S<[ B<-S> ]> S<[ B<-t> ]> S<[ B<-d> ]> S<[ B<-A> ]> S<[ B<-h> ]> S<[ B<-T> ]>
1227 B<perlbug> S<[ B<-v> ]> S<[ B<-r> I<returnaddress> ]>
1228 S<[ B<-A> ]> S<[ B<-ok> | B<-okay> | B<-nok> | B<-nokay> ]>
1235 This program is designed to help you generate and send bug reports
1236 (and thank-you notes) about perl5 and the modules which ship with it.
1238 In most cases, you can just run it interactively from a command
1239 line without any special arguments and follow the prompts.
1241 If you have found a bug with a non-standard port (one that was not
1242 part of the I<standard distribution>), a binary distribution, or a
1243 non-core module (such as Tk, DBI, etc), then please see the
1244 documentation that came with that distribution to determine the
1245 correct place to report bugs.
1247 If you are unable to send your report using B<perlbug> (most likely
1248 because your system doesn't have a way to send mail that perlbug
1249 recognizes), you may be able to use this tool to compose your report
1250 and save it to a file which you can then send to B<perlbug@perl.org>
1251 using your regular mail client.
1253 In extreme cases, B<perlbug> may not work well enough on your system
1254 to guide you through composing a bug report. In those cases, you
1255 may be able to use B<perlbug -d> to get system configuration
1256 information to include in a manually composed bug report to
1257 B<perlbug@perl.org>.
1260 When reporting a bug, please run through this checklist:
1264 =item What version of Perl you are running?
1266 Type C<perl -v> at the command line to find out.
1268 =item Are you running the latest released version of perl?
1270 Look at http://www.perl.org/ to find out. If you are not using the
1271 latest released version, please try to replicate your bug on the
1272 latest stable release.
1274 Note that reports about bugs in old versions of Perl, especially
1275 those which indicate you haven't also tested the current stable
1276 release of Perl, are likely to receive less attention from the
1277 volunteers who build and maintain Perl than reports about bugs in
1278 the current release.
1280 This tool isn't apropriate for reporting bugs in any version
1283 =item Are you sure what you have is a bug?
1285 A significant number of the bug reports we get turn out to be
1286 documented features in Perl. Make sure the issue you've run into
1287 isn't intentional by glancing through the documentation that comes
1288 with the Perl distribution.
1290 Given the sheer volume of Perl documentation, this isn't a trivial
1291 undertaking, but if you can point to documentation that suggests
1292 the behaviour you're seeing is I<wrong>, your issue is likely to
1293 receive more attention. You may want to start with B<perldoc>
1294 L<perltrap> for pointers to common traps that new (and experienced)
1295 Perl programmers run into.
1297 If you're unsure of the meaning of an error message you've run
1298 across, B<perldoc> L<perldiag> for an explanation. If the message
1299 isn't in perldiag, it probably isn't generated by Perl. You may
1300 have luck consulting your operating system documentation instead.
1302 If you are on a non-UNIX platform B<perldoc> L<perlport>, as some
1303 features may be unimplemented or work differently.
1305 You may be able to figure out what's going wrong using the Perl
1306 debugger. For information about how to use the debugger B<perldoc>
1309 =item Do you have a proper test case?
1311 The easier it is to reproduce your bug, the more likely it will be
1312 fixed -- if nobody can duplicate your problem, it probably won't be
1315 A good test case has most of these attributes: short, simple code;
1316 few dependencies on external commands, modules, or libraries; no
1317 platform-dependent code (unless it's a platform-specific bug);
1318 clear, simple documentation.
1320 A good test case is almost always a good candidate to be included in
1321 Perl's test suite. If you have the time, consider writing your test case so
1322 that it can be easily included into the standard test suite.
1324 =item Have you included all relevant information?
1326 Be sure to include the B<exact> error messages, if any.
1327 "Perl gave an error" is not an exact error message.
1329 If you get a core dump (or equivalent), you may use a debugger
1330 (B<dbx>, B<gdb>, etc) to produce a stack trace to include in the bug
1333 NOTE: unless your Perl has been compiled with debug info
1334 (often B<-g>), the stack trace is likely to be somewhat hard to use
1335 because it will most probably contain only the function names and not
1336 their arguments. If possible, recompile your Perl with debug info and
1337 reproduce the crash and the stack trace.
1339 =item Can you describe the bug in plain English?
1341 The easier it is to understand a reproducible bug, the more likely
1342 it will be fixed. Any insight you can provide into the problem
1343 will help a great deal. In other words, try to analyze the problem
1344 (to the extent you can) and report your discoveries.
1346 =item Can you fix the bug yourself?
1348 A bug report which I<includes a patch to fix it> will almost
1349 definitely be fixed. When sending a patch, please use the C<diff>
1350 program with the C<-u> option to generate "unified" diff files.
1351 Bug reports with patches are likely to receive significantly more
1352 attention and interest than those without patches.
1354 Your patch may be returned with requests for changes, or requests for more
1355 detailed explanations about your fix.
1357 Here are a few hints for creating high-quality patches:
1359 Make sure the patch is not reversed (the first argument to diff is
1360 typically the original file, the second argument your changed file).
1361 Make sure you test your patch by applying it with the C<patch>
1362 program before you send it on its way. Try to follow the same style
1363 as the code you are trying to patch. Make sure your patch really
1364 does work (C<make test>, if the thing you're patching is covered
1365 by Perl's test suite).
1367 =item Can you use C<perlbug> to submit the report?
1369 B<perlbug> will, amongst other things, ensure your report includes
1370 crucial information about your version of perl. If C<perlbug> is
1371 unable to mail your report after you have typed it in, you may have
1372 to compose the message yourself, add the output produced by C<perlbug
1373 -d> and email it to B<perlbug@perl.org>. If, for some reason, you
1374 cannot run C<perlbug> at all on your system, be sure to include the
1375 entire output produced by running C<perl -V> (note the uppercase V).
1377 Whether you use C<perlbug> or send the email manually, please make
1378 your Subject line informative. "a bug" is not informative. Neither
1379 is "perl crashes" nor is "HELP!!!". These don't help. A compact
1380 description of what's wrong is fine.
1382 =item Can you use C<perlbug> to submit a thank-you note?
1384 Yes, you can do this by either using the C<-T> option, or by invoking
1385 the program as C<perlthanks>. Thank-you notes are good. It makes people
1390 Having done your bit, please be prepared to wait, to be told the
1391 bug is in your code, or possibly to get no reply at all. The
1392 volunteers who maintain Perl are busy folks, so if your problem is
1393 an obvious bug in your own code, is difficult to understand or is
1394 a duplicate of an existing report, you may not receive a personal
1397 If it is important to you that your bug be fixed, do monitor the
1398 perl5-porters@perl.org mailing list and the commit logs to development
1399 versions of Perl, and encourage the maintainers with kind words or
1400 offers of frosty beverages. (Please do be kind to the maintainers.
1401 Harassing or flaming them is likely to have the opposite effect of
1404 Feel free to update the ticket about your bug on http://rt.perl.org
1405 if a new version of Perl is released and your bug is still present.
1413 Address to send the report to. Defaults to B<perlbug@perl.org>.
1417 Don't send a bug received acknowledgement to the reply address.
1418 Generally it is only a sensible to use this option if you are a
1419 perl maintainer actively watching perl porters for your message to
1424 Body of the report. If not included on the command line, or
1425 in a file with B<-f>, you will get a chance to edit the message.
1429 Don't send copy to administrator.
1433 Address to send copy of report to. Defaults to the address of the
1434 local perl administrator (recorded when perl was built).
1438 Data mode (the default if you redirect or pipe output). This prints out
1439 your configuration data, without mailing anything. You can use this
1440 with B<-v> to get more complete data.
1448 File containing the body of the report. Use this to quickly send a
1453 File to output the results to instead of sending as an email. Useful
1454 particularly when running perlbug on a machine with no direct internet
1459 Prints a brief summary of the options.
1463 Report successful build on this system to perl porters. Forces B<-S>
1464 and B<-C>. Forces and supplies values for B<-s> and B<-b>. Only
1465 prompts for a return address if it cannot guess it (for use with
1466 B<make>). Honors return address specified with B<-r>. You can use this
1467 with B<-v> to get more complete data. Only makes a report if this
1468 system is less than 60 days old.
1472 As B<-ok> except it will report on older systems.
1476 Report unsuccessful build on this system. Forces B<-C>. Forces and
1477 supplies a value for B<-s>, then requires you to edit the report
1478 and say what went wrong. Alternatively, a prepared report may be
1479 supplied using B<-f>. Only prompts for a return address if it
1480 cannot guess it (for use with B<make>). Honors return address
1481 specified with B<-r>. You can use this with B<-v> to get more
1482 complete data. Only makes a report if this system is less than 60
1487 As B<-nok> except it will report on older systems.
1491 Your return address. The program will ask you to confirm its default
1492 if you don't use this option.
1496 Send without asking for confirmation.
1500 Subject to include with the message. You will be prompted if you don't
1501 supply one on the command line.
1505 Test mode. The target address defaults to B<perlbug-test@perl.org>.
1509 Send a thank-you note instead of a bug report.
1513 Include verbose configuration data in the report.
1519 Kenneth Albanowski (E<lt>kjahds@kjahds.comE<gt>), subsequently
1520 I<doc>tored by Gurusamy Sarathy (E<lt>gsar@activestate.comE<gt>),
1521 Tom Christiansen (E<lt>tchrist@perl.comE<gt>), Nathan Torkington
1522 (E<lt>gnat@frii.comE<gt>), Charles F. Randall (E<lt>cfr@pobox.comE<gt>),
1523 Mike Guy (E<lt>mjtg@cam.a.ukE<gt>), Dominic Dunlop
1524 (E<lt>domo@computer.orgE<gt>), Hugo van der Sanden (E<lt>hv@crypt.org<gt>),
1525 Jarkko Hietaniemi (E<lt>jhi@iki.fiE<gt>), Chris Nandor
1526 (E<lt>pudge@pobox.comE<gt>), Jon Orwant (E<lt>orwant@media.mit.eduE<gt>,
1527 Richard Foley (E<lt>richard.foley@rfi.netE<gt>), and Jesse Vincent
1528 (E<lt>jesse@bestpractical.com<gt>).
1532 perl(1), perldebug(1), perldiag(1), perlport(1), perltrap(1),
1533 diff(1), patch(1), dbx(1), gdb(1)
1537 None known (guess what must have been used to report them?)
1543 close OUT or die "Can't close $file: $!";
1544 chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
1545 exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';