3 Module::Build::Authoring - Authoring Module::Build modules
8 When creating a C<Build.PL> script for a module, something like the
9 following code will typically be used:
12 my $build = Module::Build->new
14 module_name => 'Foo::Bar',
18 'Some::Module' => '1.23',
19 'Other::Module' => '>= 1.2, != 1.5, < 2.0',
22 $build->create_build_script;
24 A simple module could get away with something as short as this for its
29 module_name => 'Foo::Bar',
31 )->create_build_script;
33 The model used by C<Module::Build> is a lot like the C<MakeMaker>
34 metaphor, with the following correspondences:
36 In Module::Build In ExtUtils::MakeMaker
37 --------------------------- ------------------------
38 Build.PL (initial script) Makefile.PL (initial script)
39 Build (a short perl script) Makefile (a long Makefile)
40 _build/ (saved state info) various config text in the Makefile
42 Any customization can be done simply by subclassing C<Module::Build>
43 and adding a method called (for example) C<ACTION_test>, overriding
44 the default 'test' action. You could also add a method called
45 C<ACTION_whatever>, and then you could perform the action C<Build
48 For information on providing compatibility with
49 C<ExtUtils::MakeMaker>, see L<Module::Build::Compat> and
50 L<http://www.makemaker.org/wiki/index.cgi?ModuleBuildConversionGuide>.
55 Module::Build creates a class hierarchy conducive to customization.
56 Here is the parent-child class hierarchy in classy ASCII art:
58 /--------------------\
59 | Your::Parent | (If you subclass Module::Build)
60 \--------------------/
63 /--------------------\ (Doesn't define any functionality
64 | Module::Build | of its own - just figures out what
65 \--------------------/ other modules to load.)
68 /-----------------------------------\ (Some values of $^O may
69 | Module::Build::Platform::$^O | define specialized functionality.
70 \-----------------------------------/ Otherwise it's ...::Default, a
71 | pass-through class.)
73 /--------------------------\
74 | Module::Build::Base | (Most of the functionality of
75 \--------------------------/ Module::Build is defined here.)
80 Right now, there are two ways to subclass Module::Build. The first
81 way is to create a regular module (in a C<.pm> file) that inherits
82 from Module::Build, and use that module's class instead of using
83 Module::Build directly:
85 ------ in Build.PL: ----------
88 use lib q(/nonstandard/library/path);
89 use My::Builder; # Or whatever you want to call it
91 my $build = My::Builder->new
93 module_name => 'Foo::Bar', # All the regular args...
95 dist_author => 'A N Other <me@here.net.au>',
96 requires => { Carp => 0 }
98 $build->create_build_script;
100 This is relatively straightforward, and is the best way to do things
101 if your My::Builder class contains lots of code. The
102 C<create_build_script()> method will ensure that the current value of
103 C<@INC> (including the C</nonstandard/library/path>) is propogated to
104 the Build script, so that My::Builder can be found when running build
107 For very small additions, Module::Build provides a C<subclass()>
108 method that lets you subclass Module::Build more conveniently, without
109 creating a separate file for your module:
111 ------ in Build.PL: ----------
115 my $class = Module::Build->subclass
117 class => 'My::Builder',
120 print "I'm fooing to death!\n";
125 my $build = $class->new
127 module_name => 'Foo::Bar', # All the regular args...
129 dist_author => 'A N Other <me@here.net.au>',
130 requires => { Carp => 0 }
132 $build->create_build_script;
134 Behind the scenes, this actually does create a C<.pm> file, since the
135 code you provide must persist after Build.PL is run if it is to be
138 See also the documentation for the L<Module::Build::API/"subclass()">
144 =head2 Types of prerequisites
146 To specify what versions of other modules are used by this
147 distribution, several types of prerequisites can be defined with the
148 following parameters:
152 =item configure_requires
154 Items that must be installed I<before> configuring this distribution
155 (i.e. before running the F<Build.PL> script). This might be a
156 specific minimum version of C<Module::Build> or any other module the
157 F<Build.PL> needs in order to do its stuff. Clients like C<CPAN.pm>
158 or C<CPANPLUS> will be expected to pick C<configure_requires> out of the
159 F<META.yml> file and install these items before running the
162 *TODO* auto-add M::B? In what circumstances?
166 Items that are necessary for building and testing this distribution,
167 but aren't necessary after installation. This can help users who only
168 want to install these items temporarily. It also helps reduce the
169 size of the CPAN dependency graph if everything isn't smooshed into
174 Items that are necessary for basic functioning.
178 Items that are recommended for enhanced functionality, but there are
179 ways to use this distribution without having them installed. You
180 might also think of this as "can use" or "is aware of" or "changes
181 behavior in the presence of".
185 Items that can cause problems with this distribution when installed.
190 =head2 Format of prerequisites
192 The prerequisites are given in a hash reference, where the keys are
193 the module names and the values are version specifiers:
196 Foo::Module => '2.4',
198 Ken::Module => '>= 1.2, != 1.5, < 2.0',
202 The above four version specifiers have different effects. The value
203 C<'2.4'> means that B<at least> version 2.4 of C<Foo::Module> must be
204 installed. The value C<0> means that B<any> version of C<Bar::Module>
205 is acceptable, even if C<Bar::Module> doesn't define a version. The
206 more verbose value C<'E<gt>= 1.2, != 1.5, E<lt> 2.0'> means that
207 C<Ken::Module>'s version must be B<at least> 1.2, B<less than> 2.0,
208 and B<not equal to> 1.5. The list of criteria is separated by commas,
209 and all criteria must be satisfied.
211 A special C<perl> entry lets you specify the versions of the Perl
212 interpreter that are supported by your module. The same version
213 dependency-checking semantics are available, except that we also
214 understand perl's new double-dotted version numbers.
218 Modules which need to compile XS code should list C<ExtUtils::CBuilder>
219 as a C<build_requires> element.
222 =head1 SAVING CONFIGURATION INFORMATION
224 Module::Build provides a very convenient way to save configuration
225 information that your installed modules (or your regression tests) can
226 access. If your Build process calls the C<feature()> or
227 C<config_data()> methods, then a C<Foo::Bar::ConfigData> module will
228 automatically be created for you, where C<Foo::Bar> is the
229 C<module_name> parameter as passed to C<new()>. This module provides
230 access to the data saved by these methods, and a way to update the
231 values. There is also a utility script called C<config_data>
232 distributed with Module::Build that provides a command line interface
233 to this same functionality. See also the generated
234 C<Foo::Bar::ConfigData> documentation, and the C<config_data>
235 script's documentation, for more information.
238 =head1 STARTING MODULE DEVELOPMENT
240 When starting development on a new module, it's rarely worth your time
241 to create a tree of all the files by hand. Some automatic
242 module-creators are available: the oldest is C<h2xs>, which has
243 shipped with perl itself for a long time. Its name reflects the fact
244 that modules were originally conceived of as a way to wrap up a C
245 library (thus the C<h> part) into perl extensions (thus the C<xs>
248 These days, C<h2xs> has largely been superseded by modules like
249 C<ExtUtils::ModuleMaker>, and C<Module::Starter>. They have varying
250 degrees of support for C<Module::Build>.
255 One advantage of Module::Build is that since it's implemented as Perl
256 methods, you can invoke these methods directly if you want to install
257 a module non-interactively. For instance, the following Perl script
258 will invoke the entire build/install procedure:
260 my $build = Module::Build->new(module_name => 'MyModule');
261 $build->dispatch('build');
262 $build->dispatch('test');
263 $build->dispatch('install');
265 If any of these steps encounters an error, it will throw a fatal
268 You can also pass arguments as part of the build process:
270 my $build = Module::Build->new(module_name => 'MyModule');
271 $build->dispatch('build');
272 $build->dispatch('test', verbose => 1);
273 $build->dispatch('install', sitelib => '/my/secret/place/');
275 Building and installing modules in this way skips creating the
281 Note that if you want to provide both a F<Makefile.PL> and a
282 F<Build.PL> for your distribution, you probably want to add the
283 following to C<WriteMakefile> in your F<Makefile.PL> so that MakeMaker
284 doesn't try to run your F<Build.PL> as a normal F<.PL> file:
288 You may also be interested in looking at the C<Module::Build::Compat>
289 module, which can automatically create various kinds of F<Makefile.PL>
290 compatibility layers.
295 Ken Williams <kwilliams@cpan.org>
297 Development questions, bug reports, and patches should be sent to the
298 Module-Build mailing list at <module-build@perl.org>.
300 Bug reports are also welcome at
301 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>.
303 The latest development version is available from the Subversion
304 repository at <https://svn.perl.org/modules/Module-Build/trunk/>
309 perl(1), L<Module::Build>(3), L<Module::Build::API>(3),
310 L<Module::Build::Cookbook>(3), L<ExtUtils::MakeMaker>(3), L<YAML>(3)
312 F<META.yml> Specification:
313 L<http://module-build.sourceforge.net/META-spec-current.html>
315 L<http://www.dsmit.com/cons/>
317 L<http://search.cpan.org/dist/PerlBuildSystem/>