.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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 >0, 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
.\" ========================================================================
.\"
.IX Title "inc::latest 3"
.TH inc::latest 3 "2014-12-06" "perl v5.26.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"
inc::latest \- use modules bundled in inc/ if they are newer than installed ones
.SH "VERSION"
.IX Header "VERSION"
version 0.500
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  # in Makefile.PL or Build.PL
\&  use inc::latest \*(AqSome::Configure::Prereq\*(Aq;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fB\s-1WARNING\s0 \*(-- \s-1THIS IS AN EXPERIMENTAL MODULE\s0\fR.  It was originally bundled
(as an experiment) with Module::Build and has been split out for more
general use.
.PP
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 \fIMakefile.PL\fR or \fIBuild.PL\fR.
.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 version is newer than the installed one (or the
module isn't installed, then, the bundled directory is added to the start
of \f(CW@INC\fR 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 \fIMakefile.PL\fR or \fIBuild.PL\fR).  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.
\&\f(CW\*(C`inc::latest\*(C'\fR has a number of heuristics to discover module names,
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.
.SS "Managing dependency chains"
.IX Subsection "Managing dependency chains"
Before bundling a distribution you must ensure that all prerequisites are
also bundled and load in the correct order.
.PP
For example, if you need \f(CW\*(C`Wibble\*(C'\fR, but \f(CW\*(C`Wibble\*(C'\fR depends on \f(CW\*(C`Wobble\*(C'\fR,
and you have bundled \f(CW\*(C`Module::Build\*(C'\fR, your \fIBuild.PL\fR might look like this:
.PP
.Vb 3
\&  use inc::latest \*(AqWobble\*(Aq;
\&  use inc::latest \*(AqWibble\*(Aq;
\&  use inc::latest \*(AqModule::Build\*(Aq;
\&
\&  Module::Build\->new(
\&    module_name => \*(AqFoo::Bar\*(Aq,
\&    license => \*(Aqperl\*(Aq,
\&  )\->create_build_script;
.Ve
.PP
Authors are strongly suggested to limit the bundling of additional
dependencies if at all possible and to carefully test their distribution
tarballs before uploading to \s-1CPAN.\s0
.SH "USAGE"
.IX Header "USAGE"
.SS "As bundled in inc/"
.IX Subsection "As bundled in inc/"
Using \*(L"Author-mode\*(R", a special stub module will be created in your
distribute directory as \fIinc/latest.pm\fR.  In your \fIMakefile.PL\fR or
\&\fIBuild.PL\fR, you can then load \f(CW\*(C`inc::latest\*(C'\fR to load bundled modules.
.PP
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 inc::latest \*(AqFoo::Bar\*(Aq qw/foo bar baz/;
.Ve
.PP
The implementation is private.  Only the \f(CW\*(C`import\*(C'\fR method is public.
.SS "Author-mode"
.IX Subsection "Author-mode"
When you have inc::latest installed from \s-1CPAN,\s0 then you are in author-mode
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
.PP
Using author-mode, you can create the stub \fIinc/latest.pm\fR and bundle
modules into \fIinc\fR.
.IP "\fBloaded_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 whether the load
was successful or not.
.IP "\fBwrite()\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 "\fBbundle_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.
.SH "SUPPORT"
.IX Header "SUPPORT"
.SS "Bugs / Feature Requests"
.IX Subsection "Bugs / Feature Requests"
Please report any bugs or feature requests through the issue tracker
at <https://github.com/dagolden/inc\-latest/issues>.
You will be notified automatically of any progress on your issue.
.SS "Source Code"
.IX Subsection "Source Code"
This is open source software.  The code repository is available for
public review and contribution under the terms of the license.
.PP
<https://github.com/dagolden/inc\-latest>
.PP
.Vb 1
\&  git clone https://github.com/dagolden/inc\-latest.git
.Ve
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
David Golden <dagolden@cpan.org>
.IP "\(bu" 4
Eric Wilhelm <ewilhelm@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2009 by David Golden.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The Apache License, Version 2.0, January 2004
.Ve
