'\" te
.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
.\"
.\" 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" ''
'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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" 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 "inc::latest 3"
.TH inc::latest 3 "2012-11-03" "perl v5.12.5" "Perl Programmers Reference Guide"
.\" 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"
inc::latest \- use modules bundled in inc/ if they are newer than installed ones
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  # in Build.PL
\&  use inc::latest \*(AqModule::Build\*(Aq;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \f(CW\*(C`inc::latest\*(C'\fR module helps bootstrap configure-time dependencies for \s-1CPAN\s0
distributions.  These dependencies get bundled into the \f(CW\*(C`inc\*(C'\fR directory within
a distribution and are used by Build.PL (or Makefile.PL).
.PP
Arguments to \f(CW\*(C`inc::latest\*(C'\fR are module names that are checked against both the
current \f(CW@INC\fR array and against specially-named directories in \f(CW\*(C`inc\*(C'\fR.  If
the bundled verison is newer than the installed one (or the module isn't
installed, then, the bundled directory is added to the start of <@INC> and the
module is loaded from there.
.PP
There are actually two variations of \f(CW\*(C`inc::latest\*(C'\fR \*(-- one for authors and one
for the \f(CW\*(C`inc\*(C'\fR directory.  For distribution authors, the \f(CW\*(C`inc::latest\*(C'\fR
installed in the system will record modules loaded via \f(CW\*(C`inc::latest\*(C'\fR and can
be used to create the bundled files in \f(CW\*(C`inc\*(C'\fR, including writing the second
variation as \f(CW\*(C`inc/latest.pm\*(C'\fR.
.PP
This second \f(CW\*(C`inc::latest\*(C'\fR is the one that is loaded in a distribution being
installed (e.g. from Build.PL).  This bundled \f(CW\*(C`inc::latest\*(C'\fR is the one
that determines which module to load.
.SS "Special notes on bundling"
.IX Subsection "Special notes on bundling"
The \f(CW\*(C`inc::latest\*(C'\fR module creates bundled directories based on the packlist
file of an installed distribution.  Even though \f(CW\*(C`inc::latest\*(C'\fR takes module
name arguments, it is better to think of it as bundling and making available
entire \fIdistributions\fR.  When a module is loaded through \f(CW\*(C`inc::latest\*(C'\fR,
it looks in all bundled distributions in \f(CW\*(C`inc/\*(C'\fR for a newer module than
can be found in the existing \f(CW@INC\fR array.
.PP
Thus, the module-name provided should usually be the \*(L"top-level\*(R" module name of
a distribution, though this is not strictly required.  For example,
Module::Build has a number of heuristics to map module names to packlists,
allowing users to do things like this:
.PP
.Vb 1
\&  use inc::latest \*(AqDevel::AssertOS::Unix\*(Aq;
.Ve
.PP
even though Devel::AssertOS::Unix is contained within the Devel-CheckOS
distribution.
.PP
At the current time, packlists are required.  Thus, bundling dual-core modules
may require a 'forced install' over versions in the latest version of perl
in order to create the necessary packlist for bundling.
.SH "USAGE"
.IX Header "USAGE"
When calling \f(CW\*(C`use\*(C'\fR, the bundled \f(CW\*(C`inc::latest\*(C'\fR takes a single module name and
optional arguments to pass to that module's own import method.
.PP
.Vb 1
\&  use \*(Aqinc::latest\*(Aq \*(AqFoo::Bar\*(Aq qw/foo bar baz/;
.Ve
.SS "Author-mode"
.IX Subsection "Author-mode"
You are in author-mode inc::latest if any of the Author-mode methods are
available.  For example:
.PP
.Vb 3
\&  if ( inc::latest\->can(\*(Aqwrite\*(Aq) ) {
\&    inc::latest\->write(\*(Aqinc\*(Aq);
\&  }
.Ve
.IP "\fIloaded_modules()\fR" 4
.IX Item "loaded_modules()"
.Vb 1
\&  my @list = inc::latest\->loaded_modules;
.Ve
.Sp
This takes no arguments and always returns a list of module names requested for
loading via \*(L"use inc::latest '\s-1MODULE\s0'\*(R", regardless of wether the load was
successful or not.
.IP "\fIwrite()\fR" 4
.IX Item "write()"
.Vb 1
\&  inc::latest\->write( \*(Aqinc\*(Aq );
.Ve
.Sp
This writes the bundled version of inc::latest to the directory name given as an
argument.  It almost all cases, it should be '\f(CW\*(C`inc\*(C'\fR'.
.IP "\fIbundle_module()\fR" 4
.IX Item "bundle_module()"
.Vb 3
\&  for my $mod ( inc::latest\->loaded_modules ) {
\&    inc::latest\->bundle_module($mod, $dir);
\&  }
.Ve
.Sp
If \f(CW$mod\fR corresponds to a packlist, then this function creates a specially-named
directory in \f(CW$dir\fR and copies all .pm files from the modlist to the new
directory (which almost always should just be 'inc').  For example, if Foo::Bar
is the name of the module, and \f(CW$dir\fR is 'inc', then the directory would be
\&'inc/inc_Foo\-Bar' and contain files like this:
.Sp
.Vb 1
\&  inc/inc_Foo\-Bar/Foo/Bar.pm
.Ve
.Sp
Currently, \f(CW$mod\fR \fBmust\fR have a packlist.  If this is not the case (e.g. for a
dual-core module), then the bundling will fail.  You may be able to create a
packlist by forced installing the module on top of the version that came with
core Perl.
.SS "As bundled in inc/"
.IX Subsection "As bundled in inc/"
All methods are private.  Only the \f(CW\*(C`import\*(C'\fR method is public.
.SH "AUTHOR"
.IX Header "AUTHOR"
Eric Wilhelm <ewilhelm@cpan.org>, David Golden <dagolden@cpan.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2009 by Eric Wilhelm and David Golden
.PP
This library is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

.\" Oracle has added the ARC stability level to this manual page
.SH ATTRIBUTES
See
.BR attributes (5)
for descriptions of the following attributes:
.sp
.TS
box;
cbp-1 | cbp-1
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE 
=
Availability	runtime/perl-512
=
Stability	Uncommitted
.TE 
.PP
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Module::Build


.SH NOTES

.\" Oracle has added source availability information to this manual page
This software was built from source available at https://java.net/projects/solaris-userland.  The original community source was downloaded from  http://www.cpan.org/src/5.0/perl-5.12.5.tar.bz2

Further information about this software can be found on the open source community website at http://www.perl.org/.