1inc::latest(3) User Contributed Perl Documentation inc::latest(3)
2
6 inc::latest - use modules bundled in inc/ if they are newer than
7 installed ones
8
10 version 0.500
11
13 # in Makefile.PL or Build.PL
14 use inc::latest 'Some::Configure::Prereq';
15
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 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 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 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 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 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 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 use inc::latest 'Devel::AssertOS::Unix';
56 even though Devel::AssertOS::Unix is contained within the Devel-CheckOS
58 distribution.
59 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 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 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 use inc::latest 'Wobble';
73 use inc::latest 'Wibble';
74 use inc::latest 'Module::Build';
75 Module::Build->new(
77 module_name => 'Foo::Bar',
78 license => 'perl',
79 )->create_build_script;
80 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
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 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 use inc::latest 'Foo::Bar' qw/foo bar baz/;
95 The implementation is private. Only the "import" method is public.
97 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 if ( inc::latest->can('write') ) {
103 inc::latest->write('inc');
104 }
105 Using author-mode, you can create the stub inc/latest.pm and bundle
107 modules into inc.
108 loaded_modules()
110 my @list = inc::latest->loaded_modules;
111 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 write()
117 inc::latest->write( 'inc' );
118 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 bundle_module()
124 for my $mod ( inc::latest->loaded_modules ) {
125 inc::latest->bundle_module($mod, $dir);
126 }
127 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 inc/inc_Foo-Bar/Foo/Bar.pm
136 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
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 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 <https://github.com/dagolden/inc-latest>
153 git clone https://github.com/dagolden/inc-latest.git
155
157 • David Golden <dagolden@cpan.org>
158 • Eric Wilhelm <ewilhelm@cpan.org>
160
162 This software is Copyright (c) 2009 by David Golden.
163 This is free software, licensed under:
165 The Apache License, Version 2.0, January 2004
167perl v5.36.0 2023-01-20 inc::latest(3)