This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
7bbf56254919894a1b2511a022632e9ae618182d
[perl5.git] / cpan / Module-Build / lib / Module / Build / Authoring.pod
1 =head1 NAME
2
3 Module::Build::Authoring - Authoring Module::Build modules
4
5 =head1 DESCRIPTION
6
7 When creating a C<Build.PL> script for a module, something like the
8 following code will typically be used:
9
10   use Module::Build;
11   my $build = Module::Build->new
12     (
13      module_name => 'Foo::Bar',
14      license  => 'perl',
15      requires => {
16                   'perl'          => '5.6.1',
17                   'Some::Module'  => '1.23',
18                   'Other::Module' => '>= 1.2, != 1.5, < 2.0',
19                  },
20     );
21   $build->create_build_script;
22
23 A simple module could get away with something as short as this for its
24 C<Build.PL> script:
25
26   use Module::Build;
27   Module::Build->new(
28     module_name => 'Foo::Bar',
29     license     => 'perl',
30   )->create_build_script;
31
32 The model used by C<Module::Build> is a lot like the C<MakeMaker>
33 metaphor, with the following correspondences:
34
35    In Module::Build                 In ExtUtils::MakeMaker
36   ---------------------------      ------------------------
37    Build.PL (initial script)        Makefile.PL (initial script)
38    Build (a short perl script)      Makefile (a long Makefile)
39    _build/ (saved state info)       various config text in the Makefile
40
41 Any customization can be done simply by subclassing C<Module::Build>
42 and adding a method called (for example) C<ACTION_test>, overriding
43 the default 'test' action.  You could also add a method called
44 C<ACTION_whatever>, and then you could perform the action C<Build
45 whatever>.
46
47 For information on providing compatibility with
48 C<ExtUtils::MakeMaker>, see L<Module::Build::Compat> and
49 L<http://www.makemaker.org/wiki/index.cgi?ModuleBuildConversionGuide>.
50
51
52 =head1 STRUCTURE
53
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
76
77 =head1 SUBCLASSING
78
79 Right now, there are two ways to subclass Module::Build.  The first
80 way is to create a regular module (in a C<.pm> file) that inherits
81 from Module::Build, and use that module's class instead of using
82 Module::Build directly:
83
84   ------ in Build.PL: ----------
85   #!/usr/bin/perl
86
87   use lib q(/nonstandard/library/path);
88   use My::Builder;  # Or whatever you want to call it
89
90   my $build = My::Builder->new
91     (
92      module_name => 'Foo::Bar',  # All the regular args...
93      license     => 'perl',
94      dist_author => 'A N Other <me@here.net.au>',
95      requires    => { Carp => 0 }
96     );
97   $build->create_build_script;
98
99 This is relatively straightforward, and is the best way to do things
100 if your My::Builder class contains lots of code.  The
101 C<create_build_script()> method will ensure that the current value of
102 C<@INC> (including the C</nonstandard/library/path>) is propagated to
103 the Build script, so that My::Builder can be found when running build
104 actions.  If you find that you need to C<chdir> into a different directories
105 in your subclass methods or actions, be sure to always return to the original
106 directory (available via the C<base_dir()> method) before returning control
107 to the parent class.  This is important to avoid data serialization problems.
108
109 For very small additions, Module::Build provides a C<subclass()>
110 method that lets you subclass Module::Build more conveniently, without
111 creating a separate file for your module:
112
113   ------ in Build.PL: ----------
114   #!/usr/bin/perl
115
116   use Module::Build;
117   my $class = Module::Build->subclass
118     (
119      class => 'My::Builder',
120      code => q{
121        sub ACTION_foo {
122          print "I'm fooing to death!\n";
123        }
124      },
125     );
126
127   my $build = $class->new
128     (
129      module_name => 'Foo::Bar',  # All the regular args...
130      license     => 'perl',
131      dist_author => 'A N Other <me@here.net.au>',
132      requires    => { Carp => 0 }
133     );
134   $build->create_build_script;
135
136 Behind the scenes, this actually does create a C<.pm> file, since the
137 code you provide must persist after Build.PL is run if it is to be
138 very useful.
139
140 See also the documentation for the L<Module::Build::API/"subclass()">
141 method.
142
143
144 =head1 PREREQUISITES
145
146 =head2 Types of prerequisites
147
148 To specify what versions of other modules are used by this
149 distribution, several types of prerequisites can be defined with the
150 following parameters:
151
152 =over 3
153
154 =item configure_requires
155
156 Items that must be installed I<before> configuring this distribution
157 (i.e. before running the F<Build.PL> script).  This might be a
158 specific minimum version of C<Module::Build> or any other module the
159 F<Build.PL> needs in order to do its stuff.  Clients like C<CPAN.pm>
160 or C<CPANPLUS> will be expected to pick C<configure_requires> out of the
161 F<META.yml> file and install these items before running the
162 C<Build.PL>.
163
164 If no configure_requires is specified, the current version of Module::Build
165 is automatically added to configure_requires.
166
167 =item build_requires
168
169 Items that are necessary for building and testing this distribution,
170 but aren't necessary after installation.  This can help users who only
171 want to install these items temporarily.  It also helps reduce the
172 size of the CPAN dependency graph if everything isn't smooshed into
173 C<requires>.
174
175 =item requires
176
177 Items that are necessary for basic functioning.
178
179 =item recommends
180
181 Items that are recommended for enhanced functionality, but there are
182 ways to use this distribution without having them installed.  You
183 might also think of this as "can use" or "is aware of" or "changes
184 behavior in the presence of".
185
186 =item test_requires
187
188 Items that are necessary for testing.
189
190 =item conflicts
191
192 Items that can cause problems with this distribution when installed.
193 This is pretty rare.
194
195 =back
196
197 =head2 Format of prerequisites
198
199 The prerequisites are given in a hash reference, where the keys are
200 the module names and the values are version specifiers:
201
202   requires => {
203                Foo::Module => '2.4',
204                Bar::Module => 0,
205                Ken::Module => '>= 1.2, != 1.5, < 2.0',
206                perl => '5.6.0'
207               },
208
209 The above four version specifiers have different effects.  The value
210 C<'2.4'> means that B<at least> version 2.4 of C<Foo::Module> must be
211 installed.  The value C<0> means that B<any> version of C<Bar::Module>
212 is acceptable, even if C<Bar::Module> doesn't define a version.  The
213 more verbose value C<'E<gt>= 1.2, != 1.5, E<lt> 2.0'> means that
214 C<Ken::Module>'s version must be B<at least> 1.2, B<less than> 2.0,
215 and B<not equal to> 1.5.  The list of criteria is separated by commas,
216 and all criteria must be satisfied.
217
218 A special C<perl> entry lets you specify the versions of the Perl
219 interpreter that are supported by your module.  The same version
220 dependency-checking semantics are available, except that we also
221 understand perl's new double-dotted version numbers.
222
223 =head2 XS Extensions
224
225 Modules which need to compile XS code should list C<ExtUtils::CBuilder>
226 as a C<build_requires> element.
227
228
229 =head1 SAVING CONFIGURATION INFORMATION
230
231 Module::Build provides a very convenient way to save configuration
232 information that your installed modules (or your regression tests) can
233 access.  If your Build process calls the C<feature()> or
234 C<config_data()> methods, then a C<Foo::Bar::ConfigData> module will
235 automatically be created for you, where C<Foo::Bar> is the
236 C<module_name> parameter as passed to C<new()>.  This module provides
237 access to the data saved by these methods, and a way to update the
238 values.  There is also a utility script called C<config_data>
239 distributed with Module::Build that provides a command line interface
240 to this same functionality.  See also the generated
241 C<Foo::Bar::ConfigData> documentation, and the C<config_data>
242 script's documentation, for more information.
243
244
245 =head1 STARTING MODULE DEVELOPMENT
246
247 When starting development on a new module, it's rarely worth your time
248 to create a tree of all the files by hand.  Some automatic
249 module-creators are available: the oldest is C<h2xs>, which has
250 shipped with perl itself for a long time.  Its name reflects the fact
251 that modules were originally conceived of as a way to wrap up a C
252 library (thus the C<h> part) into perl extensions (thus the C<xs>
253 part).
254
255 These days, C<h2xs> has largely been superseded by modules like
256 C<ExtUtils::ModuleMaker>, and C<Module::Starter>.  They have varying
257 degrees of support for C<Module::Build>.
258
259
260 =head1 AUTOMATION
261
262 One advantage of Module::Build is that since it's implemented as Perl
263 methods, you can invoke these methods directly if you want to install
264 a module non-interactively.  For instance, the following Perl script
265 will invoke the entire build/install procedure:
266
267   my $build = Module::Build->new(module_name => 'MyModule');
268   $build->dispatch('build');
269   $build->dispatch('test');
270   $build->dispatch('install');
271
272 If any of these steps encounters an error, it will throw a fatal
273 exception.
274
275 You can also pass arguments as part of the build process:
276
277   my $build = Module::Build->new(module_name => 'MyModule');
278   $build->dispatch('build');
279   $build->dispatch('test', verbose => 1);
280   $build->dispatch('install', sitelib => '/my/secret/place/');
281
282 Building and installing modules in this way skips creating the
283 C<Build> script.
284
285
286 =head1 MIGRATION
287
288 Note that if you want to provide both a F<Makefile.PL> and a
289 F<Build.PL> for your distribution, you probably want to add the
290 following to C<WriteMakefile> in your F<Makefile.PL> so that C<MakeMaker>
291 doesn't try to run your F<Build.PL> as a normal F<.PL> file:
292
293   PL_FILES => {},
294
295 You may also be interested in looking at the C<Module::Build::Compat>
296 module, which can automatically create various kinds of F<Makefile.PL>
297 compatibility layers.
298
299
300 =head1 AUTHOR
301
302 Ken Williams <kwilliams@cpan.org>
303
304 Development questions, bug reports, and patches should be sent to the
305 Module-Build mailing list at <module-build@perl.org>.
306
307 Bug reports are also welcome at
308 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>.
309
310 The latest development version is available from the Git
311 repository at <https://github.com/Perl-Toolchain-Gang/Module-Build>
312
313
314 =head1 SEE ALSO
315
316 perl(1), L<Module::Build>(3), L<Module::Build::API>(3),
317 L<Module::Build::Cookbook>(3), L<ExtUtils::MakeMaker>(3), L<YAML>(3)
318
319 F<META.yml> Specification:
320 L<CPAN::META::Spec>
321
322 L<http://www.dsmit.com/cons/>
323
324 L<http://search.cpan.org/dist/PerlBuildSystem/>
325
326 =cut