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 | |
22 | $ perl -Mlib::core::only -Mlocal::lib=~/perl5 myscript.pl |
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 | |
27 | $ PERL5OPT='-Mlib::core::only -Mlocal::lib=~/perl5' cpan |
28 | |
57ddfe24 |
29 | =head1 DESCRIPTION |
30 | |
31 | lib::core::only is simply a shortcut to say "please reduce my @INC to only |
d8b1a404 |
32 | the core lib and archlib (architecture-specific lib) directories of this perl". |
57ddfe24 |
33 | |
34 | You might want to do this to ensure a local::lib contains only the code you |
35 | need, or to test an L<App::FatPacker|App::FatPacker> tree, or to avoid known |
36 | bad vendor packages. |
37 | |
38 | You might want to use this to try and install a self-contained tree of perl |
39 | modules. Be warned that that probably won't work (see L</CAVEATS>). |
40 | |
41 | This module was extracted from L<local::lib|local::lib>'s --self-contained |
42 | feature, and contains the only part that ever worked. I apologise to anybody |
43 | who thought anything else did. |
44 | |
45 | =head1 CAVEATS |
46 | |
47 | This does B<not> propagate properly across perl invocations like local::lib's |
48 | stuff does. It can't. It's only a module import, so it B<only affects the |
49 | specific perl VM instance in which you load and import() it>. |
50 | |
51 | If you want to cascade it across invocations, you can set the PERL5OPT |
52 | environment variable to '-Mlib::core::only' and it'll sort of work. But be |
53 | aware that taint mode ignores this, so some modules' build and test code |
54 | probably will as well. |
55 | |
56 | You also need to be aware that perl's command line options are not processed |
57 | in order - -I options take effect before -M options, so |
58 | |
59 | perl -Mlib::core::only -Ilib |
60 | |
61 | is unlike to do what you want - it's exactly equivalent to: |
62 | |
63 | perl -Mlib::core::only |
64 | |
65 | If you want to combine a core-only @INC with additional paths, you need to |
66 | add the additional paths using -M options and the L<lib|lib> module: |
67 | |
68 | perl -Mlib::core::only -Mlib=lib |
69 | |
70 | # or if you're trying to test compiled code: |
71 | |
72 | perl -Mlib::core::only -Mblib |
73 | |
74 | For more information on the impossibility of sanely propagating this across |
75 | module builds without help from the build program, see |
76 | L<http://www.shadowcat.co.uk/blog/matt-s-trout/tainted-love> - and for ways |
77 | to achieve the old --self-contained feature's results, look at |
78 | L<App::FatPacker|App::FatPacker>'s tree function, and at |
79 | L<App::cpanminus|cpanm>'s --local-lib-contained feature. |
80 | |
81 | =head1 AUTHOR |
82 | |
83 | Matt S. Trout <mst@shadowcat.co.uk> |
84 | |
85 | =head1 LICENSE |
86 | |
87 | This library is free software under the same terms as perl itself. |
88 | |
89 | =head1 COPYRIGHT |
90 | |
91 | (c) 2010 the lib::core::only L</AUTHOR> as specified above. |
92 | |
93 | =cut |
94 | |
95 | 1; |