Module::Build::Authoring(3pm)

1Module::Build::AuthorinUgs(e3r)Contributed Perl DocumentMaotdiuolne::Build::Authoring(3)
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 fol‐
10       lowing 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 what‐
47       ever".
48
49       For information on providing compatibility with "ExtUtils::MakeMaker",
50       see Module::Build::Compat and <http://www.make‐
51       maker.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 Mod‐
79       ule::Build, and use that module's class instead of using Module::Build
80       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 "cre‐
99       ate_build_script()" method will ensure that the current value of @INC
100       (including the "/nonstandard/library/path") is propogated to the Build
101       script, so that My::Builder can be found when running build actions.
102
103       For very small additions, Module::Build provides a "subclass()" method
104       that lets you subclass Module::Build more conveniently, without creat‐
105       ing a separate file for your module:
106
107         ------ in Build.PL: ----------
108         #!/usr/bin/perl
109
110         use Module::Build;
111         my $class = Module::Build->subclass
112           (
113            class => 'My::Builder',
114            code => q{
115              sub ACTION_foo {
116                print "I'm fooing to death!\n";
117              }
118            },
119           );
120
121         my $build = $class->new
122           (
123            module_name => 'Foo::Bar',  # All the regular args...
124            license     => 'perl',
125            dist_author => 'A N Other <me@here.net.au>',
126            requires    => { Carp => 0 }
127           );
128         $build->create_build_script;
129
130       Behind the scenes, this actually does create a ".pm" file, since the
131       code you provide must persist after Build.PL is run if it is to be very
132       useful.
133
134       See also the documentation for the "subclass()" in Module::Build::API
135       method.
136

PREREQUISITES

138       There are three basic types of prerequisites that can be defined: 1)
139       "requires" - are versions of modules that are required for certain
140       functionality to be available; 2) "recommends" - are versions of mod‐
141       ules that are recommended to provide enhanced functionality; and 3)
142       "conflicts" - are versions of modules that conflict with, and that can
143       cause problems with the distribution.
144
145       Each of the three types of prerequisites listed above can be applied to
146       different aspects of the Build process.  For the module distribution
147       itself you simply define "requires", "recommends", or "conflicts".  The
148       types can also apply to other aspects of the Build process.  Currently,
149       only "build_requires" is defined which is used for modules which are
150       required during the Build process.
151
152       Format of prerequisites
153
154       The prerequisites are given in a hash reference, where the keys are the
155       module names and the values are version specifiers:
156
157         requires => {
158                      Foo::Module => '2.4',
159                      Bar::Module => 0,
160                      Ken::Module => '>= 1.2, != 1.5, < 2.0',
161                      perl => '5.6.0'
162                     },
163
164       These four version specifiers have different effects.  The value '2.4'
165       means that at least version 2.4 of "Foo::Module" must be installed.
166       The value 0 means that any version of "Bar::Module" is acceptable, even
167       if "Bar::Module" doesn't define a version.  The more verbose value '>=
168       1.2, != 1.5, < 2.0' means that "Ken::Module"'s version must be at least
169       1.2, less than 2.0, and not equal to 1.5.  The list of criteria is sep‐
170       arated by commas, and all criteria must be satisfied.
171
172       A special "perl" entry lets you specify the versions of the Perl inter‐
173       preter that are supported by your module.  The same version dependency-
174       checking semantics are available, except that we also understand perl's
175       new double-dotted version numbers.
176

SAVING CONFIGURATION INFORMATION

178       Module::Build provides a very convenient way to save configuration
179       information that your installed modules (or your regression tests) can
180       access.  If your Build process calls the "feature()" or "config_data()"
181       methods, then a "Foo::Bar::ConfigData" module will automatically be
182       created for you, where "Foo::Bar" is the "module_name" parameter as
183       passed to "new()".  This module provides access to the data saved by
184       these methods, and a way to update the values.  There is also a utility
185       script called "config_data" distributed with Module::Build that pro‐
186       vides a command line interface to this same functionality.  See also
187       the generated "Foo::Bar::ConfigData" documentation, and the "con‐
188       fig_data" script's documentation, for more information.
189

STARTING MODULE DEVELOPMENT

191       When starting development on a new module, it's rarely worth your time
192       to create a tree of all the files by hand.  Some automatic module-cre‐
193       ators are available: the oldest is "h2xs", which has shipped with perl
194       itself for a long time.  Its name reflects the fact that modules were
195       originally conceived of as a way to wrap up a C library (thus the "h"
196       part) into perl extensions (thus the "xs" part).
197
198       These days, "h2xs" has largely been superseded by modules like "ExtU‐
199       tils::ModuleMaker", "Module::Starter", and "Module::Maker".  They have
200       varying degrees of support for "Module::Build".
201

AUTOMATION

203       One advantage of Module::Build is that since it's implemented as Perl
204       methods, you can invoke these methods directly if you want to install a
205       module non-interactively.  For instance, the following Perl script will
206       invoke the entire build/install procedure:
207
208         my $build = Module::Build->new(module_name => 'MyModule');
209         $build->dispatch('build');
210         $build->dispatch('test');
211         $build->dispatch('install');
212
213       If any of these steps encounters an error, it will throw a fatal excep‐
214       tion.
215
216       You can also pass arguments as part of the build process:
217
218         my $build = Module::Build->new(module_name => 'MyModule');
219         $build->dispatch('build');
220         $build->dispatch('test', verbose => 1);
221         $build->dispatch('install', sitelib => '/my/secret/place/');
222
223       Building and installing modules in this way skips creating the "Build"
224       script.
225

MIGRATION

227       Note that if you want to provide both a Makefile.PL and a Build.PL for
228       your distribution, you probably want to add the following to
229       "WriteMakefile" in your Makefile.PL so that MakeMaker doesn't try to
230       run your Build.PL as a normal .PL file:
231
232         PL_FILES => {},
233
234       You may also be interested in looking at the "Module::Build::Compat"
235       module, which can automatically create various kinds of Makefile.PL
236       compatibility layers.
237

AUTHOR

239       Ken Williams <kwilliams@cpan.org>
240
241       Development questions, bug reports, and patches should be sent to the
242       Module-Build mailing list at <module-build@perl.org>.
243
244       Bug reports are also welcome at
245       <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>.
246
247       The latest development version is available from the Subversion reposi‐
248       tory at <https://svn.perl.org/modules/Module-Build/trunk/>
249