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 There are three basic types of prerequisites that can be defined: 1)
145 "requires" - are versions of modules that are required for certain
146 functionality to be available; 2) "recommends" - are versions of
147 modules that are recommended to provide enhanced functionality; and 3)
148 "conflicts" - are versions of modules that conflict with, and that can
149 cause problems with the distribution.
151 Each of the three types of prerequisites listed above can be applied
152 to different aspects of the Build process. For the module distribution
153 itself you simply define "requires", "recommends", or "conflicts". The
154 types can also apply to other aspects of the Build process. Currently,
155 only "build_requires" is defined which is used for modules which are
156 required during the Build process.
159 =head2 Format of prerequisites
161 The prerequisites are given in a hash reference, where the keys are
162 the module names and the values are version specifiers:
165 Foo::Module => '2.4',
167 Ken::Module => '>= 1.2, != 1.5, < 2.0',
171 These four version specifiers have different effects. The value
172 C<'2.4'> means that B<at least> version 2.4 of C<Foo::Module> must be
173 installed. The value C<0> means that B<any> version of C<Bar::Module>
174 is acceptable, even if C<Bar::Module> doesn't define a version. The
175 more verbose value C<'E<gt>= 1.2, != 1.5, E<lt> 2.0'> means that
176 C<Ken::Module>'s version must be B<at least> 1.2, B<less than> 2.0,
177 and B<not equal to> 1.5. The list of criteria is separated by commas,
178 and all criteria must be satisfied.
180 A special C<perl> entry lets you specify the versions of the Perl
181 interpreter that are supported by your module. The same version
182 dependency-checking semantics are available, except that we also
183 understand perl's new double-dotted version numbers.
186 =head1 SAVING CONFIGURATION INFORMATION
188 Module::Build provides a very convenient way to save configuration
189 information that your installed modules (or your regression tests) can
190 access. If your Build process calls the C<feature()> or
191 C<config_data()> methods, then a C<Foo::Bar::ConfigData> module will
192 automatically be created for you, where C<Foo::Bar> is the
193 C<module_name> parameter as passed to C<new()>. This module provides
194 access to the data saved by these methods, and a way to update the
195 values. There is also a utility script called C<config_data>
196 distributed with Module::Build that provides a command line interface
197 to this same functionality. See also the generated
198 C<Foo::Bar::ConfigData> documentation, and the C<config_data>
199 script's documentation, for more information.
202 =head1 STARTING MODULE DEVELOPMENT
204 When starting development on a new module, it's rarely worth your time
205 to create a tree of all the files by hand. Some automatic
206 module-creators are available: the oldest is C<h2xs>, which has
207 shipped with perl itself for a long time. Its name reflects the fact
208 that modules were originally conceived of as a way to wrap up a C
209 library (thus the C<h> part) into perl extensions (thus the C<xs>
212 These days, C<h2xs> has largely been superseded by modules like
213 C<ExtUtils::ModuleMaker>, C<Module::Starter>, and C<Module::Maker>.
214 They have varying degrees of support for C<Module::Build>.
219 One advantage of Module::Build is that since it's implemented as Perl
220 methods, you can invoke these methods directly if you want to install
221 a module non-interactively. For instance, the following Perl script
222 will invoke the entire build/install procedure:
224 my $build = Module::Build->new(module_name => 'MyModule');
225 $build->dispatch('build');
226 $build->dispatch('test');
227 $build->dispatch('install');
229 If any of these steps encounters an error, it will throw a fatal
232 You can also pass arguments as part of the build process:
234 my $build = Module::Build->new(module_name => 'MyModule');
235 $build->dispatch('build');
236 $build->dispatch('test', verbose => 1);
237 $build->dispatch('install', sitelib => '/my/secret/place/');
239 Building and installing modules in this way skips creating the
245 Note that if you want to provide both a F<Makefile.PL> and a
246 F<Build.PL> for your distribution, you probably want to add the
247 following to C<WriteMakefile> in your F<Makefile.PL> so that MakeMaker
248 doesn't try to run your F<Build.PL> as a normal F<.PL> file:
252 You may also be interested in looking at the C<Module::Build::Compat>
253 module, which can automatically create various kinds of F<Makefile.PL>
254 compatibility layers.
259 Ken Williams <kwilliams@cpan.org>
261 Development questions, bug reports, and patches should be sent to the
262 Module-Build mailing list at <module-build@perl.org>.
264 Bug reports are also welcome at
265 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>.
267 The latest development version is available from the Subversion
268 repository at <https://svn.perl.org/modules/Module-Build/trunk/>
273 perl(1), L<Module::Build>(3), L<Module::Build::API>(3),
274 L<Module::Build::Cookbook>(3), L<ExtUtils::MakeMaker>(3), L<YAML>(3)
276 F<META.yml> Specification:
277 L<http://module-build.sourceforge.net/META-spec-current.html>
279 L<http://www.dsmit.com/cons/>
281 L<http://search.cpan.org/dist/PerlBuildSystem/>