summaryrefslogtreecommitdiff
path: root/systems/texlive/tlnet/tlpkg/tlperl/lib/deprecate.pm
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2020-04-11 03:09:12 +0000
committerNorbert Preining <norbert@preining.info>2020-04-11 03:09:12 +0000
commitc2697fc286a1e2c94fd9968b76be6f4a6d2114cd (patch)
tree1dc2cfb07cb032740483dd8be7c74aff66b70352 /systems/texlive/tlnet/tlpkg/tlperl/lib/deprecate.pm
parent25111608e6aa05042b0c6f83009262e1973d7a45 (diff)
CTAN sync 202004110309
Diffstat (limited to 'systems/texlive/tlnet/tlpkg/tlperl/lib/deprecate.pm')
-rw-r--r--systems/texlive/tlnet/tlpkg/tlperl/lib/deprecate.pm59
1 files changed, 47 insertions, 12 deletions
diff --git a/systems/texlive/tlnet/tlpkg/tlperl/lib/deprecate.pm b/systems/texlive/tlnet/tlpkg/tlperl/lib/deprecate.pm
index 47bc11253e..995322c477 100644
--- a/systems/texlive/tlnet/tlpkg/tlperl/lib/deprecate.pm
+++ b/systems/texlive/tlnet/tlpkg/tlperl/lib/deprecate.pm
@@ -1,7 +1,7 @@
package deprecate;
use strict;
use warnings;
-our $VERSION = 0.03;
+our $VERSION = 0.04;
# our %Config can ignore %Config::Config, e.g. for testing
our %Config;
@@ -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;>.