| =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<WARNING -- THIS IS AN EXPERIMENTAL FEATURE> |
| |
| 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<configure_requires> metadata field. This field is supported by |
| recent versions L<CPAN> and L<CPANPLUS> and is a standard feature |
| in the Perl core as of Perl 5.10.1. Module::Build now adds itself |
| to C<configure_requires> 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<inc/> directory. This is the same approach |
| used by L<Module::Install>, 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<inc/> 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 new L<inc::latest> module. |
| |
| 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<authors>, when "Build dist" is run, Module::Build will be |
| automatically bundled into C<inc> according to the rules for |
| L<inc::latest>. |
| |
| For I<users>, inc::latest will load the latest Module::Build, whether |
| installed or bundled in C<inc/>. |
| |
| =head1 BUNDLING OTHER CONFIGURATION DEPENDENCIES |
| |
| The same approach works for other configuration dependencies -- modules |
| that I<must> 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<Devel::AssertOS::Unix> 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<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>. When a module is loaded through |
| C<inc::latest>, it looks in all bundled distributions in C<inc/> 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<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, I<including Module::Build>, 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<Wibble>, but C<Wibble> depends on C<Wobble>, |
| 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 <dagolden@cpan.org> |
| |
| Development questions, bug reports, and patches should be sent to the |
| Module-Build mailing list at <module-build@perl.org>. |
| |
| Bug reports are also welcome at |
| <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>. |
| |
| =head1 SEE ALSO |
| |
| perl(1), L<inc::latest>, L<Module::Build>(3), L<Module::Build::API>(3), |
| L<Module::Build::Cookbook>(3), |
| |
| =cut |
| |
| # vim: tw=75 |