diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Module/Build/Bundling.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/Module/Build/Bundling.pod | 147 |
1 files changed, 0 insertions, 147 deletions
diff --git a/Master/tlpkg/tlperl/lib/Module/Build/Bundling.pod b/Master/tlpkg/tlperl/lib/Module/Build/Bundling.pod deleted file mode 100644 index 5e7b9f98075..00000000000 --- a/Master/tlpkg/tlperl/lib/Module/Build/Bundling.pod +++ /dev/null @@ -1,147 +0,0 @@ -=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 |