1=head1 NAME
2
3Module::Build::Bundling - How to bundle Module::Build with a distribution
4
5=head1 SYNOPSIS
6
7  # Build.PL
8  use inc::latest 'Module::Build';
9
10  Module::Build->new(
11    module_name => 'Foo::Bar',
12    license => 'perl',
13  )->create_build_script;
14
15=head1 DESCRIPTION
16
17B<WARNING -- THIS IS AN EXPERIMENTAL FEATURE>
18
19In order to install a distribution using Module::Build, users must
20have Module::Build available on their systems.  There are two ways
21to do this.  The first way is to include Module::Build in the
22C<configure_requires> metadata field.  This field is supported by
23recent versions L<CPAN> and L<CPANPLUS> and is a standard feature
24in the Perl core as of Perl 5.10.1.  Module::Build now adds itself
25to C<configure_requires> by default.
26
27The second way supports older Perls that have not upgraded CPAN or
28CPANPLUS and involves bundling an entire copy of Module::Build
29into the distribution's C<inc/> directory.  This is the same approach
30used by L<Module::Install>, a modern wrapper around ExtUtils::MakeMaker
31for Makefile.PL based distributions.
32
33The "trick" to making this work for Module::Build is making sure the
34highest version Module::Build is used, whether this is in C<inc/> or
35already installed on the user's system.  This ensures that all necessary
36features are available as well as any new bug fixes.  This is done using
37the experimental L<inc::latest> module, available on CPAN.
38
39A "normal" Build.PL looks like this (with only the minimum required
40fields):
41
42  use Module::Build;
43
44  Module::Build->new(
45    module_name => 'Foo::Bar',
46    license     => 'perl',
47  )->create_build_script;
48
49A "bundling" Build.PL replaces the initial "use" line with a nearly
50transparent replacement:
51
52  use inc::latest 'Module::Build';
53
54  Module::Build->new(
55    module_name => 'Foo::Bar',
56    license => 'perl',
57  )->create_build_script;
58
59For I<authors>, when "Build dist" is run, Module::Build will be
60automatically bundled into C<inc> according to the rules for
61L<inc::latest>.
62
63For I<users>, inc::latest will load the latest Module::Build, whether
64installed or bundled in C<inc/>.
65
66=head1 BUNDLING OTHER CONFIGURATION DEPENDENCIES
67
68The same approach works for other configuration dependencies -- modules
69that I<must> be available for Build.PL to run.  All other dependencies can
70be specified as usual in the Build.PL and CPAN or CPANPLUS will install
71them after Build.PL finishes.
72
73For example, to bundle the L<Devel::AssertOS::Unix> module (which ensures a
74"Unix-like" operating system), one could do this:
75
76  use inc::latest 'Devel::AssertOS::Unix';
77  use inc::latest 'Module::Build';
78
79  Module::Build->new(
80    module_name => 'Foo::Bar',
81    license => 'perl',
82  )->create_build_script;
83
84The C<inc::latest> module creates bundled directories based on the packlist
85file of an installed distribution.  Even though C<inc::latest> takes module
86name arguments, it is better to think of it as bundling and making
87available entire I<distributions>.  When a module is loaded through
88C<inc::latest>, it looks in all bundled distributions in C<inc/> for a
89newer module than can be found in the existing C<@INC> array.
90
91Thus, the module-name provided should usually be the "top-level" module
92name of a distribution, though this is not strictly required.  For example,
93L<Module::Build> has a number of heuristics to map module names to
94packlists, allowing users to do things like this:
95
96  use inc::latest 'Devel::AssertOS::Unix';
97
98even though Devel::AssertOS::Unix is contained within the Devel-CheckOS
99distribution.
100
101At the current time, packlists are required.  Thus, bundling dual-core
102modules, I<including Module::Build>, may require a 'forced install' over
103versions in the latest version of perl in order to create the necessary
104packlist for bundling.  This limitation will hopefully be addressed in a
105future version of Module::Build.
106
107=head2 WARNING -- How to Manage Dependency Chains
108
109Before bundling a distribution you must ensure that all prerequisites are
110also bundled and load in the correct order.  For Module::Build itself, this
111should not be necessary, but it is necessary for any other distribution.
112(A future release of Module::Build will hopefully address this deficiency.)
113
114For example, if you need C<Wibble>, but C<Wibble> depends on C<Wobble>,
115your Build.PL might look like this:
116
117  use inc::latest 'Wobble';
118  use inc::latest 'Wibble';
119  use inc::latest 'Module::Build';
120
121  Module::Build->new(
122    module_name => 'Foo::Bar',
123    license => 'perl',
124  )->create_build_script;
125
126Authors are strongly suggested to limit the bundling of additional
127dependencies if at all possible and to carefully test their distribution
128tarballs on older versions of Perl before uploading to CPAN.
129
130=head1 AUTHOR
131
132David Golden <dagolden@cpan.org>
133
134Development questions, bug reports, and patches should be sent to the
135Module-Build mailing list at <module-build@perl.org>.
136
137Bug reports are also welcome at
138<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>.
139
140=head1 SEE ALSO
141
142perl(1), L<inc::latest>, L<Module::Build>(3), L<Module::Build::API>(3),
143L<Module::Build::Cookbook>(3),
144
145=cut
146
147# vim: tw=75
148