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