1Module::Build::AuthoringP(e3rplm)Programmers ReferenceMGoudiudlee::Build::Authoring(3pm)
2
6 Module::Build::Authoring - Authoring Module::Build modules
7
9 When creating a "Build.PL" script for a module, something like the
10 following code will typically be used:
11 use Module::Build;
13 my $build = Module::Build->new
14 (
15 module_name => 'Foo::Bar',
16 license => 'perl',
17 requires => {
18 'perl' => '5.6.1',
19 'Some::Module' => '1.23',
20 'Other::Module' => '>= 1.2, != 1.5, < 2.0',
21 },
22 );
23 $build->create_build_script;
24 A simple module could get away with something as short as this for its
26 "Build.PL" script:
27 use Module::Build;
29 Module::Build->new(
30 module_name => 'Foo::Bar',
31 license => 'perl',
32 )->create_build_script;
33 The model used by "Module::Build" is a lot like the "MakeMaker"
35 metaphor, with the following correspondences:
36 In Module::Build In ExtUtils::MakeMaker
38 --------------------------- ------------------------
39 Build.PL (initial script) Makefile.PL (initial script)
40 Build (a short perl script) Makefile (a long Makefile)
41 _build/ (saved state info) various config text in the Makefile
42 Any customization can be done simply by subclassing "Module::Build" and
44 adding a method called (for example) "ACTION_test", overriding the
45 default 'test' action. You could also add a method called
46 "ACTION_whatever", and then you could perform the action "Build
47 whatever".
48 For information on providing compatibility with "ExtUtils::MakeMaker",
50 see Module::Build::Compat and
51 <http://www.makemaker.org/wiki/index.cgi?ModuleBuildConversionGuide>.
52
54 Module::Build creates a class hierarchy conducive to customization.
55 Here is the parent-child class hierarchy in classy ASCII art:
56 /--------------------\
58 | Your::Parent | (If you subclass Module::Build)
59 \--------------------/
60 |
61 |
62 /--------------------\ (Doesn't define any functionality
63 | Module::Build | of its own - just figures out what
64 \--------------------/ other modules to load.)
65 |
66 |
67 /-----------------------------------\ (Some values of $^O may
68 | Module::Build::Platform::$^O | define specialized functionality.
69 \-----------------------------------/ Otherwise it's ...::Default, a
70 | pass-through class.)
71 |
72 /--------------------------\
73 | Module::Build::Base | (Most of the functionality of
74 \--------------------------/ Module::Build is defined here.)
75
77 Right now, there are two ways to subclass Module::Build. The first way
78 is to create a regular module (in a ".pm" file) that inherits from
79 Module::Build, and use that module's class instead of using
80 Module::Build directly:
81 ------ in Build.PL: ----------
83 #!/usr/bin/perl
84 use lib q(/nonstandard/library/path);
86 use My::Builder; # Or whatever you want to call it
87 my $build = My::Builder->new
89 (
90 module_name => 'Foo::Bar', # All the regular args...
91 license => 'perl',
92 dist_author => 'A N Other <me@here.net.au>',
93 requires => { Carp => 0 }
94 );
95 $build->create_build_script;
96 This is relatively straightforward, and is the best way to do things if
98 your My::Builder class contains lots of code. The
99 "create_build_script()" method will ensure that the current value of
100 @INC (including the "/nonstandard/library/path") is propagated to the
101 Build script, so that My::Builder can be found when running build
102 actions. If you find that you need to "chdir" into a different
103 directories in your subclass methods or actions, be sure to always
104 return to the original directory (available via the "base_dir()" method
105 before returning control to the parent class. This is important to
106 avoid data serialization problems.
107 For very small additions, Module::Build provides a "subclass()" method
109 that lets you subclass Module::Build more conveniently, without
110 creating a separate file for your module:
111 ------ in Build.PL: ----------
113 #!/usr/bin/perl
114 use Module::Build;
116 my $class = Module::Build->subclass
117 (
118 class => 'My::Builder',
119 code => q{
120 sub ACTION_foo {
121 print "I'm fooing to death!\n";
122 }
123 },
124 );
125 my $build = $class->new
127 (
128 module_name => 'Foo::Bar', # All the regular args...
129 license => 'perl',
130 dist_author => 'A N Other <me@here.net.au>',
131 requires => { Carp => 0 }
132 );
133 $build->create_build_script;
134 Behind the scenes, this actually does create a ".pm" file, since the
136 code you provide must persist after Build.PL is run if it is to be very
137 useful.
138 See also the documentation for the "subclass()" in Module::Build::API
140 method.
141
143 Types of prerequisites
144 To specify what versions of other modules are used by this
145 distribution, several types of prerequisites can be defined with the
146 following parameters:
147 configure_requires
149 Items that must be installed before configuring this distribution
150 (i.e. before running the Build.PL script). This might be a specific
151 minimum version of "Module::Build" or any other module the Build.PL
152 needs in order to do its stuff. Clients like "CPAN.pm" or
153 "CPANPLUS" will be expected to pick "configure_requires" out of the
154 META.yml file and install these items before running the "Build.PL".
155 If no configure_requires is specified, the current version of
157 Module::Build is automatically added to configure_requires.
158 build_requires
160 Items that are necessary for building and testing this distribution,
161 but aren't necessary after installation. This can help users who
162 only want to install these items temporarily. It also helps reduce
163 the size of the CPAN dependency graph if everything isn't smooshed
164 into "requires".
165 requires
167 Items that are necessary for basic functioning.
168 recommends
170 Items that are recommended for enhanced functionality, but there are
171 ways to use this distribution without having them installed. You
172 might also think of this as "can use" or "is aware of" or "changes
173 behavior in the presence of".
174 conflicts
176 Items that can cause problems with this distribution when installed.
177 This is pretty rare.
178 Format of prerequisites
180 The prerequisites are given in a hash reference, where the keys are the
181 module names and the values are version specifiers:
182 requires => {
184 Foo::Module => '2.4',
185 Bar::Module => 0,
186 Ken::Module => '>= 1.2, != 1.5, < 2.0',
187 perl => '5.6.0'
188 },
189 The above four version specifiers have different effects. The value
191 '2.4' means that at least version 2.4 of "Foo::Module" must be
192 installed. The value 0 means that any version of "Bar::Module" is
193 acceptable, even if "Bar::Module" doesn't define a version. The more
194 verbose value '>= 1.2, != 1.5, < 2.0' means that "Ken::Module"'s
195 version must be at least 1.2, less than 2.0, and not equal to 1.5. The
196 list of criteria is separated by commas, and all criteria must be
197 satisfied.
198 A special "perl" entry lets you specify the versions of the Perl
200 interpreter that are supported by your module. The same version
201 dependency-checking semantics are available, except that we also
202 understand perl's new double-dotted version numbers.
203 XS Extensions
205 Modules which need to compile XS code should list "ExtUtils::CBuilder"
206 as a "build_requires" element.
207
209 Module::Build provides a very convenient way to save configuration
210 information that your installed modules (or your regression tests) can
211 access. If your Build process calls the "feature()" or "config_data()"
212 methods, then a "Foo::Bar::ConfigData" module will automatically be
213 created for you, where "Foo::Bar" is the "module_name" parameter as
214 passed to "new()". This module provides access to the data saved by
215 these methods, and a way to update the values. There is also a utility
216 script called "config_data" distributed with Module::Build that
217 provides a command line interface to this same functionality. See also
218 the generated "Foo::Bar::ConfigData" documentation, and the
219 "config_data" script's documentation, for more information.
220
222 When starting development on a new module, it's rarely worth your time
223 to create a tree of all the files by hand. Some automatic module-
224 creators are available: the oldest is "h2xs", which has shipped with
225 perl itself for a long time. Its name reflects the fact that modules
226 were originally conceived of as a way to wrap up a C library (thus the
227 "h" part) into perl extensions (thus the "xs" part).
228 These days, "h2xs" has largely been superseded by modules like
230 "ExtUtils::ModuleMaker", and "Module::Starter". They have varying
231 degrees of support for "Module::Build".
232
234 One advantage of Module::Build is that since it's implemented as Perl
235 methods, you can invoke these methods directly if you want to install a
236 module non-interactively. For instance, the following Perl script will
237 invoke the entire build/install procedure:
238 my $build = Module::Build->new(module_name => 'MyModule');
240 $build->dispatch('build');
241 $build->dispatch('test');
242 $build->dispatch('install');
243 If any of these steps encounters an error, it will throw a fatal
245 exception.
246 You can also pass arguments as part of the build process:
248 my $build = Module::Build->new(module_name => 'MyModule');
250 $build->dispatch('build');
251 $build->dispatch('test', verbose => 1);
252 $build->dispatch('install', sitelib => '/my/secret/place/');
253 Building and installing modules in this way skips creating the "Build"
255 script.
256
258 Note that if you want to provide both a Makefile.PL and a Build.PL for
259 your distribution, you probably want to add the following to
260 "WriteMakefile" in your Makefile.PL so that "MakeMaker" doesn't try to
261 run your Build.PL as a normal .PL file:
262 PL_FILES => {},
264 You may also be interested in looking at the "Module::Build::Compat"
266 module, which can automatically create various kinds of Makefile.PL
267 compatibility layers.
268
270 Ken Williams <kwilliams@cpan.org>
271 Development questions, bug reports, and patches should be sent to the
273 Module-Build mailing list at <module-build@perl.org>.
274 Bug reports are also welcome at
276 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>.
277 The latest development version is available from the Subversion
279 repository at <https://svn.perl.org/modules/Module-Build/trunk/>
280
282 perl(1), Module::Build(3), Module::Build::API(3),
283 Module::Build::Cookbook(3), ExtUtils::MakeMaker(3), YAML(3)
284 META.yml Specification:
286 <http://module-build.sourceforge.net/META-spec-current.html>
287 <http://www.dsmit.com/cons/>
289 <http://search.cpan.org/dist/PerlBuildSystem/>
291perl v5.10.1 2009-07-06 Module::Build::Authoring(3pm)