1Module::Build::AuthoringP(e3rplm)Programmers ReferenceMGoudiudlee::Build::Authoring(3pm)
2
3
4

NAME

6       Module::Build::Authoring - Authoring Module::Build modules
7

DESCRIPTION

9       When creating a "Build.PL" script for a module, something like the
10       following code will typically be used:
11
12         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
25       A simple module could get away with something as short as this for its
26       "Build.PL" script:
27
28         use Module::Build;
29         Module::Build->new(
30           module_name => 'Foo::Bar',
31           license     => 'perl',
32         )->create_build_script;
33
34       The model used by "Module::Build" is a lot like the "MakeMaker"
35       metaphor, with the following correspondences:
36
37          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
43       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
49       For information on providing compatibility with "ExtUtils::MakeMaker",
50       see Module::Build::Compat and
51       <http://www.makemaker.org/wiki/index.cgi?ModuleBuildConversionGuide>.
52

STRUCTURE

54       Module::Build creates a class hierarchy conducive to customization.
55       Here is the parent-child class hierarchy in classy ASCII art:
56
57          /--------------------\
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

SUBCLASSING

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
82         ------ in Build.PL: ----------
83         #!/usr/bin/perl
84
85         use lib q(/nonstandard/library/path);
86         use My::Builder;  # Or whatever you want to call it
87
88         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
97       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
108       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
112         ------ in Build.PL: ----------
113         #!/usr/bin/perl
114
115         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
126         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
135       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
139       See also the documentation for the "subclass()" in Module::Build::API
140       method.
141

PREREQUISITES

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
148       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
156          If no configure_requires is specified, the current version of
157          Module::Build is automatically added to configure_requires.
158
159       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
166       requires
167          Items that are necessary for basic functioning.
168
169       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
175       conflicts
176          Items that can cause problems with this distribution when installed.
177          This is pretty rare.
178
179   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
183         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
190       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
199       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
204   XS Extensions
205       Modules which need to compile XS code should list "ExtUtils::CBuilder"
206       as a "build_requires" element.
207

SAVING CONFIGURATION INFORMATION

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

STARTING MODULE DEVELOPMENT

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
229       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

AUTOMATION

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
239         my $build = Module::Build->new(module_name => 'MyModule');
240         $build->dispatch('build');
241         $build->dispatch('test');
242         $build->dispatch('install');
243
244       If any of these steps encounters an error, it will throw a fatal
245       exception.
246
247       You can also pass arguments as part of the build process:
248
249         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
254       Building and installing modules in this way skips creating the "Build"
255       script.
256

MIGRATION

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
263         PL_FILES => {},
264
265       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

AUTHOR

270       Ken Williams <kwilliams@cpan.org>
271
272       Development questions, bug reports, and patches should be sent to the
273       Module-Build mailing list at <module-build@perl.org>.
274
275       Bug reports are also welcome at
276       <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>.
277
278       The latest development version is available from the Subversion
279       repository at <https://svn.perl.org/modules/Module-Build/trunk/>
280

SEE ALSO

282       perl(1), Module::Build(3), Module::Build::API(3),
283       Module::Build::Cookbook(3), ExtUtils::MakeMaker(3), YAML(3)
284
285       META.yml Specification:
286       http://module-build.sourceforge.net/META-spec-current.html
287       <http://module-build.sourceforge.net/META-spec-current.html>
288
289       <http://www.dsmit.com/cons/>
290
291       <http://search.cpan.org/dist/PerlBuildSystem/>
292
293
294
295perl v5.12.4                      2011-06-07     Module::Build::Authoring(3pm)
Impressum