This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
33290d536d0e5b3eadbd5898b5eae7adcd1d0151
[perl5.git] / utils / perlbug.PL
1 #!/usr/local/bin/perl
2
3 use Config;
4 use File::Basename qw(&basename &dirname);
5
6 # List explicitly here the variables you want Configure to
7 # generate.  Metaconfig only looks for shell variables, so you
8 # have to mention them as if they were shell variables, not
9 # %Config entries.  Thus you write
10 #  $startperl
11 # to ensure Configure will look for $Config{startperl}.
12
13 # This forces PL files to create target in same directory as PL file.
14 # This is so that make depend always knows where to find PL derivatives.
15 chdir dirname($0);
16 $file = basename($0, '.PL');
17 $file .= '.com' if $^O eq 'VMS';
18
19 open OUT,">$file" or die "Can't create $file: $!";
20
21 print "Extracting $file (with variable substitutions)\n";
22
23 # In this section, perl variables will be expanded during extraction.
24 # You can use $Config{...} to use Configure variables.
25
26 print OUT <<"!GROK!THIS!";
27 $Config{startperl}
28     eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}'
29         if \$running_under_some_shell;
30 !GROK!THIS!
31
32 # In the following, perl variables are not expanded during extraction.
33
34 print OUT <<'!NO!SUBS!';
35
36 use Config;
37 use Getopt::Std;
38
39 BEGIN {
40         eval "use Mail::Send;";
41         $::HaveSend = ($@ eq "");
42         eval "use Mail::Util;";
43         $::HaveUtil = ($@ eq "");
44 };
45
46
47 use strict;
48
49 sub paraprint;
50
51
52 my($Version) = "1.16";
53
54 # Changed in 1.06 to skip Mail::Send and Mail::Util if not available.
55 # Changed in 1.07 to see more sendmail execs, and added pipe output.
56 # Changed in 1.08 to use correct address for sendmail.
57 # Changed in 1.09 to close the REP file before calling it up in the editor.
58 #                 Also removed some old comments duplicated elsewhere.
59 # Changed in 1.10 to run under VMS without Mail::Send; also fixed
60 #                 temp filename generation.
61 # Changed in 1.11 to clean up some text and removed Mail::Send deactivator.
62 # Changed in 1.12 to check for editor errors, make save/send distinction
63 #                 clearer and add $ENV{REPLYTO}.
64 # Changed in 1.13 to hopefully make it more difficult to accidentally
65 #                 send mail
66 # Changed in 1.14 to make the prompts a little more clear on providing
67 #                 helpful information. Also let file read fail gracefully.
68 # Changed in 1.15 to add warnings to stop people using perlbug for non-bugs.
69 #                 Also report selected environment variables.
70 # Changed in 1.16 to include @INC, and allow user to re-edit if no changes.
71
72 # TODO: Allow the user to re-name the file on mail failure, and
73 #       make sure failure (transmission-wise) of Mail::Send is 
74 #       accounted for.
75
76 my( $file, $usefile, $cc, $address, $perlbug, $testaddress, $filename,
77     $subject, $from, $verbose, $ed, 
78     $fh, $me, $Is_VMS, $msg, $body, $andcc, %REP);
79
80 Init();
81
82 if($::opt_h) { Help(); exit; }
83
84 if(!-t STDIN) {
85         paraprint <<EOF;
86 Please use perlbug interactively. If you want to 
87 include a file, you can use the -f switch.
88 EOF
89         die "\n";
90 }
91
92 if($::opt_d or !-t STDOUT) { Dump(*STDOUT); exit; }
93
94 Query();
95 Edit() unless $usefile;
96 NowWhat();
97 Send();
98
99 exit;
100
101 sub Init {
102  
103         # -------- Setup --------
104
105         $Is_VMS = $^O eq 'VMS';
106
107         getopts("dhva:s:b:f:r:e:SCc:t");
108         
109
110         # This comment is needed to notify metaconfig that we are
111         # using the $perladmin, $cf_by, and $cf_time definitions.
112
113
114         # -------- Configuration ---------
115         
116         # perlbug address
117         $perlbug = 'perlbug@perl.com';
118         
119         # Test address
120         $testaddress = 'perlbug-test@perl.com';
121         
122         # Target address
123         $address = $::opt_a || ($::opt_t ? $testaddress : $perlbug);
124
125         # Possible administrator addresses, in order of confidence
126         # (Note that cf_email is not mentioned to metaconfig, since
127         # we don't really want it. We'll just take it if we have to.)
128         $cc = ($::opt_C ? "" : (
129                 $::opt_c || $::Config{perladmin} || $::Config{cf_email} || $::Config{cf_by}
130                 ));
131         
132         # Users address, used in message and in Reply-To header
133         $from = $::opt_r || "";
134
135         # Include verbose configuration information
136         $verbose = $::opt_v || 0;
137
138         # Subject of bug-report message
139         $subject = $::opt_s || "";
140
141         # Send a file
142         $usefile = ($::opt_f || 0);
143         
144         # File to send as report
145         $file = $::opt_f || "";
146
147         # Body of report
148         $body = $::opt_b || "";
149
150         # Editor
151         $ed = ( $::opt_e || $ENV{VISUAL} || $ENV{EDITOR} || $ENV{EDIT} || 
152                       ($Is_VMS ? "edit/tpu" : "vi")
153               );
154               
155       
156         # My username
157         $me = getpwuid($<);
158
159 }
160
161
162 sub Query {
163
164         # Explain what perlbug is
165         
166         paraprint <<EOF;
167 This program provides an easy way to create a message reporting a bug
168 in perl, and e-mail it to $address.  It is *NOT* intended for
169 sending test messages or simply verifying that perl works.  It is *ONLY*
170 a means of reporting verifiable problems with perl, and any solutions to
171 such problems, to the people who maintain perl.
172
173 EOF
174
175
176         # Prompt for subject of message, if needed
177         if(! $subject) {
178                 paraprint <<EOF;
179 First of all, please provide a subject for the 
180 message. It should be a concise description of 
181 the bug or problem. "perl bug" or "perl problem"
182 is not a concise description.
183
184 EOF
185                 print "Subject: ";
186         
187                 $subject = <>;
188                 chop $subject;
189         
190                 my($err)=0;
191                 while( $subject =~ /^\s*$/ ) {
192                         print "\nPlease enter a subject: ";
193                         $subject = <>;
194                         chop $subject;
195                         if($err++>5) {
196                                 die "Aborting.\n";
197                         }
198                 }
199         }
200         
201
202         # Prompt for return address, if needed
203         if( !$from) {
204
205                 # Try and guess return address
206                 my($domain);
207                 
208                 if($::HaveUtil) {
209                         $domain = Mail::Util::maildomain();
210                 } elsif ($Is_VMS) {
211                         require Sys::Hostname;
212                         $domain = Sys::Hostname::hostname();
213                 } else {
214                         $domain = `hostname`.".".`domainname`;
215                         $domain =~ s/[\r\n]+//g;
216                 }
217             
218             my($guess);
219                              
220                 if( !$domain) {
221                         $guess = "";
222                 } elsif ($Is_VMS && !$::Config{'d_socket'}) { 
223                         $guess = "$domain\:\:$me";
224                 } else {
225                         $guess = "$me\@$domain" if $domain;
226                         $guess = "$me\@unknown.addresss" unless $domain;
227                         }
228                         
229                 $guess = $ENV{'REPLYTO'} if defined($ENV{'REPLYTO'});
230                 $guess = $ENV{"REPLY-TO"} if defined($ENV{'REPLY-TO'});
231         
232                 if( $guess ) {
233                         paraprint <<EOF;
234
235
236 Your e-mail address will be useful if you need to be contacted. If the
237 default shown is not your full internet e-mail address, please correct it.
238
239 EOF
240                 } else {
241                         paraprint <<EOF;
242
243 So that you may be contacted if necessary, please enter 
244 your full internet e-mail address here.
245
246 EOF
247                 }
248                 print "Your address [$guess]: ";
249         
250                 $from = <>;
251                 chop $from;
252         
253                 if($from eq "") { $from = $guess }
254         
255         }
256         
257         #if( $from =~ /^(.*)\@(.*)$/ ) {
258         #       $mailname = $1;
259         #       $maildomain = $2;
260         #}
261
262         if( $from eq $cc or $me eq $cc ) {
263                 # Try not to copy ourselves
264                 $cc = "yourself";
265         }
266
267
268         # Prompt for administrator address, unless an override was given
269         if( !$::opt_C and !$::opt_c ) {
270                 paraprint <<EOF;
271
272
273 A copy of this report can be sent to your local
274 perl administrator. If the address is wrong, please 
275 correct it, or enter 'none' or 'yourself' to not send
276 a copy.
277
278 EOF
279
280                 print "Local perl administrator [$cc]: ";
281         
282                 my($entry) = scalar(<>);
283                 chop $entry;
284         
285                 if($entry ne "") {
286                         $cc = $entry;
287                         if($me eq $cc) { $cc = "" }
288                 }
289         
290         }
291
292         if($cc =~ /^(none|yourself|me|myself|ourselves)$/i) { $cc = "" }
293
294         $andcc = " and $cc" if $cc;
295
296 editor:
297         
298         # Prompt for editor, if no override is given
299         if(! $::opt_e and ! $::opt_f and ! $::opt_b) {
300                 paraprint <<EOF;
301
302
303 Now you need to supply the bug report. Try to make
304 the report concise but descriptive. Include any 
305 relevant detail. If you are reporting something
306 that does not work as you think it should, please
307 try to include example of both the actual 
308 result, and what you expected.
309
310 Some information about your local
311 perl configuration will automatically be included 
312 at the end of the report. If you are using any
313 unusual version of perl, please try and confirm
314 exactly which versions are relevant.
315
316 You will probably want to use an editor to enter
317 the report. If "$ed" is the editor you want
318 to use, then just press Enter, otherwise type in
319 the name of the editor you would like to use.
320
321 If you would like to use a prepared file, type
322 "file", and you will be asked for the filename.
323
324 EOF
325
326                 print "Editor [$ed]: ";
327         
328                 my($entry) =scalar(<>);
329                 chop $entry;
330                 
331                 $usefile = 0;
332                 if($entry eq "file") {
333                         $usefile = 1;
334                 } elsif($entry ne "") {
335                         $ed = $entry;
336                 } 
337         }
338
339
340         # Generate scratch file to edit report in
341         
342         {
343         my($dir) = $Is_VMS ? 'sys$scratch:' : '/tmp/';
344         $filename = "bugrep0$$";
345         $filename++ while -e "$dir$filename";
346         $filename = "$dir$filename";
347         }
348         
349         
350         # Prompt for file to read report from, if needed
351         
352         if( $usefile and ! $file) {
353 filename:
354                 paraprint <<EOF;
355
356 What is the name of the file that contains your report?
357
358 EOF
359
360                 print "Filename: ";
361         
362                 my($entry) = scalar(<>);
363                 chop($entry);
364
365                 if($entry eq "") {
366                         paraprint <<EOF;
367                         
368 No filename? I'll let you go back and choose an editor again.                   
369
370 EOF
371                         goto editor;
372                 }
373                 
374                 if(!-f $entry or !-r $entry) {
375                         paraprint <<EOF;
376                         
377 I'm sorry, but I can't read from `$entry'. Maybe you mistyped the name of
378 the file? If you don't want to send a file, just enter a blank line and you
379 can get back to the editor selection.
380
381 EOF
382                         goto filename;
383                 }
384                 $file = $entry;
385
386         }
387
388
389         # Generate report
390
391         open(REP,">$filename");
392
393         print REP <<EOF;
394 This is a bug report for perl from $from,
395 generated with the help of perlbug $Version running under perl $].
396
397 EOF
398
399         if($body) {
400                 print REP $body;
401         } elsif($usefile) {
402                 open(F,"<$file") or die "Unable to read report file from `$file': $!\n";
403                 while(<F>) {
404                 print REP $_
405                 }
406                 close(F);
407         } else {
408                 print REP <<EOF;
409
410 -----------------------------------------------------------------
411 [Please enter your report here]
412
413
414
415 [Please do not change anything below this line]
416 -----------------------------------------------------------------
417 EOF
418         }
419         
420         Dump(*REP);
421         close(REP);
422
423         # read in the report template once so that
424         # we can track whether the user does any editing.
425         # yes, *all* whitespace is ignored.
426         open(REP, "<$filename");
427         while (<REP>) {
428                 s/\s+//g;
429                 $REP{$_}++;
430         }
431         close(REP);
432
433 }
434
435 sub Dump {
436         local(*OUT) = @_;
437         
438         print OUT <<EOF;
439
440 ---
441 Site configuration information for perl $]:
442
443 EOF
444
445         if( $::Config{cf_by} and $::Config{cf_time}) {
446                 print OUT "Configured by $::Config{cf_by} at $::Config{cf_time}.\n\n";
447         }
448
449         print OUT Config::myconfig;
450
451         if($verbose) {
452                 print OUT "\nComplete configuration data for perl $]:\n\n";
453                 my($value);
454                 foreach (sort keys %::Config) {
455                         $value = $::Config{$_};
456                         $value =~ s/'/\\'/g;
457                         print OUT "$_='$value'\n";
458                 }
459         }
460         print OUT <<EOF;
461
462 ---
463 \@INC for perl $]:
464 EOF
465         for my $i (@INC) {
466             print OUT "\t$i\n";
467         }
468
469         print OUT <<EOF;
470
471 ---
472 Environment for perl $]:
473 EOF
474         for my $env (qw(PATH LD_LIBRARY_PATH
475                     PERL5LIB PERLLIB PERL5DB
476                     LC_ALL LC_COLLATE LC_CTYPE LC_MONETARY LC_NUMERIC LC_TIME
477                     LANG PERL_BADLANG
478                     SHELL HOME LOGDIR)) {
479             print OUT "    $env",
480                       exists $ENV{$env} ? "=$ENV{$env}" : ' (unset)',
481                       "\n";
482         }
483 }
484
485 sub Edit {
486         # Edit the report
487
488         if($usefile) {
489                 $usefile = 0;
490                 paraprint <<EOF;
491
492 Please make sure that the name of the editor you want to use is correct.
493
494 EOF
495                 print "Editor [$ed]: ";
496                 
497                 my($entry) =scalar(<>);
498                 chop $entry;
499         
500                 if($entry ne "") {
501                         $ed = $entry;
502                 } 
503         }
504         
505 tryagain:
506         if(!$usefile and !$body) {
507                 my($sts) = system("$ed $filename");
508                 if( $Is_VMS ? !($sts & 1) : $sts ) {
509                         #print "\nUnable to run editor!\n";
510                         paraprint <<EOF;
511
512 The editor you chose (`$ed') could apparently not be run!
513 Did you mistype the name of your editor? If so, please
514 correct it here, otherwise just press Enter. 
515
516 EOF
517                         print "Editor [$ed]: ";
518                 
519                         my($entry) =scalar(<>);
520                         chop $entry;
521         
522                         if($entry ne "") {
523                                 $ed = $entry;
524                                 goto tryagain;
525                         } else {
526                         
527                         paraprint <<EOF;
528
529 You may want to save your report to a file, so you can edit and mail it
530 yourself.
531 EOF
532                         }
533                 } 
534         }
535
536         # Check that we have a report that has some, eh, report in it.
537
538         my $unseen = 0;
539
540         open(REP, "<$filename");
541         # a strange way to check whether any significant editing
542         # have been done: check whether any new non-empty lines
543         # have been added. Yes, the below code ignores *any* space
544         # in *any* line.
545         while (<REP>) {
546             s/\s+//g;
547             $unseen++ if ($_ ne '' and not exists $REP{$_});
548         }
549
550         while ($unseen == 0) {
551             paraprint <<EOF;
552
553 I am sorry but it looks like you did not report anything.
554
555 EOF
556                 print "Action (Retry Edit/Cancel) ";
557                 my ($action) = scalar(<>);
558                 if ($action =~ /^[re]/i) { # <R>etry <E>dit
559                         goto tryagain;
560                 } elsif ($action =~ /^[cq]/i) { # <C>ancel, <Q>uit
561                         Cancel();
562                 }
563         }
564
565 }
566
567 sub Cancel {
568     1 while unlink($filename);  # remove all versions under VMS
569     print "\nCancelling.\n";
570     exit(0);
571 }
572
573 sub NowWhat {
574
575         # Report is done, prompt for further action
576         if( !$::opt_S ) {
577                 while(1) {
578
579                         paraprint <<EOF;
580
581
582 Now that you have completed your report, would you like to send 
583 the message to $address$andcc, display the message on 
584 the screen, re-edit it, or cancel without sending anything?
585 You may also save the message as a file to mail at another time.
586
587 EOF
588
589                         print "Action (Send/Display/Edit/Cancel/Save to File): ";
590                         my($action) = scalar(<>);
591                         chop $action;
592
593                         if( $action =~ /^(f|sa)/i ) { # <F>ile/<Sa>ve
594                                 print "\n\nName of file to save message in [perlbug.rep]: ";
595                                 my($file) = scalar(<>);
596                                 chop $file;
597                                 if($file eq "") { $file = "perlbug.rep" }
598                         
599                                 open(FILE,">$file");
600                                 open(REP,"<$filename");
601                                 print FILE "To: $address\nSubject: $subject\n";
602                                 print FILE "Cc: $cc\n" if $cc;
603                                 print FILE "Reply-To: $from\n" if $from;
604                                 print FILE "\n";
605                                 while(<REP>) { print FILE }
606                                 close(REP);
607                                 close(FILE);
608         
609                                 print "\nMessage saved in `$file'.\n";
610                                 exit;
611
612                         } elsif( $action =~ /^(d|l|sh)/i ) { # <D>isplay, <L>ist, <Sh>ow
613                                 # Display the message
614                                 open(REP,"<$filename");
615                                 while(<REP>) { print $_ }
616                                 close(REP);
617                         } elsif( $action =~ /^se/i ) { # <S>end
618                                 # Send the message
619                                 print "\
620 Are you certain you want to send this message?
621 Please type \"yes\" if you are: ";
622                                 my($reply) = scalar(<STDIN>);
623                                 chop($reply);
624                                 if( $reply eq "yes" ) {
625                                         last;
626                                 } else {
627                                         paraprint <<EOF;
628
629 That wasn't a clear "yes", so I won't send your message. If you are sure
630 your message should be sent, type in "yes" (without the quotes) at the
631 confirmation prompt.
632
633 EOF
634                                         
635                                 }
636                         } elsif( $action =~ /^[er]/i ) { # <E>dit, <R>e-edit
637                                 # edit the message
638                                 Edit();
639                                 #system("$ed $filename");
640                         } elsif( $action =~ /^[qc]/i ) { # <C>ancel, <Q>uit
641                                 Cancel();
642                         } elsif( $action =~ /^s/ ) {
643                                 paraprint <<EOF;
644
645 I'm sorry, but I didn't understand that. Please type "send" or "save".
646 EOF
647                         }
648                 
649                 }
650         }
651 }
652
653
654 sub Send {
655
656         # Message has been accepted for transmission -- Send the message
657         
658         if($::HaveSend) {
659
660                 $msg = new Mail::Send Subject => $subject, To => $address;
661         
662                 $msg->cc($cc) if $cc;
663                 $msg->add("Reply-To",$from) if $from;
664             
665                 $fh = $msg->open;
666
667                 open(REP,"<$filename");
668                 while(<REP>) { print $fh $_ }
669                 close(REP);
670         
671                 $fh->close;  
672         
673         } else {
674                 if ($Is_VMS) {
675                         if ( ($address =~ /@/ and $address !~ /^\w+%"/) or
676                              ($cc      =~ /@/ and $cc      !~ /^\w+%"/) ){
677                                 my($prefix);
678                                 foreach (qw[ IN MX SMTP UCX PONY WINS ],'') {
679                                         $prefix = "$_%",last if $ENV{"MAIL\$PROTOCOL_$_"};
680                                 }
681                                 $address = qq[${prefix}"$address"] unless $address =~ /^\w+%"/;
682                                 $cc = qq[${prefix}"$cc"] unless !$cc || $cc =~ /^\w+%"/;
683                         }
684                         $subject =~ s/"/""/g; $address =~ s/"/""/g; $cc =~ s/"/""/g;
685                         my($sts) = system(qq[mail/Subject="$subject" $filename. "$address","$cc"]);
686                         if (!($sts & 1)) { die "Can't spawn off mail\n\t(leaving bug report in $filename): $sts\n;" }
687                 } else {
688                         my($sendmail) = "";
689                         
690                         foreach (qw(/usr/lib/sendmail /usr/sbin/sendmail /usr/ucblib/sendmail))
691                         {
692                                 $sendmail = $_, last if -e $_;
693                         }
694                         
695                         paraprint <<"EOF" and die "\n" if $sendmail eq "";
696                         
697 I am terribly sorry, but I cannot find sendmail, or a close equivalent, and
698 the perl package Mail::Send has not been installed, so I can't send your bug
699 report. We apologize for the inconvenience.
700
701 So you may attempt to find some way of sending your message, it has
702 been left in the file `$filename'.
703
704 EOF
705                         
706                         open(SENDMAIL,"|$sendmail -t");
707                         print SENDMAIL "To: $address\n";
708                         print SENDMAIL "Subject: $subject\n";
709                         print SENDMAIL "Cc: $cc\n" if $cc;
710                         print SENDMAIL "Reply-To: $from\n" if $from;
711                         print SENDMAIL "\n\n";
712                         open(REP,"<$filename");
713                         while(<REP>) { print SENDMAIL $_ }
714                         close(REP);
715                         
716                         close(SENDMAIL);
717                 }
718         
719         }
720         
721         print "\nMessage sent.\n";
722
723         1 while unlink($filename);  # remove all versions under VMS
724
725 }
726
727 sub Help {
728         print <<EOF; 
729
730 A program to help generate bug reports about perl5, and mail them. 
731 It is designed to be used interactively. Normally no arguments will
732 be needed.
733         
734 Usage:
735 $0  [-v] [-a address] [-s subject] [-b body | -f file ]
736     [-r returnaddress] [-e editor] [-c adminaddress | -C] [-S] [-t] [-h]
737     
738 Simplest usage:  run "$0", and follow the prompts.
739
740 Options:
741
742   -v    Include Verbose configuration data in the report
743   -f    File containing the body of the report. Use this to 
744         quickly send a prepared message.
745   -S    Send without asking for confirmation.
746   -a    Address to send the report to. Defaults to `$address'.
747   -c    Address to send copy of report to. Defaults to `$cc'.
748   -C    Don't send copy to administrator.
749   -s    Subject to include with the message. You will be prompted 
750         if you don't supply one on the command line.
751   -b    Body of the report. If not included on the command line, or
752         in a file with -f, you will get a chance to edit the message.
753   -r    Your return address. The program will ask you to confirm
754         this if you don't give it here.
755   -e    Editor to use. 
756   -t    Test mode. The target address defaults to `$testaddress'.
757   -d    Data mode (the default if you redirect or pipe output.) 
758         This prints out your configuration data, without mailing
759         anything. You can use this with -v to get more complete data.
760   -h    Print this help message. 
761   
762 EOF
763 }
764
765 sub paraprint {
766     my @paragraphs = split /\n{2,}/, "@_";
767     print "\n\n";
768     for (@paragraphs) {   # implicit local $_
769         s/(\S)\s*\n/$1 /g;
770             write;
771             print "\n";
772     }
773                        
774 }
775                             
776
777 format STDOUT =
778 ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~~
779 $_
780 .
781
782 __END__
783
784 =head1 NAME
785
786 perlbug - how to submit bug reports on Perl
787
788 =head1 SYNOPSIS
789
790 B<perlbug> S<[ B<-v> ]> S<[ B<-a> I<address> ]> S<[ B<-s> I<subject> ]>
791 S<[ B<-b> I<body> | B<-f> I<file> ]> S<[ B<-r> I<returnaddress> ]>
792 S<[ B<-e> I<editor> ]> S<[ B<-c> I<adminaddress> | B<-C> ]>
793 S<[ B<-S> ]> S<[ B<-t> ]>  S<[ B<-d> ]>  S<[ B<-h> ]>
794
795 =head1 DESCRIPTION
796
797 A program to help generate bug reports about perl or the modules that
798 come with it, and mail them. 
799
800 If you have found a bug with a non-standard port (one that was not part
801 of the I<standard distribution>), a binary distribution, or a
802 non-standard module (such as Tk, CGI, etc), then please see the
803 documentation that came with that distribution to determine the correct
804 place to report bugs.
805
806 C<perlbug> is designed to be used interactively. Normally no arguments
807 will be needed.  Simply run it, and follow the prompts.
808
809 If you are unable to run B<perlbug> (most likely because you don't have
810 a working setup to send mail that perlbug recognizes), you may have to
811 compose your own report, and email it to B<perlbug@perl.com>.  You might
812 find the B<-d> option useful to get summary information in that case.
813
814 In any case, when reporting a bug, please make sure you have run through
815 this checklist:
816
817 =over 4
818
819 =item What version of perl you are running?
820
821 Type C<perl -v> at the command line to find out.
822
823 =item Are you running the latest released version of perl?
824
825 Look at http://www.perl.com/ to find out.  If it is not the latest
826 released version, get that one and see whether your bug has been
827 fixed.  Note that bug reports about old versions of perl, especially
828 those prior to the 5.0 release, are likely to fall upon deaf ears.
829 You are on your own if you continue to use perl1 .. perl4.
830
831 =item Are you sure what you have is a bug?
832
833 A significant number of the bug reports we get turn out to be documented
834 features in perl.  Make sure the behavior you are witnessing doesn't fall
835 under that category, by glancing through the documentation that comes
836 with perl (we'll admit this is no mean task, given the sheer volume of
837 it all, but at least have a look at the sections that I<seem> relevant).
838
839 Be aware of the familiar traps that perl programmers of various hues
840 fall into.  See perltrap(1).
841
842 Try to study the problem under the perl debugger, if necessary.
843 See perldebug(1).
844
845 =item Do you have a proper test case?
846
847 The easier it is to reproduce your bug, the more likely it will be
848 fixed, because if no one can duplicate the problem, no one can fix it.
849 A good test case has most of these attributes: fewest possible number
850 of lines; few dependencies on external commands, modules, or
851 libraries; runs on most platforms unimpeded; and is self-documenting.
852
853 A good test case is almost always a good candidate to be on the perl
854 test suite.  If you have the time, consider making your test case so
855 that it will readily fit into the standard test suite.
856
857 =item Can you describe the bug in plain English?
858
859 The easier it is to understand a reproducible bug, the more likely it
860 will be fixed.  Anything you can provide by way of insight into the
861 problem helps a great deal.  In other words, try to analyse the
862 problem to the extent you feel qualified and report your discoveries.
863
864 =item Can you fix the bug yourself?
865
866 A bug report which I<includes a patch to fix it> will almost
867 definitely be fixed.  Use the C<diff> program to generate your patches
868 (C<diff> is being maintained by the GNU folks as part of the B<diffutils>
869 package, so you should be able to get it from any of the GNU software
870 repositories).  If you do submit a patch, the cool-dude counter at
871 perlbug@perl.com will register you as a savior of the world.  Your
872 patch may be returned with requests for changes, or requests for more
873 detailed explanations about your fix.
874
875 Here are some clues for creating quality patches: Use the B<-c> or
876 B<-u> switches to the diff program (to create a so-called context or
877 unified diff).  Make sure the patch is not reversed (the first
878 argument to diff is typically the original file, the second argument
879 your changed file).  Make sure you test your patch by applying it with
880 the C<patch> program before you send it on its way.  Try to follow the
881 same style as the code you are trying to patch.  Make sure your patch
882 really does work (C<make test>, if the thing you're patching supports
883 it).
884
885 =item Can you use C<perlbug> to submit the report?
886
887 B<perlbug> will, amongst other things, ensure your report includes
888 crucial information about your version of perl.  If C<perlbug> is unable
889 to mail your report after you have typed it in, you may have to compose
890 the message yourself, add the output produced by C<perlbug -d> and email
891 it to B<perlbug@perl.com>.  If, for some reason, you cannot run
892 C<perlbug> at all on your system, be sure to include the entire output
893 produced by running C<perl -V> (note the uppercase V).
894
895 =back
896
897 Having done your bit, please be prepared to wait, to be told the bug
898 is in your code, or even to get no reply at all.  The perl maintainers
899 are busy folks, so if your problem is a small one or if it is
900 difficult to understand, they may not respond with a personal reply.
901 If it is important to you that your bug be fixed, do monitor the
902 C<Changes> file in any development releases since the time you submitted
903 the bug, and encourage the maintainers with kind words (but never any
904 flames!).  Feel free to resend your bug report if the next released
905 version of perl comes out and your bug is still present.
906
907 =head1 OPTIONS
908
909 =over 8
910
911 =item -a
912
913 Address to send the report to.  Defaults to `perlbug@perl.com'.
914
915 =item -b
916
917 Body of the report.  If not included on the command line, or
918 in a file with -f, you will get a chance to edit the message.
919
920 =item -C
921
922 Don't send copy to administrator.
923
924 =item -c
925
926 Address to send copy of report to.  Defaults to the address of the
927 local perl administrator (recorded when perl was built).
928
929 =item -d
930
931 Data mode (the default if you redirect or pipe output).  This prints out
932 your configuration data, without mailing anything.  You can use this
933 with -v to get more complete data.
934
935 =item -e
936
937 Editor to use. 
938
939 =item -f
940
941 File containing the body of the report.  Use this to quickly send a
942 prepared message.
943
944 =item -h
945
946 Prints a brief summary of the options.
947
948 =item -r
949
950 Your return address.  The program will ask you to confirm its default
951 if you don't use this option.
952
953 =item -S
954
955 Send without asking for confirmation.
956
957 =item -s
958
959 Subject to include with the message.  You will be prompted if you don't
960 supply one on the command line.
961
962 =item -t
963
964 Test mode.  The target address defaults to `perlbug-test@perl.com'.
965
966 =item -v
967
968 Include verbose configuration data in the report.
969
970 =back
971
972 =head1 AUTHORS
973
974 Kenneth Albanowski <kjahds@kjahds.com>, subsequently I<doc>tored by
975 Gurusamy Sarathy (E<lt>gsar@umich.eduE<gt>), Tom Christiansen
976 (E<lt>tchrist@perl.comE<gt>), and Nathan Torkington
977 (E<lt>gnat@frii.comE<gt>).
978
979 =head1 SEE ALSO
980
981 perl(1), perldebug(1), perltrap(1), diff(1), patch(1)
982
983 =head1 BUGS
984
985 None known (guess what must have been used to report them?)
986
987 =cut
988
989 !NO!SUBS!
990
991 close OUT or die "Can't close $file: $!";
992 chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
993 exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
994