Author: dagolden Date: Sun Sep 13 15:21:41 2009 New Revision: 13331 Modified: Module-Build/branches/inc-bundling/lib/inc/latest.pm
Log: write some docs for inc::latest Modified: Module-Build/branches/inc-bundling/lib/inc/latest.pm ============================================================================== --- Module-Build/branches/inc-bundling/lib/inc/latest.pm (original) +++ Module-Build/branches/inc-bundling/lib/inc/latest.pm Sun Sep 13 15:21:41 2009 @@ -93,6 +93,105 @@ 1; + +=head1 NAME + +inc::latest - use modules bundled in inc/ if they are newer than installed ones + +=head1 SYNOPSIS + + # in Build.PL + use inc::latest 'Module::Build'; + +=head1 DESCRIPTION + +The C<inc::latest> module helps bootstrap configure-time dependencies for CPAN +distributions. These dependencies get bundled into the C<inc> directory within +a distribution and are used by Build.PL (or Makefile.PL). + +Arguments to C<inc::latest> are module names that are checked against both the +current C<@INC> array and against specially-named directories in C<inc>. If +the bundled verison is newer than the installed one (or the module isn't +installed, then, the bundled directory is added to the start of <@INC> and the +module is loaded from there. + +There are actually two variations of C<inc::latest> -- one for authors and one +for the C<inc> directory. For distribution authors, the C<inc::latest> +installed in the system will record modules loaded via C<inc::latest> and can +be used to create the bundled files in C<inc>, including writing the second +variation as C<inc/latest.pm>. + +This second C<inc::latest> is the one that is loaded in a distribution being +installed (e.g. from Build.PL). This bundled C<inc::latest> is the one +that determines which module to load. + +=head2 Special notes on bundling + +The C<inc::latest> module creates bundled directories based on the packlist +file of an installed distribution. Even though C<inc::latest> takes module +name arguments, it is better to think of it as bundling and making available +entire I<distributions>. + +Thus, the module-name provided should usually be the "top-level" module name of +a distribution, though this is not strictly required. For example, +L<Module::Build> has a number of heuristics to map module names to packlists, +allowing users to do things like this: + + use inc::latest 'Devel::AssertOS::Unix'; + +even though Devel::AssertOS::Unix is contained within the Devel-CheckOS +distribution. + +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. + +=head1 USAGE + +When calling C<use>, the bundled C<inc::latest> takes a single module name and +optional arguments to pass to that module's own import method. + + use 'inc::latest' 'Foo::Bar' qw/foo bar baz/; + +=head2 Author-mode + +=over 4 + +=item loaded_modules() + +DOCUMENT THIS + +=item write() + +DOCUMENT THIS + +=item bundle_module() + +DOCUMENT THIS + +=back + +=head2 As bundled in inc/ + +All methods are private. Only the C<import> method is public. + +=head1 AUTHOR + +Eric Wilhelm <[email protected]>, David Golden <[email protected]> + +=head1 COPYRIGHT + +Copyright (c) 2009 by Eric Wilhelm and David Golden + +This library is free software; you can redistribute it and/or +modify it under the same terms as Perl itself. + +=head1 SEE ALSO + +L<Module::Build> + +=cut + __DATA__ package inc::latest;
