File Coverage

blib/lib/lib/core/only.pm
Criterion Covered Total %
statement 11 11 100.0
branch n/a
condition n/a
subroutine 4 4 100.0
pod n/a
total 15 15 100.0


line stmt bran cond sub pod time code
1             package lib::core::only;
2              
3 1     1   56339 use strict;
  1         7  
  1         25  
4 1     1   3 use warnings FATAL => 'all';
  1         2  
  1         26  
5 1     1   4 use Config;
  1         1  
  1         78  
6              
7             sub import {
8 1     1   80 @INC = @Config{qw(privlibexp archlibexp)};
9             return
10 1         2 }
11              
12             =head1 NAME
13              
14             lib::core::only - Remove all non-core paths from @INC to avoid site/vendor dirs
15              
16             =head1 SYNOPSIS
17              
18             use lib::core::only; # now @INC contains only the two core directories
19              
20             To get only the core directories plus the ones for the local::lib in scope:
21              
22             $ perl -mlocal::lib -Mlib::core::only -Mlocal::lib=~/perl5 myscript.pl
23              
24             To attempt to do a self-contained build (but note this will not reliably
25             propagate into subprocesses, see the CAVEATS below):
26              
27             $ PERL5OPT='-mlocal::lib -Mlib::core::only -Mlocal::lib=~/perl5' cpan
28              
29             Please note that it is necessary to use C twice for this to work.
30             First so that C doesn't prevent C from loading
31             (it's not currently in core) and then again after C so that
32             the local paths are not removed.
33              
34             =head1 DESCRIPTION
35              
36             lib::core::only is simply a shortcut to say "please reduce my @INC to only
37             the core lib and archlib (architecture-specific lib) directories of this perl".
38              
39             You might want to do this to ensure a local::lib contains only the code you
40             need, or to test an L tree, or to avoid known
41             bad vendor packages.
42              
43             You might want to use this to try and install a self-contained tree of perl
44             modules. Be warned that that probably won't work (see L).
45              
46             This module was extracted from L's --self-contained
47             feature, and contains the only part that ever worked. I apologise to anybody
48             who thought anything else did.
49              
50             =head1 CAVEATS
51              
52             This does B propagate properly across perl invocations like local::lib's
53             stuff does. It can't. It's only a module import, so it B
54             specific perl VM instance in which you load and import() it>.
55              
56             If you want to cascade it across invocations, you can set the PERL5OPT
57             environment variable to '-Mlib::core::only' and it'll sort of work. But be
58             aware that taint mode ignores this, so some modules' build and test code
59             probably will as well.
60              
61             You also need to be aware that perl's command line options are not processed
62             in order - -I options take effect before -M options, so
63              
64             perl -Mlib::core::only -Ilib
65              
66             is unlike to do what you want - it's exactly equivalent to:
67              
68             perl -Mlib::core::only
69              
70             If you want to combine a core-only @INC with additional paths, you need to
71             add the additional paths using -M options and the L module:
72              
73             perl -Mlib::core::only -Mlib=lib
74              
75             # or if you're trying to test compiled code:
76              
77             perl -Mlib::core::only -Mblib
78              
79             For more information on the impossibility of sanely propagating this across
80             module builds without help from the build program, see
81             L - and for ways
82             to achieve the old --self-contained feature's results, look at
83             L's tree function, and at
84             L's --local-lib-contained feature.
85              
86             =head1 AUTHOR
87              
88             Matt S. Trout
89              
90             =head1 LICENSE
91              
92             This library is free software under the same terms as perl itself.
93              
94             =head1 COPYRIGHT
95              
96             (c) 2010 the lib::core::only L as specified above.
97              
98             =cut
99              
100             1;