This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlbug.pod for 5.004
[perl5.git] / utils / perlbug.PL
CommitLineData
37fa004c 1#!/usr/local/bin/perl
2
3use Config;
4use 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.
44a8e56a 15chdir dirname($0);
16$file = basename($0, '.PL');
774d564b 17$file .= '.com' if $^O eq 'VMS';
37fa004c 18
19open OUT,">$file" or die "Can't create $file: $!";
20
21print "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
26print OUT <<"!GROK!THIS!";
5f05dabc 27$Config{startperl}
28 eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}'
29 if \$running_under_some_shell;
37fa004c 30!GROK!THIS!
31
32# In the following, perl variables are not expanded during extraction.
33
34print OUT <<'!NO!SUBS!';
35
36use Config;
37fa004c 37use Getopt::Std;
38
c07a80fd 39BEGIN {
40 eval "use Mail::Send;";
41 $::HaveSend = ($@ eq "");
42 eval "use Mail::Util;";
43 $::HaveUtil = ($@ eq "");
44};
45
46
37fa004c 47use strict;
48
49sub paraprint;
50
c07a80fd 51
774d564b 52my($Version) = "1.16";
c07a80fd 53
54# Changed in 1.06 to skip Mail::Send and Mail::Util if not available.
a5f75d66
AD
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.
c07a80fd 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
a5f75d66 60# temp filename generation.
c07a80fd 61# Changed in 1.11 to clean up some text and removed Mail::Send deactivator.
a5f75d66
AD
62# Changed in 1.12 to check for editor errors, make save/send distinction
63# clearer and add $ENV{REPLYTO}.
84478119 64# Changed in 1.13 to hopefully make it more difficult to accidentally
65# send mail
ab3ef367 66# Changed in 1.14 to make the prompts a little more clear on providing
67# helpful information. Also let file read fail gracefully.
8ecf1a0c
KA
68# Changed in 1.15 to add warnings to stop people using perlbug for non-bugs.
69# Also report selected environment variables.
774d564b 70# Changed in 1.16 to include @INC, and allow user to re-edit if no changes.
c07a80fd 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.
37fa004c 75
ab3ef367 76my( $file, $usefile, $cc, $address, $perlbug, $testaddress, $filename,
37fa004c 77 $subject, $from, $verbose, $ed,
774d564b 78 $fh, $me, $Is_VMS, $msg, $body, $andcc, %REP);
37fa004c 79
80Init();
81
82if($::opt_h) { Help(); exit; }
83
84478119 84if(!-t STDIN) {
85 paraprint <<EOF;
86Please use perlbug interactively. If you want to
87include a file, you can use the -f switch.
88EOF
89 die "\n";
90}
91
c07a80fd 92if($::opt_d or !-t STDOUT) { Dump(*STDOUT); exit; }
93
37fa004c 94Query();
ab3ef367 95Edit() unless $usefile;
37fa004c 96NowWhat();
97Send();
98
99exit;
100
101sub Init {
102
103 # -------- Setup --------
104
84478119 105 $Is_VMS = $^O eq 'VMS';
37fa004c 106
c07a80fd 107 getopts("dhva:s:b:f:r:e:SCc:t");
37fa004c 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
ab3ef367 141 # Send a file
142 $usefile = ($::opt_f || 0);
143
37fa004c 144 # File to send as report
145 $file = $::opt_f || "";
146
147 # Body of report
148 $body = $::opt_b || "";
149
150 # Editor
ab3ef367 151 $ed = ( $::opt_e || $ENV{VISUAL} || $ENV{EDITOR} || $ENV{EDIT} ||
37fa004c 152 ($Is_VMS ? "edit/tpu" : "vi")
ab3ef367 153 );
154
37fa004c 155
156 # My username
157 $me = getpwuid($<);
158
159}
160
161
162sub Query {
163
164 # Explain what perlbug is
165
166 paraprint <<EOF;
8ecf1a0c
KA
167This program provides an easy way to create a message reporting a bug
168in perl, and e-mail it to $address. It is *NOT* intended for
169sending test messages or simply verifying that perl works. It is *ONLY*
170a means of reporting verifiable problems with perl, and any solutions to
171such problems, to the people who maintain perl.
37fa004c 172
173EOF
174
175
176 # Prompt for subject of message, if needed
177 if(! $subject) {
178 paraprint <<EOF;
179First of all, please provide a subject for the
ab3ef367 180message. It should be a concise description of
774d564b 181the bug or problem. "perl bug" or "perl problem"
182is not a concise description.
37fa004c 183
184EOF
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
c07a80fd 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 }
37fa004c 217
218 my($guess);
219
220 if( !$domain) {
221 $guess = "";
bf9e8eaa 222 } elsif ($Is_VMS && !$::Config{'d_socket'}) {
c07a80fd 223 $guess = "$domain\:\:$me";
37fa004c 224 } else {
c07a80fd 225 $guess = "$me\@$domain" if $domain;
226 $guess = "$me\@unknown.addresss" unless $domain;
37fa004c 227 }
a5f75d66
AD
228
229 $guess = $ENV{'REPLYTO'} if defined($ENV{'REPLYTO'});
230 $guess = $ENV{"REPLY-TO"} if defined($ENV{'REPLY-TO'});
37fa004c 231
232 if( $guess ) {
233 paraprint <<EOF;
234
235
a5f75d66
AD
236Your e-mail address will be useful if you need to be contacted. If the
237default shown is not your full internet e-mail address, please correct it.
37fa004c 238
239EOF
240 } else {
241 paraprint <<EOF;
242
243So that you may be contacted if necessary, please enter
a5f75d66 244your full internet e-mail address here.
37fa004c 245
246EOF
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
c07a80fd 264 $cc = "yourself";
37fa004c 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
273A copy of this report can be sent to your local
274perl administrator. If the address is wrong, please
c07a80fd 275correct it, or enter 'none' or 'yourself' to not send
276a copy.
37fa004c 277
278EOF
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
84478119 292 if($cc =~ /^(none|yourself|me|myself|ourselves)$/i) { $cc = "" }
37fa004c 293
294 $andcc = " and $cc" if $cc;
295
ab3ef367 296editor:
297
37fa004c 298 # Prompt for editor, if no override is given
299 if(! $::opt_e and ! $::opt_f and ! $::opt_b) {
300 paraprint <<EOF;
301
302
c07a80fd 303Now you need to supply the bug report. Try to make
37fa004c 304the report concise but descriptive. Include any
ab3ef367 305relevant detail. If you are reporting something
306that does not work as you think it should, please
307try to include example of both the actual
308result, and what you expected.
309
310Some information about your local
37fa004c 311perl configuration will automatically be included
ab3ef367 312at the end of the report. If you are using any
313unusual version of perl, please try and confirm
314exactly which versions are relevant.
37fa004c 315
316You will probably want to use an editor to enter
317the report. If "$ed" is the editor you want
318to use, then just press Enter, otherwise type in
319the name of the editor you would like to use.
320
c07a80fd 321If you would like to use a prepared file, type
37fa004c 322"file", and you will be asked for the filename.
323
324EOF
325
326 print "Editor [$ed]: ";
327
328 my($entry) =scalar(<>);
329 chop $entry;
ab3ef367 330
331 $usefile = 0;
332 if($entry eq "file") {
333 $usefile = 1;
334 } elsif($entry ne "") {
37fa004c 335 $ed = $entry;
336 }
337 }
338
339
340 # Generate scratch file to edit report in
341
c07a80fd 342 {
343 my($dir) = $Is_VMS ? 'sys$scratch:' : '/tmp/';
344 $filename = "bugrep0$$";
345 $filename++ while -e "$dir$filename";
346 $filename = "$dir$filename";
347 }
37fa004c 348
349
350 # Prompt for file to read report from, if needed
351
ab3ef367 352 if( $usefile and ! $file) {
353filename:
37fa004c 354 paraprint <<EOF;
355
37fa004c 356What is the name of the file that contains your report?
357
358EOF
359
360 print "Filename: ";
361
362 my($entry) = scalar(<>);
363 chop($entry);
364
ab3ef367 365 if($entry eq "") {
366 paraprint <<EOF;
367
368No filename? I'll let you go back and choose an editor again.
369
370EOF
371 goto editor;
372 }
373
37fa004c 374 if(!-f $entry or !-r $entry) {
ab3ef367 375 paraprint <<EOF;
376
377I'm sorry, but I can't read from `$entry'. Maybe you mistyped the name of
378the file? If you don't want to send a file, just enter a blank line and you
379can get back to the editor selection.
380
381EOF
382 goto filename;
37fa004c 383 }
384 $file = $entry;
385
386 }
387
388
389 # Generate report
390
391 open(REP,">$filename");
392
393 print REP <<EOF;
394This is a bug report for perl from $from,
395generated with the help of perlbug $Version running under perl $].
396
397EOF
398
399 if($body) {
400 print REP $body;
ab3ef367 401 } elsif($usefile) {
402 open(F,"<$file") or die "Unable to read report file from `$file': $!\n";
37fa004c 403 while(<F>) {
404 print REP $_
405 }
406 close(F);
407 } else {
774d564b 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-----------------------------------------------------------------
417EOF
37fa004c 418 }
c07a80fd 419
420 Dump(*REP);
421 close(REP);
37fa004c 422
774d564b 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
c07a80fd 433}
434
435sub Dump {
436 local(*OUT) = @_;
437
438 print OUT <<EOF;
37fa004c 439
774d564b 440---
37fa004c 441Site configuration information for perl $]:
442
443EOF
444
445 if( $::Config{cf_by} and $::Config{cf_time}) {
c07a80fd 446 print OUT "Configured by $::Config{cf_by} at $::Config{cf_time}.\n\n";
37fa004c 447 }
448
c07a80fd 449 print OUT Config::myconfig;
37fa004c 450
451 if($verbose) {
c07a80fd 452 print OUT "\nComplete configuration data for perl $]:\n\n";
37fa004c 453 my($value);
454 foreach (sort keys %::Config) {
455 $value = $::Config{$_};
456 $value =~ s/'/\\'/g;
c07a80fd 457 print OUT "$_='$value'\n";
37fa004c 458 }
459 }
8ecf1a0c
KA
460 print OUT <<EOF;
461
774d564b 462---
463\@INC for perl $]:
464EOF
465 for my $i (@INC) {
466 print OUT "\t$i\n";
467 }
468
469 print OUT <<EOF;
8ecf1a0c 470
774d564b 471---
8ecf1a0c
KA
472Environment for perl $]:
473EOF
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 }
37fa004c 483}
484
485sub Edit {
486 # Edit the report
ab3ef367 487
488 if($usefile) {
489 $usefile = 0;
490 paraprint <<EOF;
491
492Please make sure that the name of the editor you want to use is correct.
493
494EOF
495 print "Editor [$ed]: ";
496
497 my($entry) =scalar(<>);
498 chop $entry;
37fa004c 499
ab3ef367 500 if($entry ne "") {
501 $ed = $entry;
502 }
503 }
504
505tryagain:
506 if(!$usefile and !$body) {
c07a80fd 507 my($sts) = system("$ed $filename");
508 if( $Is_VMS ? !($sts & 1) : $sts ) {
a5f75d66
AD
509 #print "\nUnable to run editor!\n";
510 paraprint <<EOF;
511
512The editor you chose (`$ed') could apparently not be run!
513Did you mistype the name of your editor? If so, please
514correct it here, otherwise just press Enter.
515
516EOF
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
529You may want to save your report to a file, so you can edit and mail it
530yourself.
531EOF
532 }
37fa004c 533 }
534 }
774d564b 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
553I am sorry but it looks like you did not report anything.
554
555EOF
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
567sub Cancel {
568 1 while unlink($filename); # remove all versions under VMS
569 print "\nCancelling.\n";
570 exit(0);
37fa004c 571}
572
573sub NowWhat {
574
575 # Report is done, prompt for further action
576 if( !$::opt_S ) {
577 while(1) {
578
579 paraprint <<EOF;
580
581
582Now that you have completed your report, would you like to send
583the message to $address$andcc, display the message on
584the screen, re-edit it, or cancel without sending anything?
585You may also save the message as a file to mail at another time.
586
587EOF
588
a5f75d66 589 print "Action (Send/Display/Edit/Cancel/Save to File): ";
37fa004c 590 my($action) = scalar(<>);
591 chop $action;
592
a5f75d66 593 if( $action =~ /^(f|sa)/i ) { # <F>ile/<Sa>ve
37fa004c 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
a5f75d66 612 } elsif( $action =~ /^(d|l|sh)/i ) { # <D>isplay, <L>ist, <Sh>ow
37fa004c 613 # Display the message
614 open(REP,"<$filename");
615 while(<REP>) { print $_ }
616 close(REP);
84478119 617 } elsif( $action =~ /^se/i ) { # <S>end
a5f75d66 618 # Send the message
84478119 619 print "\
620Are you certain you want to send this message?
621Please type \"yes\" if you are: ";
622 my($reply) = scalar(<STDIN>);
623 chop($reply);
624 if( $reply eq "yes" ) {
625 last;
ab3ef367 626 } else {
627 paraprint <<EOF;
628
629That wasn't a clear "yes", so I won't send your message. If you are sure
630your message should be sent, type in "yes" (without the quotes) at the
631confirmation prompt.
632
633EOF
634
84478119 635 }
a5f75d66 636 } elsif( $action =~ /^[er]/i ) { # <E>dit, <R>e-edit
37fa004c 637 # edit the message
a5f75d66
AD
638 Edit();
639 #system("$ed $filename");
640 } elsif( $action =~ /^[qc]/i ) { # <C>ancel, <Q>uit
774d564b 641 Cancel();
84478119 642 } elsif( $action =~ /^s/ ) {
643 paraprint <<EOF;
644
645I'm sorry, but I didn't understand that. Please type "send" or "save".
646EOF
37fa004c 647 }
648
649 }
650 }
651}
652
653
654sub Send {
655
656 # Message has been accepted for transmission -- Send the message
c07a80fd 657
658 if($::HaveSend) {
37fa004c 659
c07a80fd 660 $msg = new Mail::Send Subject => $subject, To => $address;
37fa004c 661
c07a80fd 662 $msg->cc($cc) if $cc;
663 $msg->add("Reply-To",$from) if $from;
37fa004c 664
c07a80fd 665 $fh = $msg->open;
666
667 open(REP,"<$filename");
668 while(<REP>) { print $fh $_ }
669 close(REP);
37fa004c 670
c07a80fd 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
697I am terribly sorry, but I cannot find sendmail, or a close equivalent, and
698the perl package Mail::Send has not been installed, so I can't send your bug
3f4fc463 699report. We apologize for the inconvenience.
c07a80fd 700
701So you may attempt to find some way of sending your message, it has
702been left in the file `$filename'.
703
704EOF
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 }
37fa004c 718
c07a80fd 719 }
37fa004c 720
721 print "\nMessage sent.\n";
722
723 1 while unlink($filename); # remove all versions under VMS
724
725}
726
727sub Help {
728 print <<EOF;
729
730A program to help generate bug reports about perl5, and mail them.
731It is designed to be used interactively. Normally no arguments will
732be needed.
733
734Usage:
735$0 [-v] [-a address] [-s subject] [-b body | -f file ]
3f4fc463 736 [-r returnaddress] [-e editor] [-c adminaddress | -C] [-S] [-t] [-h]
37fa004c 737
c07a80fd 738Simplest usage: run "$0", and follow the prompts.
37fa004c 739
740Options:
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'.
c07a80fd 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.
3f4fc463 760 -h Print this help message.
37fa004c 761
762EOF
763}
764
765sub paraprint {
766 my @paragraphs = split /\n{2,}/, "@_";
c07a80fd 767 print "\n\n";
37fa004c 768 for (@paragraphs) { # implicit local $_
769 s/(\S)\s*\n/$1 /g;
770 write;
771 print "\n";
772 }
773
774}
775
776
777format STDOUT =
778^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~~
779$_
780.
3f4fc463
GS
781
782__END__
783
784=head1 NAME
785
786perlbug - how to submit bug reports on Perl
787
788=head1 SYNOPSIS
789
790B<perlbug> S<[ B<-v> ]> S<[ B<-a> I<address> ]> S<[ B<-s> I<subject> ]>
791S<[ B<-b> I<body> | B<-f> I<file> ]> S<[ B<-r> I<returnaddress> ]>
792S<[ B<-e> I<editor> ]> S<[ B<-c> I<adminaddress> | B<-C> ]>
793S<[ B<-S> ]> S<[ B<-t> ]> S<[ B<-d> ]> S<[ B<-h> ]>
794
795=head1 DESCRIPTION
796
797A program to help generate bug reports about perl or the modules that
798come with it, and mail them.
799
800If you have found a bug with a non-standard port (one that was not part
801of the I<standard distribution>), a binary distribution, or a
802non-standard module (such as Tk, CGI, etc), then please see the
803documentation that came with that distribution to determine the correct
804place to report bugs.
805
806C<perlbug> is designed to be used interactively. Normally no arguments
807will be needed. Simply run it, and follow the prompts.
808
809If you are unable to run B<perlbug> (most likely because you don't have
810a working setup to send mail that perlbug recognizes), you may have to
811compose your own report, and email it to B<perlbug@perl.com>. You might
812find the B<-d> option useful to get summary information in that case.
813
814In any case, when reporting a bug, please make sure you have run through
815this checklist:
816
817=over 4
818
819=item What version of perl you are running?
820
821Type C<perl -v> at the command line to find out.
822
823=item Are you running the latest released version of perl?
824
825Look at http://www.perl.com/ to find out. If it is not the latest
826released version, get that one and see whether your bug has been
827fixed. Note that bug reports about old versions of perl, especially
828those prior to the 5.0 release, are likely to fall upon deaf ears.
829You are on your own if you continue to use perl1 .. perl4.
830
831=item Are you sure what you have is a bug?
832
833A significant number of the bug reports we get turn out to be documented
834features in perl. Make sure the behavior you are witnessing doesn't fall
835under that category, by glancing through the documentation that comes
836with perl (we'll admit this is no mean task, given the sheer volume of
837it all, but at least have a look at the sections that I<seem> relevant).
838
839Be aware of the familiar traps that perl programmers of various hues
4fc194b2 840fall into. See L<perltrap>.
3f4fc463
GS
841
842Try to study the problem under the perl debugger, if necessary.
4fc194b2 843See L<perldebug>.
3f4fc463
GS
844
845=item Do you have a proper test case?
846
847The easier it is to reproduce your bug, the more likely it will be
848fixed, because if no one can duplicate the problem, no one can fix it.
849A good test case has most of these attributes: fewest possible number
850of lines; few dependencies on external commands, modules, or
851libraries; runs on most platforms unimpeded; and is self-documenting.
852
853A good test case is almost always a good candidate to be on the perl
854test suite. If you have the time, consider making your test case so
855that it will readily fit into the standard test suite.
856
857=item Can you describe the bug in plain English?
858
859The easier it is to understand a reproducible bug, the more likely it
860will be fixed. Anything you can provide by way of insight into the
861problem helps a great deal. In other words, try to analyse the
862problem to the extent you feel qualified and report your discoveries.
863
864=item Can you fix the bug yourself?
865
866A bug report which I<includes a patch to fix it> will almost
867definitely 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>
869package, so you should be able to get it from any of the GNU software
870repositories). If you do submit a patch, the cool-dude counter at
871perlbug@perl.com will register you as a savior of the world. Your
872patch may be returned with requests for changes, or requests for more
873detailed explanations about your fix.
874
875Here are some clues for creating quality patches: Use the B<-c> or
876B<-u> switches to the diff program (to create a so-called context or
877unified diff). Make sure the patch is not reversed (the first
878argument to diff is typically the original file, the second argument
879your changed file). Make sure you test your patch by applying it with
880the C<patch> program before you send it on its way. Try to follow the
881same style as the code you are trying to patch. Make sure your patch
882really does work (C<make test>, if the thing you're patching supports
883it).
884
885=item Can you use C<perlbug> to submit the report?
886
887B<perlbug> will, amongst other things, ensure your report includes
888crucial information about your version of perl. If C<perlbug> is unable
889to mail your report after you have typed it in, you may have to compose
890the message yourself, add the output produced by C<perlbug -d> and email
891it to B<perlbug@perl.com>. If, for some reason, you cannot run
892C<perlbug> at all on your system, be sure to include the entire output
893produced by running C<perl -V> (note the uppercase V).
894
895=back
896
897Having done your bit, please be prepared to wait, to be told the bug
898is in your code, or even to get no reply at all. The perl maintainers
899are busy folks, so if your problem is a small one or if it is
900difficult to understand, they may not respond with a personal reply.
901If it is important to you that your bug be fixed, do monitor the
902C<Changes> file in any development releases since the time you submitted
903the bug, and encourage the maintainers with kind words (but never any
904flames!). Feel free to resend your bug report if the next released
905version of perl comes out and your bug is still present.
906
907=head1 OPTIONS
908
909=over 8
910
4fc194b2 911=item B<-a>
3f4fc463
GS
912
913Address to send the report to. Defaults to `perlbug@perl.com'.
914
4fc194b2 915=item B<-b>
3f4fc463
GS
916
917Body of the report. If not included on the command line, or
4fc194b2 918in a file with B<-f>, you will get a chance to edit the message.
3f4fc463 919
4fc194b2 920=item B<-C>
3f4fc463
GS
921
922Don't send copy to administrator.
923
4fc194b2 924=item B<-c>
3f4fc463
GS
925
926Address to send copy of report to. Defaults to the address of the
927local perl administrator (recorded when perl was built).
928
4fc194b2 929=item B<-d>
3f4fc463
GS
930
931Data mode (the default if you redirect or pipe output). This prints out
932your configuration data, without mailing anything. You can use this
4fc194b2 933with B<-v> to get more complete data.
3f4fc463 934
4fc194b2 935=item B<-e>
3f4fc463
GS
936
937Editor to use.
938
4fc194b2 939=item B<-f>
3f4fc463
GS
940
941File containing the body of the report. Use this to quickly send a
942prepared message.
943
4fc194b2 944=item B<-h>
3f4fc463
GS
945
946Prints a brief summary of the options.
947
4fc194b2 948=item B<-r>
3f4fc463
GS
949
950Your return address. The program will ask you to confirm its default
951if you don't use this option.
952
4fc194b2 953=item B<-S>
3f4fc463
GS
954
955Send without asking for confirmation.
956
4fc194b2 957=item B<-s>
3f4fc463
GS
958
959Subject to include with the message. You will be prompted if you don't
960supply one on the command line.
961
4fc194b2 962=item B<-t>
3f4fc463
GS
963
964Test mode. The target address defaults to `perlbug-test@perl.com'.
965
4fc194b2 966=item B<-v>
3f4fc463
GS
967
968Include verbose configuration data in the report.
969
970=back
971
972=head1 AUTHORS
973
4fc194b2
GS
974Kenneth Albanowski (E<lt>kjahds@kjahds.comE<gt>), subsequently I<doc>tored
975by Gurusamy Sarathy (E<lt>gsar@umich.eduE<gt>), Tom Christiansen
3f4fc463
GS
976(E<lt>tchrist@perl.comE<gt>), and Nathan Torkington
977(E<lt>gnat@frii.comE<gt>).
978
979=head1 SEE ALSO
980
981perl(1), perldebug(1), perltrap(1), diff(1), patch(1)
982
983=head1 BUGS
984
985None known (guess what must have been used to report them?)
986
987=cut
988
37fa004c 989!NO!SUBS!
990
991close OUT or die "Can't close $file: $!";
992chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
993exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
3f4fc463 994