local-lib5/lib/perl5/Task/Weaken.pm

   1 package Task::Weaken;
   2
   3 use 5.005;
   4 use strict;
   5
   6 use vars qw{$VERSION};
   7 BEGIN {
   8         $VERSION = '1.03';
   9 }
  10
  11 1;
  12
  13 __END__
  14
  15 =pod
  16
  17 =head1 NAME
  18
  19 Task::Weaken - Ensure that a platform has weaken support
  20
  21 =head1 DESCRIPTION
  22
  23 One recurring problem in modules that use L<Scalar::Util>'s C<weaken>
  24 function is that it is not present in the pure-perl variant.
  25
  26 While this isn't necesarily always a problem in a straight CPAN-based
  27 Perl environment, some operating system distributions only include the
  28 pure-Perl versions, don't include the XS version, and so weaken is
  29 then "missing" from the platform, B<despite> passing a dependency on
  30 L<Scalar::Util> successfully.
  31
  32 Most notably this is RedHat Linux at time of writing, but other come
  33 and go and do the same thing, hence "recurring problem".
  34
  35 The normal solution is to manually write tests in each distribution
  36 to ensure that C<weaken> is available.
  37
  38 This restores the functionality testing to a dependency you do once
  39 in your F<Makefile.PL>, rather than something you have to write extra
  40 tests for each time you write a module.
  41
  42 It should also help make the package auto-generators for the various
  43 operating systems play more nicely, because it introduces a dependency
  44 that they B<have> to have a proper weaken in order to work.
  45
  46 =head2 How this Task works
  47
  48 Part of the problem seems to stem from the fact that some distributions
  49 continue to include modules even if they fail some of their tests.
  50
  51 To get around that for this module, it will do a few dirty tricks.
  52
  53 If L<Scalar::Util> is not available at all, it will issue a normal
  54 dependency on the module. However, if L<Scalar::Util> is relatively
  55 new ( it is >= 1.19 ) and the module does B<not> have weaken, the
  56 install will bail out altogether with a long error encouraging the
  57 user to seek support from their vendor (this problem happens most
  58 often in vendor-packaged Perl versions).
  59
  60 This distribution also contains tests to ensure that weaken is
  61 available using more normal methods.
  62
  63 So if your module uses C<weaken>, you can just add the following to
  64 your L<Module::Install>-based F<Makefile.PL> (or equivalent).
  65
  66   requires 'Task::Weaken' => 0;
  67
  68 =head1 AUTHOR
  69
  70 Adam Kennedy E<lt>adamk@cpan.orgE<gt>, L<http://ali.as/>
  71
  72 =head1 SEE ALSO
  73
  74 L<Task>, L<Scalar::Util>, L<http://ali.as/>
  75
  76 =head1 COPYRIGHT
  77
  78 Copyright 2006 - 2009 Adam Kennedy.
  79
  80 This program is free software; you can redistribute
  81 it and/or modify it under the same terms as Perl itself.
  82
  83 The full text of the license can be found in the
  84 LICENSE file included with this module.
  85
  86 =cut