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 | |
144 | There are three basic types of prerequisites that can be defined: 1) |
145 | "requires" - are versions of modules that are required for certain |
146 | functionality to be available; 2) "recommends" - are versions of |
147 | modules that are recommended to provide enhanced functionality; and 3) |
148 | "conflicts" - are versions of modules that conflict with, and that can |
149 | cause problems with the distribution. |
150 | |
151 | Each of the three types of prerequisites listed above can be applied |
152 | to different aspects of the Build process. For the module distribution |
153 | itself you simply define "requires", "recommends", or "conflicts". The |
154 | types can also apply to other aspects of the Build process. Currently, |
155 | only "build_requires" is defined which is used for modules which are |
156 | required during the Build process. |
157 | |
158 | |
159 | =head2 Format of prerequisites |
160 | |
161 | The prerequisites are given in a hash reference, where the keys are |
162 | the module names and the values are version specifiers: |
163 | |
164 | requires => { |
165 | Foo::Module => '2.4', |
166 | Bar::Module => 0, |
167 | Ken::Module => '>= 1.2, != 1.5, < 2.0', |
168 | perl => '5.6.0' |
169 | }, |
170 | |
171 | These four version specifiers have different effects. The value |
172 | C<'2.4'> means that B<at least> version 2.4 of C<Foo::Module> must be |
173 | installed. The value C<0> means that B<any> version of C<Bar::Module> |
174 | is acceptable, even if C<Bar::Module> doesn't define a version. The |
175 | more verbose value C<'E<gt>= 1.2, != 1.5, E<lt> 2.0'> means that |
176 | C<Ken::Module>'s version must be B<at least> 1.2, B<less than> 2.0, |
177 | and B<not equal to> 1.5. The list of criteria is separated by commas, |
178 | and all criteria must be satisfied. |
179 | |
180 | A special C<perl> entry lets you specify the versions of the Perl |
181 | interpreter that are supported by your module. The same version |
182 | dependency-checking semantics are available, except that we also |
183 | understand perl's new double-dotted version numbers. |
184 | |
185 | |
186 | =head1 SAVING CONFIGURATION INFORMATION |
187 | |
188 | Module::Build provides a very convenient way to save configuration |
189 | information that your installed modules (or your regression tests) can |
190 | access. If your Build process calls the C<feature()> or |
191 | C<config_data()> methods, then a C<Foo::Bar::ConfigData> module will |
192 | automatically be created for you, where C<Foo::Bar> is the |
193 | C<module_name> parameter as passed to C<new()>. This module provides |
194 | access to the data saved by these methods, and a way to update the |
195 | values. There is also a utility script called C<config_data> |
196 | distributed with Module::Build that provides a command line interface |
197 | to this same functionality. See also the generated |
198 | C<Foo::Bar::ConfigData> documentation, and the C<config_data> |
199 | script's documentation, for more information. |
200 | |
201 | |
dc8021d3 |
202 | =head1 STARTING MODULE DEVELOPMENT |
203 | |
204 | When starting development on a new module, it's rarely worth your time |
205 | to create a tree of all the files by hand. Some automatic |
206 | module-creators are available: the oldest is C<h2xs>, which has |
207 | shipped with perl itself for a long time. Its name reflects the fact |
208 | that modules were originally conceived of as a way to wrap up a C |
209 | library (thus the C<h> part) into perl extensions (thus the C<xs> |
210 | part). |
211 | |
212 | These days, C<h2xs> has largely been superseded by modules like |
213 | C<ExtUtils::ModuleMaker>, C<Module::Starter>, and C<Module::Maker>. |
214 | They have varying degrees of support for C<Module::Build>. |
215 | |
216 | |
bb4e9162 |
217 | =head1 AUTOMATION |
218 | |
219 | One advantage of Module::Build is that since it's implemented as Perl |
220 | methods, you can invoke these methods directly if you want to install |
221 | a module non-interactively. For instance, the following Perl script |
222 | will invoke the entire build/install procedure: |
223 | |
224 | my $build = Module::Build->new(module_name => 'MyModule'); |
225 | $build->dispatch('build'); |
226 | $build->dispatch('test'); |
227 | $build->dispatch('install'); |
228 | |
229 | If any of these steps encounters an error, it will throw a fatal |
230 | exception. |
231 | |
232 | You can also pass arguments as part of the build process: |
233 | |
234 | my $build = Module::Build->new(module_name => 'MyModule'); |
235 | $build->dispatch('build'); |
236 | $build->dispatch('test', verbose => 1); |
237 | $build->dispatch('install', sitelib => '/my/secret/place/'); |
238 | |
239 | Building and installing modules in this way skips creating the |
240 | C<Build> script. |
241 | |
242 | |
bb4e9162 |
243 | =head1 MIGRATION |
244 | |
245 | Note that if you want to provide both a F<Makefile.PL> and a |
246 | F<Build.PL> for your distribution, you probably want to add the |
247 | following to C<WriteMakefile> in your F<Makefile.PL> so that MakeMaker |
248 | doesn't try to run your F<Build.PL> as a normal F<.PL> file: |
249 | |
250 | PL_FILES => {}, |
251 | |
252 | You may also be interested in looking at the C<Module::Build::Compat> |
253 | module, which can automatically create various kinds of F<Makefile.PL> |
254 | compatibility layers. |
255 | |
256 | |
257 | =head1 AUTHOR |
258 | |
dc8021d3 |
259 | Ken Williams <kwilliams@cpan.org> |
bb4e9162 |
260 | |
261 | Development questions, bug reports, and patches should be sent to the |
0ec9ad96 |
262 | Module-Build mailing list at <module-build@perl.org>. |
bb4e9162 |
263 | |
264 | Bug reports are also welcome at |
dc8021d3 |
265 | <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>. |
bb4e9162 |
266 | |
dc8021d3 |
267 | The latest development version is available from the Subversion |
268 | repository at <https://svn.perl.org/modules/Module-Build/trunk/> |
bb4e9162 |
269 | |
270 | |
271 | =head1 SEE ALSO |
272 | |
dc8021d3 |
273 | perl(1), L<Module::Build>(3), L<Module::Build::API>(3), |
274 | L<Module::Build::Cookbook>(3), L<ExtUtils::MakeMaker>(3), L<YAML>(3) |
bb4e9162 |
275 | |
276 | F<META.yml> Specification: |
77e96e88 |
277 | L<http://module-build.sourceforge.net/META-spec-current.html> |
bb4e9162 |
278 | |
279 | L<http://www.dsmit.com/cons/> |
280 | |
dc8021d3 |
281 | L<http://search.cpan.org/dist/PerlBuildSystem/> |
282 | |
bb4e9162 |
283 | =cut |