In perl.git, the branch blead has been updated <https://perl5.git.perl.org/perl.git/commitdiff/776df88fda46ef3c747750e8122e7b290f3496a7?hp=6fa7480cb8207fa42519b5660f36dcd35b377c7c>
- Log ----------------------------------------------------------------- commit 776df88fda46ef3c747750e8122e7b290f3496a7 Author: Aristotle Pagaltzis <[email protected]> Date: Mon Feb 18 00:14:52 2019 +0100 deprecate: expand the documentation commit 7f4cf7621dff61fd6643465d9120524907cb34b3 Author: Aristotle Pagaltzis <[email protected]> Date: Mon Feb 18 00:14:46 2019 +0100 prepare next patch commit a64ac81e504b759fcf679d357a59737a7a1c2c08 Author: Aristotle Pagaltzis <[email protected]> Date: Mon Feb 18 00:14:38 2019 +0100 deprecate: fix POD heading level ----------------------------------------------------------------------- Summary of changes: lib/deprecate.pm | 57 +++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 46 insertions(+), 11 deletions(-) diff --git a/lib/deprecate.pm b/lib/deprecate.pm index 47bc11253e..b2371caa97 100644 --- a/lib/deprecate.pm +++ b/lib/deprecate.pm @@ -71,26 +71,61 @@ __END__ =head1 NAME -deprecate - Perl pragma for deprecating the core version of a module +deprecate - Perl pragma for deprecating the inclusion of a module in core =head1 SYNOPSIS - use deprecate; # always deprecate the module in which this occurs - - use if $] > 5.010, 'deprecate'; # conditionally deprecate the module + use deprecate; # warn about future absence if loaded from core =head1 DESCRIPTION -This module is used using C<use deprecate;> (or something that calls -C<< deprecate->import() >>, for example C<use if COND, deprecate;>). +This pragma simplifies the maintenance of dual-life modules that will no longer +be included in the Perl core in a future Perl release, but are still included +currently. + +The purpose of the pragma is to alert users to the status of such a module by +issuing a warning that encourages them to install the module from CPAN, so that +a future upgrade to a perl which omits the module will not break their code. + +This warning will only be issued if the module was loaded from a core library +directory, which allows the C<use deprecate> line to be included in the CPAN +version of the module. Because the pragma remains silent when the module is run +from a non-core library directory, the pragma call does not need to be patched +into or out of either the core or CPAN version of the module. The exact same +code can be shipped for either purpose. + +=head2 Important Caveat + +Note that when a module installs from CPAN to a core library directory rather +than the site library directories, the user gains no protection from having +installed it. + +At the same time, this pragma cannot detect when such a module has installed +from CPAN to the core library, and so it would endlessly and uselessly exhort +the user to upgrade. + +Therefore modules that can install from CPAN to the core library must make sure +not to call this pragma when they have done so. Generally this means that the +exact logic from the installer must be mirrored inside the module. E.g.: + + # Makefile.PL + WriteMakefile( + # ... + INSTALLDIRS => ( "$]" >= 5.011 ? 'site' : 'perl' ), + ); + + # lib/Foo/Bar.pm + use if "$]" >= 5.011, 'deprecate'; + +(The above example shows the most important case of this: when the target is +a Perl older than 5.12 (where the core library directories take precedence over +the site library directories) and the module being installed was included in +core in that Perl version. Under those circumstances, an upgrade of the module +from CPAN is only possible by installing to the core library.) -If the module that includes C<use deprecate> is located in a core library -directory, a deprecation warning is issued, encouraging the user to use -the version on CPAN. If that module is located in a site library, it is -the CPAN version, and no warning is issued. -=head2 EXPORT +=head1 EXPORT None by default. The only method is C<import>, called by C<use deprecate;>. -- Perl5 Master Repository
