1inc::latest(3pm)       Perl Programmers Reference Guide       inc::latest(3pm)
2
3
4

NAME

6       inc::latest - use modules bundled in inc/ if they are newer than
7       installed ones
8

SYNOPSIS

10         # in Build.PL
11         use inc::latest 'Module::Build';
12

DESCRIPTION

14       The "inc::latest" module helps bootstrap configure-time dependencies
15       for CPAN distributions.  These dependencies get bundled into the "inc"
16       directory within a distribution and are used by Build.PL (or
17       Makefile.PL).
18
19       Arguments to "inc::latest" are module names that are checked against
20       both the current @INC array and against specially-named directories in
21       "inc".  If the bundled verison is newer than the installed one (or the
22       module isn't installed, then, the bundled directory is added to the
23       start of <@INC> and the module is loaded from there.
24
25       There are actually two variations of "inc::latest" -- one for authors
26       and one for the "inc" directory.  For distribution authors, the
27       "inc::latest" installed in the system will record modules loaded via
28       "inc::latest" and can be used to create the bundled files in "inc",
29       including writing the second variation as "inc/latest.pm".
30
31       This second "inc::latest" is the one that is loaded in a distribution
32       being installed (e.g. from Build.PL).  This bundled "inc::latest" is
33       the one that determines which module to load.
34
35   Special notes on bundling
36       The "inc::latest" module creates bundled directories based on the
37       packlist file of an installed distribution.  Even though "inc::latest"
38       takes module name arguments, it is better to think of it as bundling
39       and making available entire distributions.  When a module is loaded
40       through "inc::latest", it looks in all bundled distributions in "inc/"
41       for a newer module than can be found in the existing @INC array.
42
43       Thus, the module-name provided should usually be the "top-level" module
44       name of a distribution, though this is not strictly required.  For
45       example, Module::Build has a number of heuristics to map module names
46       to packlists, allowing users to do things like this:
47
48         use inc::latest 'Devel::AssertOS::Unix';
49
50       even though Devel::AssertOS::Unix is contained within the Devel-CheckOS
51       distribution.
52
53       At the current time, packlists are required.  Thus, bundling dual-core
54       modules may require a 'forced install' over versions in the latest
55       version of perl in order to create the necessary packlist for bundling.
56

USAGE

58       When calling "use", the bundled "inc::latest" takes a single module
59       name and optional arguments to pass to that module's own import method.
60
61         use 'inc::latest' 'Foo::Bar' qw/foo bar baz/;
62
63   Author-mode
64       You are in author-mode inc::latest if any of the Author-mode methods
65       are available.  For example:
66
67         if ( inc::latest->can('write') ) {
68           inc::latest->write('inc');
69         }
70
71       loaded_modules()
72             my @list = inc::latest->loaded_modules;
73
74           This takes no arguments and always returns a list of module names
75           requested for loading via "use inc::latest 'MODULE'", regardless of
76           wether the load was successful or not.
77
78       write()
79             inc::latest->write( 'inc' );
80
81           This writes the bundled version of inc::latest to the directory
82           name given as an argument.  It almost all cases, it should be
83           '"inc"'.
84
85       bundle_module()
86             for my $mod ( inc::latest->loaded_modules ) {
87               inc::latest->bundle_module($mod, $dir);
88             }
89
90           If $mod corresponds to a packlist, then this function creates a
91           specially-named directory in $dir and copies all .pm files from the
92           modlist to the new directory (which almost always should just be
93           'inc').  For example, if Foo::Bar is the name of the module, and
94           $dir is 'inc', then the directory would be 'inc/inc_Foo-Bar' and
95           contain files like this:
96
97             inc/inc_Foo-Bar/Foo/Bar.pm
98
99           Currently, $mod must have a packlist.  If this is not the case
100           (e.g. for a dual-core module), then the bundling will fail.  You
101           may be able to create a packlist by forced installing the module on
102           top of the version that came with core Perl.
103
104   As bundled in inc/
105       All methods are private.  Only the "import" method is public.
106

AUTHOR

108       Eric Wilhelm <ewilhelm@cpan.org>, David Golden <dagolden@cpan.org>
109

111       Copyright (c) 2009 by Eric Wilhelm and David Golden
112
113       This library is free software; you can redistribute it and/or modify it
114       under the same terms as Perl itself.
115

SEE ALSO

117       Module::Build
118
119
120
121perl v5.12.4                      2011-06-07                  inc::latest(3pm)
Impressum