lib/lib/core/only.pm

   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
  20 To get only the core directories plus the ones for the local::lib in scope:
  21
  22   $ perl -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='-Mlib::core::only -Mlocal::lib=~/perl5' cpan
  28
  29 =head1 DESCRIPTION
  30
  31 lib::core::only is simply a shortcut to say "please reduce my @INC to only
  32 the core lib and archlib (architecture-specific lib) directories of this perl".
  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;