1inc::latest(3)        User Contributed Perl Documentation       inc::latest(3)
2
3
4

NAME

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

VERSION

10       version 0.500
11

SYNOPSIS

13         # in Makefile.PL or Build.PL
14         use inc::latest 'Some::Configure::Prereq';
15

DESCRIPTION

17       WARNING -- THIS IS AN EXPERIMENTAL MODULE.  It was originally bundled
18       (as an experiment) with Module::Build and has been split out for more
19       general use.
20
21       The "inc::latest" module helps bootstrap configure-time dependencies
22       for CPAN distributions.  These dependencies get bundled into the "inc"
23       directory within a distribution and are used by Makefile.PL or
24       Build.PL.
25
26       Arguments to "inc::latest" are module names that are checked against
27       both the current @INC array and against specially-named directories in
28       "inc".  If the bundled version is newer than the installed one (or the
29       module isn't installed, then, the bundled directory is added to the
30       start of @INC and the module is loaded from there.
31
32       There are actually two variations of "inc::latest" -- one for authors
33       and one for the "inc" directory.  For distribution authors, the
34       "inc::latest" installed in the system will record modules loaded via
35       "inc::latest" and can be used to create the bundled files in "inc",
36       including writing the second variation as "inc/latest.pm".
37
38       This second "inc::latest" is the one that is loaded in a distribution
39       being installed (e.g. from Makefile.PL or Build.PL).  This bundled
40       "inc::latest" is the one that determines which module to load.
41
42   Special notes on bundling
43       The "inc::latest" module creates bundled directories based on the
44       packlist file of an installed distribution.  Even though "inc::latest"
45       takes module name arguments, it is better to think of it as bundling
46       and making available entire distributions.  When a module is loaded
47       through "inc::latest", it looks in all bundled distributions in "inc/"
48       for a newer module than can be found in the existing @INC array.
49
50       Thus, the module-name provided should usually be the "top-level" module
51       name of a distribution, though this is not strictly required.
52       "inc::latest" has a number of heuristics to discover module names,
53       allowing users to do things like this:
54
55         use inc::latest 'Devel::AssertOS::Unix';
56
57       even though Devel::AssertOS::Unix is contained within the Devel-CheckOS
58       distribution.
59
60       At the current time, packlists are required.  Thus, bundling dual-core
61       modules may require a 'forced install' over versions in the latest
62       version of perl in order to create the necessary packlist for bundling.
63
64   Managing dependency chains
65       Before bundling a distribution you must ensure that all prerequisites
66       are also bundled and load in the correct order.
67
68       For example, if you need "Wibble", but "Wibble" depends on "Wobble",
69       and you have bundled "Module::Build", your Build.PL might look like
70       this:
71
72         use inc::latest 'Wobble';
73         use inc::latest 'Wibble';
74         use inc::latest 'Module::Build';
75
76         Module::Build->new(
77           module_name => 'Foo::Bar',
78           license => 'perl',
79         )->create_build_script;
80
81       Authors are strongly suggested to limit the bundling of additional
82       dependencies if at all possible and to carefully test their
83       distribution tarballs before uploading to CPAN.
84

USAGE

86   As bundled in inc/
87       Using "Author-mode", a special stub module will be created in your
88       distribute directory as inc/latest.pm.  In your Makefile.PL or
89       Build.PL, you can then load "inc::latest" to load bundled modules.
90
91       When calling "use", the bundled "inc::latest" takes a single module
92       name and optional arguments to pass to that module's own import method.
93
94         use inc::latest 'Foo::Bar' qw/foo bar baz/;
95
96       The implementation is private.  Only the "import" method is public.
97
98   Author-mode
99       When you have inc::latest installed from CPAN, then you are in author-
100       mode if any of the Author-mode methods are available.  For example:
101
102         if ( inc::latest->can('write') ) {
103           inc::latest->write('inc');
104         }
105
106       Using author-mode, you can create the stub inc/latest.pm and bundle
107       modules into inc.
108
109       loaded_modules()
110             my @list = inc::latest->loaded_modules;
111
112           This takes no arguments and always returns a list of module names
113           requested for loading via "use inc::latest 'MODULE'", regardless of
114           whether the load was successful or not.
115
116       write()
117             inc::latest->write( 'inc' );
118
119           This writes the bundled version of inc::latest to the directory
120           name given as an argument.  It almost all cases, it should be
121           '"inc"'.
122
123       bundle_module()
124             for my $mod ( inc::latest->loaded_modules ) {
125               inc::latest->bundle_module($mod, $dir);
126             }
127
128           If $mod corresponds to a packlist, then this function creates a
129           specially-named directory in $dir and copies all .pm files from the
130           modlist to the new directory (which almost always should just be
131           'inc').  For example, if Foo::Bar is the name of the module, and
132           $dir is 'inc', then the directory would be 'inc/inc_Foo-Bar' and
133           contain files like this:
134
135             inc/inc_Foo-Bar/Foo/Bar.pm
136
137           Currently, $mod must have a packlist.  If this is not the case
138           (e.g. for a dual-core module), then the bundling will fail.  You
139           may be able to create a packlist by forced installing the module on
140           top of the version that came with core Perl.
141

SUPPORT

143   Bugs / Feature Requests
144       Please report any bugs or feature requests through the issue tracker at
145       <https://github.com/dagolden/inc-latest/issues>.  You will be notified
146       automatically of any progress on your issue.
147
148   Source Code
149       This is open source software.  The code repository is available for
150       public review and contribution under the terms of the license.
151
152       <https://github.com/dagolden/inc-latest>
153
154         git clone https://github.com/dagolden/inc-latest.git
155

AUTHORS

157       •   David Golden <dagolden@cpan.org>
158
159       •   Eric Wilhelm <ewilhelm@cpan.org>
160
162       This software is Copyright (c) 2009 by David Golden.
163
164       This is free software, licensed under:
165
166         The Apache License, Version 2.0, January 2004
167
168
169
170perl v5.32.1                      2021-01-27                    inc::latest(3)
Impressum