/usr/local/share/man/man3/ Current File: //usr/local/share/man/man3/lib::core::only.3pm
.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "lib::core::only 3"
.TH lib::core::only 3 "2015-05-27" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
lib::core::only \- Remove all non\-core paths from @INC to avoid site/vendor dirs
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use lib::core::only; # now @INC contains only the two core directories
.Ve
.PP
To get only the core directories plus the ones for the local::lib in scope:
.PP
.Vb 1
\&  $ perl \-mlocal::lib \-Mlib::core::only \-Mlocal::lib=~/perl5 myscript.pl
.Ve
.PP
To attempt to do a self-contained build (but note this will not reliably
propagate into subprocesses, see the \s-1CAVEATS\s0 below):
.PP
.Vb 1
\&  $ PERL5OPT=\*(Aq\-mlocal::lib \-Mlib::core::only \-Mlocal::lib=~/perl5\*(Aq cpan
.Ve
.PP
Please note that it is necessary to use \f(CW\*(C`local::lib\*(C'\fR twice for this to work.
First so that \f(CW\*(C`lib::core::only\*(C'\fR doesn't prevent \f(CW\*(C`local::lib\*(C'\fR from loading
(it's not currently in core) and then again after \f(CW\*(C`lib::core::only\*(C'\fR so that
the local paths are not removed.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
lib::core::only is simply a shortcut to say \*(L"please reduce my \f(CW@INC\fR to only
the core lib and archlib (architecture-specific lib) directories of this perl\*(R".
.PP
You might want to do this to ensure a local::lib contains only the code you
need, or to test an App::FatPacker tree, or to avoid known
bad vendor packages.
.PP
You might want to use this to try and install a self-contained tree of perl
modules. Be warned that that probably won't work (see \*(L"\s-1CAVEATS\*(R"\s0).
.PP
This module was extracted from local::lib's \-\-self\-contained
feature, and contains the only part that ever worked. I apologise to anybody
who thought anything else did.
.SH "CAVEATS"
.IX Header "CAVEATS"
This does \fBnot\fR propagate properly across perl invocations like local::lib's
stuff does. It can't. It's only a module import, so it \fBonly affects the
specific perl \s-1VM\s0 instance in which you load and \f(BIimport()\fB it\fR.
.PP
If you want to cascade it across invocations, you can set the \s-1PERL5OPT\s0
environment variable to '\-Mlib::core::only' and it'll sort of work. But be
aware that taint mode ignores this, so some modules' build and test code
probably will as well.
.PP
You also need to be aware that perl's command line options are not processed
in order \- \-I options take effect before \-M options, so
.PP
.Vb 1
\&  perl \-Mlib::core::only \-Ilib
.Ve
.PP
is unlike to do what you want \- it's exactly equivalent to:
.PP
.Vb 1
\&  perl \-Mlib::core::only
.Ve
.PP
If you want to combine a core-only \f(CW@INC\fR with additional paths, you need to
add the additional paths using \-M options and the lib module:
.PP
.Vb 1
\&  perl \-Mlib::core::only \-Mlib=lib
\&
\&  # or if you\*(Aqre trying to test compiled code:
\&
\&  perl \-Mlib::core::only \-Mblib
.Ve
.PP
For more information on the impossibility of sanely propagating this across
module builds without help from the build program, see
<http://www.shadowcat.co.uk/blog/matt\-s\-trout/tainted\-love> \- and for ways
to achieve the old \-\-self\-contained feature's results, look at
App::FatPacker's tree function, and at
App::cpanminus's \-\-local\-lib\-contained feature.
.SH "AUTHOR"
.IX Header "AUTHOR"
Matt S. Trout <mst@shadowcat.co.uk>
.SH "LICENSE"
.IX Header "LICENSE"
This library is free software under the same terms as perl itself.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
(c) 2010 the lib::core::only \*(L"\s-1AUTHOR\*(R"\s0 as specified above.