summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Module/Build/Authoring.pod
blob: 38fb3f089a68b71fbc93d9b82723cc6c70436469 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
=head1 NAME

Module::Build::Authoring - Authoring Module::Build modules


=head1 DESCRIPTION

When creating a C<Build.PL> script for a module, something like the
following code will typically be used:

  use Module::Build;
  my $build = Module::Build->new
    (
     module_name => 'Foo::Bar',
     license  => 'perl',
     requires => {
                  'perl'          => '5.6.1',
                  'Some::Module'  => '1.23',
                  'Other::Module' => '>= 1.2, != 1.5, < 2.0',
                 },
    );
  $build->create_build_script;

A simple module could get away with something as short as this for its
C<Build.PL> script:

  use Module::Build;
  Module::Build->new(
    module_name => 'Foo::Bar',
    license     => 'perl',
  )->create_build_script;

The model used by C<Module::Build> is a lot like the C<MakeMaker>
metaphor, with the following correspondences:

   In Module::Build                 In ExtUtils::MakeMaker
  ---------------------------      ------------------------
   Build.PL (initial script)        Makefile.PL (initial script)
   Build (a short perl script)      Makefile (a long Makefile)
   _build/ (saved state info)       various config text in the Makefile

Any customization can be done simply by subclassing C<Module::Build>
and adding a method called (for example) C<ACTION_test>, overriding
the default 'test' action.  You could also add a method called
C<ACTION_whatever>, and then you could perform the action C<Build
whatever>.

For information on providing compatibility with
C<ExtUtils::MakeMaker>, see L<Module::Build::Compat> and
L<http://www.makemaker.org/wiki/index.cgi?ModuleBuildConversionGuide>.


=head1 STRUCTURE

Module::Build creates a class hierarchy conducive to customization.
Here is the parent-child class hierarchy in classy ASCII art:

   /--------------------\
   |   Your::Parent     |  (If you subclass Module::Build)
   \--------------------/
            |
            |
   /--------------------\  (Doesn't define any functionality
   |   Module::Build    |   of its own - just figures out what
   \--------------------/   other modules to load.)
            |
            |
   /-----------------------------------\  (Some values of $^O may
   |   Module::Build::Platform::$^O    |   define specialized functionality.
   \-----------------------------------/   Otherwise it's ...::Default, a
            |                              pass-through class.)
            |
   /--------------------------\
   |   Module::Build::Base    |  (Most of the functionality of 
   \--------------------------/   Module::Build is defined here.)


=head1 SUBCLASSING

Right now, there are two ways to subclass Module::Build.  The first
way is to create a regular module (in a C<.pm> file) that inherits
from Module::Build, and use that module's class instead of using
Module::Build directly:

  ------ in Build.PL: ----------
  #!/usr/bin/perl

  use lib q(/nonstandard/library/path);
  use My::Builder;  # Or whatever you want to call it

  my $build = My::Builder->new
    (
     module_name => 'Foo::Bar',  # All the regular args...
     license     => 'perl',
     dist_author => 'A N Other <me@here.net.au>',
     requires    => { Carp => 0 }
    );
  $build->create_build_script;

This is relatively straightforward, and is the best way to do things
if your My::Builder class contains lots of code.  The
C<create_build_script()> method will ensure that the current value of
C<@INC> (including the C</nonstandard/library/path>) is propagated to
the Build script, so that My::Builder can be found when running build
actions.  If you find that you need to C<chdir> into a different directories
in your subclass methods or actions, be sure to always return to the original
directory (available via the C<base_dir()> method before returning control
to the parent class.  This is important to avoid data serialization problems.

For very small additions, Module::Build provides a C<subclass()>
method that lets you subclass Module::Build more conveniently, without
creating a separate file for your module:

  ------ in Build.PL: ----------
  #!/usr/bin/perl

  use Module::Build;
  my $class = Module::Build->subclass
    (
     class => 'My::Builder',
     code => q{
       sub ACTION_foo {
         print "I'm fooing to death!\n";
       }
     },
    );

  my $build = $class->new
    (
     module_name => 'Foo::Bar',  # All the regular args...
     license     => 'perl',
     dist_author => 'A N Other <me@here.net.au>',
     requires    => { Carp => 0 }
    );
  $build->create_build_script;

Behind the scenes, this actually does create a C<.pm> file, since the
code you provide must persist after Build.PL is run if it is to be
very useful.

See also the documentation for the L<Module::Build::API/"subclass()">
method.


=head1 PREREQUISITES

=head2 Types of prerequisites

To specify what versions of other modules are used by this
distribution, several types of prerequisites can be defined with the
following parameters:

=over 3

=item configure_requires

Items that must be installed I<before> configuring this distribution
(i.e. before running the F<Build.PL> script).  This might be a
specific minimum version of C<Module::Build> or any other module the
F<Build.PL> needs in order to do its stuff.  Clients like C<CPAN.pm>
or C<CPANPLUS> will be expected to pick C<configure_requires> out of the
F<META.yml> file and install these items before running the
C<Build.PL>.

If no configure_requires is specified, the current version of Module::Build
is automatically added to configure_requires.

=item build_requires

Items that are necessary for building and testing this distribution,
but aren't necessary after installation.  This can help users who only
want to install these items temporarily.  It also helps reduce the
size of the CPAN dependency graph if everything isn't smooshed into
C<requires>.

=item requires

Items that are necessary for basic functioning.

=item recommends

Items that are recommended for enhanced functionality, but there are
ways to use this distribution without having them installed.  You
might also think of this as "can use" or "is aware of" or "changes
behavior in the presence of".

=item conflicts

Items that can cause problems with this distribution when installed.
This is pretty rare.

=back

=head2 Format of prerequisites

The prerequisites are given in a hash reference, where the keys are
the module names and the values are version specifiers:

  requires => {
               Foo::Module => '2.4',
               Bar::Module => 0,
               Ken::Module => '>= 1.2, != 1.5, < 2.0',
               perl => '5.6.0'
              },

The above four version specifiers have different effects.  The value
C<'2.4'> means that B<at least> version 2.4 of C<Foo::Module> must be
installed.  The value C<0> means that B<any> version of C<Bar::Module>
is acceptable, even if C<Bar::Module> doesn't define a version.  The
more verbose value C<'E<gt>= 1.2, != 1.5, E<lt> 2.0'> means that
C<Ken::Module>'s version must be B<at least> 1.2, B<less than> 2.0,
and B<not equal to> 1.5.  The list of criteria is separated by commas,
and all criteria must be satisfied.

A special C<perl> entry lets you specify the versions of the Perl
interpreter that are supported by your module.  The same version
dependency-checking semantics are available, except that we also
understand perl's new double-dotted version numbers.

=head2 XS Extensions

Modules which need to compile XS code should list C<ExtUtils::CBuilder>
as a C<build_requires> element.


=head1 SAVING CONFIGURATION INFORMATION

Module::Build provides a very convenient way to save configuration
information that your installed modules (or your regression tests) can
access.  If your Build process calls the C<feature()> or
C<config_data()> methods, then a C<Foo::Bar::ConfigData> module will
automatically be created for you, where C<Foo::Bar> is the
C<module_name> parameter as passed to C<new()>.  This module provides
access to the data saved by these methods, and a way to update the
values.  There is also a utility script called C<config_data>
distributed with Module::Build that provides a command line interface
to this same functionality.  See also the generated
C<Foo::Bar::ConfigData> documentation, and the C<config_data>
script's documentation, for more information.


=head1 STARTING MODULE DEVELOPMENT

When starting development on a new module, it's rarely worth your time
to create a tree of all the files by hand.  Some automatic
module-creators are available: the oldest is C<h2xs>, which has
shipped with perl itself for a long time.  Its name reflects the fact
that modules were originally conceived of as a way to wrap up a C
library (thus the C<h> part) into perl extensions (thus the C<xs>
part).

These days, C<h2xs> has largely been superseded by modules like
C<ExtUtils::ModuleMaker>, and C<Module::Starter>.  They have varying
degrees of support for C<Module::Build>.


=head1 AUTOMATION

One advantage of Module::Build is that since it's implemented as Perl
methods, you can invoke these methods directly if you want to install
a module non-interactively.  For instance, the following Perl script
will invoke the entire build/install procedure:

  my $build = Module::Build->new(module_name => 'MyModule');
  $build->dispatch('build');
  $build->dispatch('test');
  $build->dispatch('install');

If any of these steps encounters an error, it will throw a fatal
exception.

You can also pass arguments as part of the build process:

  my $build = Module::Build->new(module_name => 'MyModule');
  $build->dispatch('build');
  $build->dispatch('test', verbose => 1);
  $build->dispatch('install', sitelib => '/my/secret/place/');

Building and installing modules in this way skips creating the
C<Build> script.


=head1 MIGRATION

Note that if you want to provide both a F<Makefile.PL> and a
F<Build.PL> for your distribution, you probably want to add the
following to C<WriteMakefile> in your F<Makefile.PL> so that C<MakeMaker>
doesn't try to run your F<Build.PL> as a normal F<.PL> file:

  PL_FILES => {},

You may also be interested in looking at the C<Module::Build::Compat>
module, which can automatically create various kinds of F<Makefile.PL>
compatibility layers.


=head1 AUTHOR

Ken Williams <kwilliams@cpan.org>

Development questions, bug reports, and patches should be sent to the
Module-Build mailing list at <module-build@perl.org>.

Bug reports are also welcome at
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>.

The latest development version is available from the Subversion
repository at <https://svn.perl.org/modules/Module-Build/trunk/>


=head1 SEE ALSO

perl(1), L<Module::Build>(3), L<Module::Build::API>(3),
L<Module::Build::Cookbook>(3), L<ExtUtils::MakeMaker>(3), L<YAML>(3)

F<META.yml> Specification:
L<http://module-build.sourceforge.net/META-spec-current.html>

L<http://www.dsmit.com/cons/>

L<http://search.cpan.org/dist/PerlBuildSystem/>

=cut