summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Module/Build/Bundling.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Module/Build/Bundling.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Module/Build/Bundling.pod147
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