|
Packit Service |
d63224 |
NAME
|
|
Packit Service |
d63224 |
inc::latest - use modules bundled in inc/ if they are newer than
|
|
Packit Service |
d63224 |
installed ones
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
VERSION
|
|
Packit Service |
d63224 |
version 0.500
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
SYNOPSIS
|
|
Packit Service |
d63224 |
# in Makefile.PL or Build.PL
|
|
Packit Service |
d63224 |
use inc::latest 'Some::Configure::Prereq';
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
DESCRIPTION
|
|
Packit Service |
d63224 |
WARNING -- THIS IS AN EXPERIMENTAL MODULE. It was originally bundled (as
|
|
Packit Service |
d63224 |
an experiment) with Module::Build and has been split out for more
|
|
Packit Service |
d63224 |
general use.
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
The "inc::latest" module helps bootstrap configure-time dependencies for
|
|
Packit Service |
d63224 |
CPAN distributions. These dependencies get bundled into the "inc"
|
|
Packit Service |
d63224 |
directory within a distribution and are used by Makefile.PL or Build.PL.
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
Arguments to "inc::latest" are module names that are checked against
|
|
Packit Service |
d63224 |
both the current @INC array and against specially-named directories in
|
|
Packit Service |
d63224 |
"inc". If the bundled version is newer than the installed one (or the
|
|
Packit Service |
d63224 |
module isn't installed, then, the bundled directory is added to the
|
|
Packit Service |
d63224 |
start of @INC and the module is loaded from there.
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
There are actually two variations of "inc::latest" -- one for authors
|
|
Packit Service |
d63224 |
and one for the "inc" directory. For distribution authors, the
|
|
Packit Service |
d63224 |
"inc::latest" installed in the system will record modules loaded via
|
|
Packit Service |
d63224 |
"inc::latest" and can be used to create the bundled files in "inc",
|
|
Packit Service |
d63224 |
including writing the second variation as "inc/latest.pm".
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
This second "inc::latest" is the one that is loaded in a distribution
|
|
Packit Service |
d63224 |
being installed (e.g. from Makefile.PL or Build.PL). This bundled
|
|
Packit Service |
d63224 |
"inc::latest" is the one that determines which module to load.
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
Special notes on bundling
|
|
Packit Service |
d63224 |
The "inc::latest" module creates bundled directories based on the
|
|
Packit Service |
d63224 |
packlist file of an installed distribution. Even though "inc::latest"
|
|
Packit Service |
d63224 |
takes module name arguments, it is better to think of it as bundling and
|
|
Packit Service |
d63224 |
making available entire *distributions*. When a module is loaded through
|
|
Packit Service |
d63224 |
"inc::latest", it looks in all bundled distributions in "inc/" for a
|
|
Packit Service |
d63224 |
newer module than can be found in the existing @INC array.
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
Thus, the module-name provided should usually be the "top-level" module
|
|
Packit Service |
d63224 |
name of a distribution, though this is not strictly required.
|
|
Packit Service |
d63224 |
"inc::latest" has a number of heuristics to discover module names,
|
|
Packit Service |
d63224 |
allowing users to do things like this:
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
use inc::latest 'Devel::AssertOS::Unix';
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
even though Devel::AssertOS::Unix is contained within the Devel-CheckOS
|
|
Packit Service |
d63224 |
distribution.
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
At the current time, packlists are required. Thus, bundling dual-core
|
|
Packit Service |
d63224 |
modules may require a 'forced install' over versions in the latest
|
|
Packit Service |
d63224 |
version of perl in order to create the necessary packlist for bundling.
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
Managing dependency chains
|
|
Packit Service |
d63224 |
Before bundling a distribution you must ensure that all prerequisites
|
|
Packit Service |
d63224 |
are also bundled and load in the correct order.
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
For example, if you need "Wibble", but "Wibble" depends on "Wobble", and
|
|
Packit Service |
d63224 |
you have bundled "Module::Build", your Build.PL might look like this:
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
use inc::latest 'Wobble';
|
|
Packit Service |
d63224 |
use inc::latest 'Wibble';
|
|
Packit Service |
d63224 |
use inc::latest 'Module::Build';
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
Module::Build->new(
|
|
Packit Service |
d63224 |
module_name => 'Foo::Bar',
|
|
Packit Service |
d63224 |
license => 'perl',
|
|
Packit Service |
d63224 |
)->create_build_script;
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
Authors are strongly suggested to limit the bundling of additional
|
|
Packit Service |
d63224 |
dependencies if at all possible and to carefully test their distribution
|
|
Packit Service |
d63224 |
tarballs before uploading to CPAN.
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
USAGE
|
|
Packit Service |
d63224 |
As bundled in inc/
|
|
Packit Service |
d63224 |
Using "Author-mode", a special stub module will be created in your
|
|
Packit Service |
d63224 |
distribute directory as inc/latest.pm. In your Makefile.PL or Build.PL,
|
|
Packit Service |
d63224 |
you can then load "inc::latest" to load bundled modules.
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
When calling "use", the bundled "inc::latest" takes a single module name
|
|
Packit Service |
d63224 |
and optional arguments to pass to that module's own import method.
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
use inc::latest 'Foo::Bar' qw/foo bar baz/;
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
The implementation is private. Only the "import" method is public.
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
Author-mode
|
|
Packit Service |
d63224 |
When you have inc::latest installed from CPAN, then you are in
|
|
Packit Service |
d63224 |
author-mode if any of the Author-mode methods are available. For
|
|
Packit Service |
d63224 |
example:
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
if ( inc::latest->can('write') ) {
|
|
Packit Service |
d63224 |
inc::latest->write('inc');
|
|
Packit Service |
d63224 |
}
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
Using author-mode, you can create the stub inc/latest.pm and bundle
|
|
Packit Service |
d63224 |
modules into inc.
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
loaded_modules()
|
|
Packit Service |
d63224 |
my @list = inc::latest->loaded_modules;
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
This takes no arguments and always returns a list of module names
|
|
Packit Service |
d63224 |
requested for loading via "use inc::latest 'MODULE'", regardless of
|
|
Packit Service |
d63224 |
whether the load was successful or not.
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
write()
|
|
Packit Service |
d63224 |
inc::latest->write( 'inc' );
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
This writes the bundled version of inc::latest to the directory name
|
|
Packit Service |
d63224 |
given as an argument. It almost all cases, it should be '"inc"'.
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
bundle_module()
|
|
Packit Service |
d63224 |
for my $mod ( inc::latest->loaded_modules ) {
|
|
Packit Service |
d63224 |
inc::latest->bundle_module($mod, $dir);
|
|
Packit Service |
d63224 |
}
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
If $mod corresponds to a packlist, then this function creates a
|
|
Packit Service |
d63224 |
specially-named directory in $dir and copies all .pm files from the
|
|
Packit Service |
d63224 |
modlist to the new directory (which almost always should just be
|
|
Packit Service |
d63224 |
'inc'). For example, if Foo::Bar is the name of the module, and $dir
|
|
Packit Service |
d63224 |
is 'inc', then the directory would be 'inc/inc_Foo-Bar' and contain
|
|
Packit Service |
d63224 |
files like this:
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
inc/inc_Foo-Bar/Foo/Bar.pm
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
Currently, $mod must have a packlist. If this is not the case (e.g.
|
|
Packit Service |
d63224 |
for a dual-core module), then the bundling will fail. You may be
|
|
Packit Service |
d63224 |
able to create a packlist by forced installing the module on top of
|
|
Packit Service |
d63224 |
the version that came with core Perl.
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
SUPPORT
|
|
Packit Service |
d63224 |
Bugs / Feature Requests
|
|
Packit Service |
d63224 |
Please report any bugs or feature requests through the issue tracker at
|
|
Packit Service |
d63224 |
<https://github.com/dagolden/inc-latest/issues>. You will be notified
|
|
Packit Service |
d63224 |
automatically of any progress on your issue.
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
Source Code
|
|
Packit Service |
d63224 |
This is open source software. The code repository is available for
|
|
Packit Service |
d63224 |
public review and contribution under the terms of the license.
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
<https://github.com/dagolden/inc-latest>
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
git clone https://github.com/dagolden/inc-latest.git
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
AUTHORS
|
|
Packit Service |
d63224 |
* David Golden <dagolden@cpan.org>
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
* Eric Wilhelm <ewilhelm@cpan.org>
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
COPYRIGHT AND LICENSE
|
|
Packit Service |
d63224 |
This software is Copyright (c) 2009 by David Golden.
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
This is free software, licensed under:
|
|
Packit Service |
d63224 |
|
|
Packit Service |
d63224 |
The Apache License, Version 2.0, January 2004
|
|
Packit Service |
d63224 |
|