From 467298a34215401cdcbb1dded51bc2aba5f1f41c Mon Sep 17 00:00:00 2001 From: Lorry Tar Creator Date: Thu, 11 Jun 2015 22:32:06 +0000 Subject: Module-Build-0.4214 --- lib/Module/Build/Bundling.pod | 147 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 lib/Module/Build/Bundling.pod (limited to 'lib/Module/Build/Bundling.pod') diff --git a/lib/Module/Build/Bundling.pod b/lib/Module/Build/Bundling.pod new file mode 100644 index 0000000..98f2de3 --- /dev/null +++ b/lib/Module/Build/Bundling.pod @@ -0,0 +1,147 @@ +=head1 NAME + +Module::Build::Bundling - How to bundle Module::Build with a distribution + +=head1 SYNOPSIS + + # Build.PL + use inc::latest 'Module::Build'; + + Module::Build->new( + module_name => 'Foo::Bar', + license => 'perl', + )->create_build_script; + +=head1 DESCRIPTION + +B + +In order to install a distribution using Module::Build, users must +have Module::Build available on their systems. There are two ways +to do this. The first way is to include Module::Build in the +C metadata field. This field is supported by +recent versions L and L and is a standard feature +in the Perl core as of Perl 5.10.1. Module::Build now adds itself +to C by default. + +The second way supports older Perls that have not upgraded CPAN or +CPANPLUS and involves bundling an entire copy of Module::Build +into the distribution's C directory. This is the same approach +used by L, a modern wrapper around ExtUtils::MakeMaker +for Makefile.PL based distributions. + +The "trick" to making this work for Module::Build is making sure the +highest version Module::Build is used, whether this is in C or +already installed on the user's system. This ensures that all necessary +features are available as well as any new bug fixes. This is done using +the experimental L module, available on CPAN. + +A "normal" Build.PL looks like this (with only the minimum required +fields): + + use Module::Build; + + Module::Build->new( + module_name => 'Foo::Bar', + license => 'perl', + )->create_build_script; + +A "bundling" Build.PL replaces the initial "use" line with a nearly +transparent replacement: + + use inc::latest 'Module::Build'; + + Module::Build->new( + module_name => 'Foo::Bar', + license => 'perl', + )->create_build_script; + +For I, when "Build dist" is run, Module::Build will be +automatically bundled into C according to the rules for +L. + +For I, inc::latest will load the latest Module::Build, whether +installed or bundled in C. + +=head1 BUNDLING OTHER CONFIGURATION DEPENDENCIES + +The same approach works for other configuration dependencies -- modules +that I be available for Build.PL to run. All other dependencies can +be specified as usual in the Build.PL and CPAN or CPANPLUS will install +them after Build.PL finishes. + +For example, to bundle the L module (which ensures a +"Unix-like" operating system), one could do this: + + use inc::latest 'Devel::AssertOS::Unix'; + use inc::latest 'Module::Build'; + + Module::Build->new( + module_name => 'Foo::Bar', + license => 'perl', + )->create_build_script; + +The C module creates bundled directories based on the packlist +file of an installed distribution. Even though C takes module +name arguments, it is better to think of it as bundling and making +available entire I. When a module is loaded through +C, it looks in all bundled distributions in C for a +newer module than can be found in the existing C<@INC> array. + +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 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, I, may require a 'forced install' over +versions in the latest version of perl in order to create the necessary +packlist for bundling. This limitation will hopefully be addressed in a +future version of Module::Build. + +=head2 WARNING -- How to Manage Dependency Chains + +Before bundling a distribution you must ensure that all prerequisites are +also bundled and load in the correct order. For Module::Build itself, this +should not be necessary, but it is necessary for any other distribution. +(A future release of Module::Build will hopefully address this deficiency.) + +For example, if you need C, but C depends on C, +your Build.PL might look like this: + + use inc::latest 'Wobble'; + use inc::latest 'Wibble'; + use inc::latest 'Module::Build'; + + Module::Build->new( + module_name => 'Foo::Bar', + license => 'perl', + )->create_build_script; + +Authors are strongly suggested to limit the bundling of additional +dependencies if at all possible and to carefully test their distribution +tarballs on older versions of Perl before uploading to CPAN. + +=head1 AUTHOR + +David Golden + +Development questions, bug reports, and patches should be sent to the +Module-Build mailing list at . + +Bug reports are also welcome at +. + +=head1 SEE ALSO + +perl(1), L, L(3), L(3), +L(3), + +=cut + +# vim: tw=75 -- cgit v1.2.1