Canary-Stability/Stability.pm

=head1 NAME

Canary::Stability - canary to check perl compatibility for schmorp's modules

=head1 SYNOPSIS

 # in Makefile.PL
 use Canary::Stability DISTNAME => 2001, MINIMUM_PERL_VERSION;

=head1 DESCRIPTION

This module is used by Schmorp's modules during configuration stage to
test the installed perl for compatibility with his modules.

It's not, at this stage, meant as a tool for other module authors,
although in principle nothing prevents them from subscribing to the same
ideas.

See the F<Makefile.PL> in L<Coro> or L<AnyEvent> for usage examples.

=cut

package Canary::Stability;

BEGIN {
   $VERSION = 2006;
}

sub sgr {
   # we just assume ANSI almost everywhere
   # red 31, yellow 33, green 32
   local $| = 1;

   $ENV{PERL_CANARY_STABILITY_COLOUR} ne 0
   and ((-t STDOUT and length $ENV{TERM}) or $ENV{PERL_CANARY_STABILITY_COLOUR})
   and print "\e[$_[0]m";
}

sub import {
   my (undef, $distname, $minvers, $minperl) = @_;

   $ENV{PERL_CANARY_STABILITY_DISABLE}
      and return;

   $minperl ||= 5.008002;

   if ($minvers > $VERSION) {
      sgr 33;
      print <<EOF;

***
*** The stability canary says: (nothing, it died of old age).
***
*** Your Canary::Stability module (used by $distname) is too old.
*** This is not a fatal problem - while you might want to upgrade to version
*** $minvers (currently installed version: $VERSION) to get better support
*** status testing, you might also not want to care at all, and all will
*** be well as long $distname works well enough for you, as the stability
*** canary is only used when installing the distribution.
***

EOF
   } elsif ($] < $minperl) {

      sgr 33;
      print <<EOF;

***
*** The stability canary says: chirp (it seems concerned about something).
***
*** Your perl version ($]) is older than the $distname distribution
*** likes ($minperl). This is not a fatal problem - the module might work
*** well with your version of perl, but it does mean the author likely
*** won't do anything to make it work if it breaks.
***

EOF
   } elsif (defined $Internals::StabilityBranchVersion) {
      # note to people studying this modules sources:
      # the above test is not considered a clean or stable way to
      # test for the stability branch.

      sgr 32;
      print <<EOF;

***
*** The stability canary says: chirp! chirp! (it seems to be quite excited)
***
*** It seems you are running schmorp's stability branch of perl.
*** All should be well, and if it isn't, you should report this as a bug
*** to the $distname author.
***

EOF
   } elsif ($] < 5.021) {
      #sgr 32;
      print <<EOF;

***
*** The stability canary says: chirp! chirp! (it seems to be quite happy)
***
*** Your version of perl ($]) is quite supported by $distname, nothing
*** else to be said, hope it comes in handy.
***

EOF
   } else {
      sgr 31;
      print <<EOF;

***
*** The stability canary says: (nothing, it was driven away by harsh weather)
***
*** It seems you are running perl version $], likely the "official" or
*** "standard" version. While there is nothing wrong with doing that,
*** standard perl versions 5.022 and up are not supported by $distname.
*** While this might be fatal, it might also be all right - if you run into
*** problems, you might want to downgrade your perl or switch to the
*** stability branch.
***
*** If everything works fine, you can ignore this message.
***
EOF
      sgr 0;
      print <<EOF;
*** Stability canary mini-FAQ:
***
*** Do I need to do anything?
***    With luck, no. While some distributions are known to fail
***    already, most should probably work. This message is here
***    to alert you that your perl is not supported by $distname,
***    and if things go wrong, you either need to downgrade, or
***    sidegrade to the stability variant of your perl version,
***    or simply live with the consequences.
***
*** What is this canary thing?
***    It's purpose is to check support status of $distname with
***    respect to your perl version.
***
*** What is this "stability branch"?
***    It's a branch or fork of the official perl, by schmorp, to
***    improve stability and compatibility with existing modules.
***
*** How can I skip this prompt on automated installs?
***    Set PERL_CANARY_STABILITY_NOPROMPT=1 in your environment.
***    More info is in the Canary::Stability manpage.
***
*** Long version of this FAQ: http://stableperl.schmorp.de/faq.html
*** Stability Branch homepage: http://stableperl.schmorp.de/
***

EOF

      unless ($ENV{PERL_CANARY_STABILITY_NOPROMPT}) {
         require ExtUtils::MakeMaker;

         ExtUtils::MakeMaker::prompt ("Continue anyways? ", "y") =~ /^y/i
            or die "FATAL: User aborted configuration of $distname.\n";
      }
   }

   sgr 0;
}

=head1 ENVIRONMENT VARIABLES

=over 4

=item C<PERL_CANARY_STABILITY_NOPROMPT=1>

Do not prompt the user on alert messages.

=item C<PERL_CANARY_STABILITY_COLOUR=0>

Disable use of colour.

=item C<PERL_CANARY_STABILITY_COLOUR=1>

Force use of colour.

=item C<PERL_CANARY_STABILITY_DISABLE=1>

Disable this modules functionality completely.

=back

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://software.schmorp.de/pkg/Canary-Stability.html

=cut

1

Revision:	1.7
Committed:	Mon Jun 29 00:02:01 2015 UTC (8 years, 10 months ago) by root
Branch:	MAIN
Changes since 1.6:	+1 -0 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3	root	1.4	Canary::Stability - canary to check perl compatibility for schmorp's modules
4	root	1.1
5			=head1 SYNOPSIS
6
7	root	1.4	# in Makefile.PL
8			use Canary::Stability DISTNAME => 2001, MINIMUM_PERL_VERSION;
9	root	1.1
10			=head1 DESCRIPTION
11
12	root	1.4	This module is used by Schmorp's modules during configuration stage to
13			test the installed perl for compatibility with his modules.
14
15			It's not, at this stage, meant as a tool for other module authors,
16			although in principle nothing prevents them from subscribing to the same
17			ideas.
18
19			See the F<Makefile.PL> in L<Coro> or L<AnyEvent> for usage examples.
20	root	1.1
21			=cut
22
23			package Canary::Stability;
24
25			BEGIN {
26	root	1.6	$VERSION = 2006;
27	root	1.2	}
28
29			sub sgr {
30			# we just assume ANSI almost everywhere
31			# red 31, yellow 33, green 32
32	root	1.7	local $\| = 1;
33	root	1.2
34			$ENV{PERL_CANARY_STABILITY_COLOUR} ne 0
35			and ((-t STDOUT and length $ENV{TERM}) or $ENV{PERL_CANARY_STABILITY_COLOUR})
36			and print "\e[$_[0]m";
37	root	1.1	}
38
39			sub import {
40	root	1.2	my (undef, $distname, $minvers, $minperl) = @_;
41
42			$ENV{PERL_CANARY_STABILITY_DISABLE}
43			and return;
44
45			$minperl \|\|= 5.008002;
46
47			if ($minvers > $VERSION) {
48			sgr 33;
49			print <<EOF;
50
51			***
52	root	1.3	*** The stability canary says: (nothing, it died of old age).
53	root	1.2	***
54			*** Your Canary::Stability module (used by $distname) is too old.
55			*** This is not a fatal problem - while you might want to upgrade to version
56			*** $minvers (currently installed version: $VERSION) to get better support
57			*** status testing, you might also not want to care at all, and all will
58			*** be well as long $distname works well enough for you, as the stability
59			*** canary is only used when installing the distribution.
60			***
61
62			EOF
63			} elsif ($] < $minperl) {
64
65			sgr 33;
66			print <<EOF;
67
68			***
69	root	1.3	*** The stability canary says: chirp (it seems concerned about something).
70	root	1.2	***
71			*** Your perl version ($]) is older than the $distname distribution
72			*** likes ($minperl). This is not a fatal problem - the module might work
73			*** well with your version of perl, but it does mean the author likely
74	root	1.3	*** won't do anything to make it work if it breaks.
75	root	1.2	***
76
77			EOF
78			} elsif (defined $Internals::StabilityBranchVersion) {
79			# note to people studying this modules sources:
80			# the above test is not considered a clean or stable way to
81			# test for the stability branch.
82
83			sgr 32;
84			print <<EOF;
85
86			***
87			*** The stability canary says: chirp! chirp! (it seems to be quite excited)
88			***
89			*** It seems you are running schmorp's stability branch of perl.
90			*** All should be well, and if it isn't, you should report this as a bug
91			*** to the $distname author.
92			***
93
94			EOF
95	root	1.6	} elsif ($] < 5.021) {
96	root	1.3	#sgr 32;
97	root	1.2	print <<EOF;
98
99			***
100			*** The stability canary says: chirp! chirp! (it seems to be quite happy)
101			***
102			*** Your version of perl ($]) is quite supported by $distname, nothing
103			*** else to be said, hope it comes in handy.
104			***
105
106			EOF
107			} else {
108			sgr 31;
109			print <<EOF;
110
111			***
112			*** The stability canary says: (nothing, it was driven away by harsh weather)
113			***
114			*** It seems you are running perl version $], likely the "official" or
115			*** "standard" version. While there is nothing wrong with doing that,
116			*** standard perl versions 5.022 and up are not supported by $distname.
117			*** While this might be fatal, it might also be all right - if you run into
118			*** problems, you might want to downgrade your perl or switch to the
119			*** stability branch.
120			***
121			*** If everything works fine, you can ignore this message.
122			***
123			EOF
124			sgr 0;
125			print <<EOF;
126			*** Stability canary mini-FAQ:
127			***
128			*** Do I need to do anything?
129			*** With luck, no. While some distributions are known to fail
130			*** already, most should probably work. This message is here
131			*** to alert you that your perl is not supported by $distname,
132			*** and if things go wrong, you either need to downgrade, or
133			*** sidegrade to the stability variant of your perl version,
134			*** or simply live with the consequences.
135			***
136			*** What is this canary thing?
137			*** It's purpose is to check support status of $distname with
138			*** respect to your perl version.
139			***
140			*** What is this "stability branch"?
141			*** It's a branch or fork of the official perl, by schmorp, to
142			*** improve stability and compatibility with existing modules.
143			***
144			*** How can I skip this prompt on automated installs?
145			*** Set PERL_CANARY_STABILITY_NOPROMPT=1 in your environment.
146			*** More info is in the Canary::Stability manpage.
147			***
148	root	1.5	*** Long version of this FAQ: http://stableperl.schmorp.de/faq.html
149			*** Stability Branch homepage: http://stableperl.schmorp.de/
150	root	1.2	***
151
152			EOF
153
154			unless ($ENV{PERL_CANARY_STABILITY_NOPROMPT}) {
155			require ExtUtils::MakeMaker;
156
157			ExtUtils::MakeMaker::prompt ("Continue anyways? ", "y") =~ /^y/i
158			or die "FATAL: User aborted configuration of $distname.\n";
159			}
160			}
161
162			sgr 0;
163	root	1.1	}
164
165	root	1.2	=head1 ENVIRONMENT VARIABLES
166
167			=over 4
168
169			=item C<PERL_CANARY_STABILITY_NOPROMPT=1>
170
171			Do not prompt the user on alert messages.
172
173			=item C<PERL_CANARY_STABILITY_COLOUR=0>
174
175			Disable use of colour.
176
177			=item C<PERL_CANARY_STABILITY_COLOUR=1>
178
179			Force use of colour.
180
181			=item C<PERL_CANARY_STABILITY_DISABLE=1>
182
183			Disable this modules functionality completely.
184
185			=back
186
187	root	1.1	=head1 AUTHOR
188
189			Marc Lehmann <schmorp@schmorp.de>
190	root	1.6	http://software.schmorp.de/pkg/Canary-Stability.html
191	root	1.1
192			=cut
193
194			1
195