Commit | Line | Data |
57ddfe24 |
1 | package lib::core::only; |
2 | |
3 | use strict; |
4 | use warnings FATAL => 'all'; |
5 | use Config; |
6 | |
7 | sub import { |
8 | @INC = @Config{qw(privlibexp archlibexp)}; |
9 | return |
10 | } |
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 | |
d8b1a404 |
20 | To get only the core directories plus the ones for the local::lib in scope: |
57ddfe24 |
21 | |
cde83945 |
22 | $ perl -mlocal::lib -Mlib::core::only -Mlocal::lib=~/perl5 myscript.pl |
57ddfe24 |
23 | |
d8b1a404 |
24 | To attempt to do a self-contained build (but note this will not reliably |
25 | propagate into subprocesses, see the CAVEATS below): |
26 | |
cde83945 |
27 | $ PERL5OPT='-mlocal::lib -Mlib::core::only -Mlocal::lib=~/perl5' cpan |
28 | |
29 | Please note that it is necessary to use C<local::lib> twice for this to work. |
30 | First so that C<lib::core::only> doesn't prevent C<local::lib> from loading |
31 | (it's not currently in core) and then again after C<lib::core::only> so that |
32 | the local paths are not removed. |
d8b1a404 |
33 | |
57ddfe24 |
34 | =head1 DESCRIPTION |
35 | |
36 | lib::core::only is simply a shortcut to say "please reduce my @INC to only |
d8b1a404 |
37 | the core lib and archlib (architecture-specific lib) directories of this perl". |
57ddfe24 |
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<App::FatPacker|App::FatPacker> 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</CAVEATS>). |
45 | |
46 | This module was extracted from L<local::lib|local::lib>'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<not> propagate properly across perl invocations like local::lib's |
53 | stuff does. It can't. It's only a module import, so it B<only affects the |
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<lib|lib> 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<http://www.shadowcat.co.uk/blog/matt-s-trout/tainted-love> - and for ways |
82 | to achieve the old --self-contained feature's results, look at |
83 | L<App::FatPacker|App::FatPacker>'s tree function, and at |
84 | L<App::cpanminus|cpanm>'s --local-lib-contained feature. |
85 | |
86 | =head1 AUTHOR |
87 | |
88 | Matt S. Trout <mst@shadowcat.co.uk> |
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</AUTHOR> as specified above. |
97 | |
98 | =cut |
99 | |
100 | 1; |