Commit | Line | Data |
dc8021d3 |
1 | =head1 NAME |
2 | |
3 | Module::Build::API - API Reference for Module Authors |
4 | |
5 | |
6 | =head1 DESCRIPTION |
7 | |
8 | I list here some of the most important methods in C<Module::Build>. |
9 | Normally you won't need to deal with these methods unless you want to |
10 | subclass C<Module::Build>. But since one of the reasons I created |
11 | this module in the first place was so that subclassing is possible |
12 | (and easy), I will certainly write more docs as the interface |
13 | stabilizes. |
14 | |
15 | |
16 | =head2 CONSTRUCTORS |
17 | |
18 | =over 4 |
19 | |
20 | =item current() |
21 | |
22 | [version 0.20] |
23 | |
24 | This method returns a reasonable facsimile of the currently-executing |
25 | C<Module::Build> object representing the current build. You can use |
7a827510 |
26 | this object to query its L</notes()> method, inquire about installed |
dc8021d3 |
27 | modules, and so on. This is a great way to share information between |
28 | different parts of your build process. For instance, you can ask |
29 | the user a question during C<perl Build.PL>, then use their answer |
30 | during a regression test: |
31 | |
32 | # In Build.PL: |
33 | my $color = $build->prompt("What is your favorite color?"); |
34 | $build->notes(color => $color); |
35 | |
36 | # In t/colortest.t: |
37 | use Module::Build; |
38 | my $build = Module::Build->current; |
39 | my $color = $build->notes('color'); |
40 | ... |
41 | |
42 | The way the C<current()> method is currently implemented, there may be |
43 | slight differences between the C<$build> object in Build.PL and the |
44 | one in C<t/colortest.t>. It is our goal to minimize these differences |
45 | in future releases of Module::Build, so please report any anomalies |
46 | you find. |
47 | |
48 | One important caveat: in its current implementation, C<current()> will |
49 | B<NOT> work correctly if you have changed out of the directory that |
50 | C<Module::Build> was invoked from. |
51 | |
52 | =item new() |
53 | |
54 | [version 0.03] |
55 | |
56 | Creates a new Module::Build object. Arguments to the new() method are |
57 | listed below. Most arguments are optional, but you must provide |
7a827510 |
58 | either the L</module_name> argument, or L</dist_name> and one of |
59 | L</dist_version> or L</dist_version_from>. In other words, you must |
dc8021d3 |
60 | provide enough information to determine both a distribution name and |
61 | version. |
62 | |
63 | |
64 | =over 4 |
65 | |
66 | =item add_to_cleanup |
67 | |
68 | [version 0.19] |
69 | |
70 | An array reference of files to be cleaned up when the C<clean> action |
7a827510 |
71 | is performed. See also the L<add_to_cleanup()|/"add_to_cleanup(@files)"> |
72 | method. |
dc8021d3 |
73 | |
74 | =item auto_features |
75 | |
76 | [version 0.26] |
77 | |
78 | This parameter supports the setting of features (see |
7a827510 |
79 | L</feature($name)>) automatically based on a set of prerequisites. For |
dc8021d3 |
80 | instance, for a module that could optionally use either MySQL or |
81 | PostgreSQL databases, you might use C<auto_features> like this: |
82 | |
83 | my $build = Module::Build->new |
84 | ( |
85 | ...other stuff here... |
86 | auto_features => { |
87 | pg_support => { |
88 | description => "Interface with Postgres databases", |
89 | requires => { 'DBD::Pg' => 23.3, |
90 | 'DateTime::Format::Pg' => 0 }, |
91 | }, |
92 | mysql_support => { |
93 | description => "Interface with MySQL databases", |
94 | requires => { 'DBD::mysql' => 17.9, |
95 | 'DateTime::Format::MySQL' => 0 }, |
96 | }, |
97 | } |
98 | ); |
99 | |
100 | For each feature named, the required prerequisites will be checked, and |
101 | if there are no failures, the feature will be enabled (set to C<1>). |
102 | Otherwise the failures will be displayed to the user and the feature |
103 | will be disabled (set to C<0>). |
104 | |
7a827510 |
105 | See the documentation for L</requires> for the details of how |
dc8021d3 |
106 | requirements can be specified. |
107 | |
108 | =item autosplit |
109 | |
110 | [version 0.04] |
111 | |
112 | An optional C<autosplit> argument specifies a file which should be run |
7a827510 |
113 | through the L<AutoSplit::autosplit()|AutoSplit/autosplit> function. |
114 | If multiple files should be split, the argument may be given as an |
115 | array of the files to split. |
dc8021d3 |
116 | |
117 | In general I don't consider autosplitting a great idea, because it's |
118 | not always clear that autosplitting achieves its intended performance |
119 | benefits. It may even harm performance in environments like mod_perl, |
120 | where as much as possible of a module's code should be loaded during |
121 | startup. |
122 | |
123 | =item build_class |
124 | |
125 | [version 0.28] |
126 | |
7a827510 |
127 | The Module::Build class or subclass to use in the build script. |
128 | Defaults to "Module::Build" or the class name passed to or created by |
129 | a call to L</subclass()>. This property is useful if you're |
dc8021d3 |
130 | writing a custom Module::Build subclass and have a bootstrapping |
131 | problem--that is, your subclass requires modules that may not be |
132 | installed when C<perl Build.PL> is executed, but you've listed in |
7a827510 |
133 | L</build_requires> so that they should be available when C<./Build> is |
dc8021d3 |
134 | executed. |
135 | |
136 | =item build_requires |
137 | |
138 | [version 0.07] |
139 | |
140 | Modules listed in this section are necessary to build and install the |
141 | given module, but are not necessary for regular usage of it. This is |
142 | actually an important distinction - it allows for tighter control over |
143 | the body of installed modules, and facilitates correct dependency |
144 | checking on binary/packaged distributions of the module. |
145 | |
146 | See the documentation for L<Module::Build::Authoring/"PREREQUISITES"> |
147 | for the details of how requirements can be specified. |
148 | |
149 | =item create_packlist |
150 | |
151 | [version 0.28] |
152 | |
153 | If true, this parameter tells Module::Build to create a F<.packlist> |
154 | file during the C<install> action, just like ExtUtils::MakeMaker does. |
155 | The file is created in a subdirectory of the C<arch> installation |
156 | location. It is used by some other tools (CPAN, CPANPLUS, etc.) for |
157 | determining what files are part of an install. |
158 | |
159 | The default value is true. This parameter was introduced in |
160 | Module::Build version 0.2609; previously no packlists were ever |
161 | created by Module::Build. |
162 | |
163 | =item c_source |
164 | |
165 | [version 0.04] |
166 | |
167 | An optional C<c_source> argument specifies a directory which contains |
168 | C source files that the rest of the build may depend on. Any C<.c> |
169 | files in the directory will be compiled to object files. The |
170 | directory will be added to the search path during the compilation and |
171 | linking phases of any C or XS files. |
172 | |
173 | =item conflicts |
174 | |
175 | [version 0.07] |
176 | |
177 | Modules listed in this section conflict in some serious way with the |
178 | given module. C<Module::Build> (or some higher-level tool) will |
179 | refuse to install the given module if the given module/version is also |
180 | installed. |
181 | |
182 | See the documentation for L<Module::Build::Authoring/"PREREQUISITES"> |
183 | for the details of how requirements can be specified. |
184 | |
185 | =item create_makefile_pl |
186 | |
187 | [version 0.19] |
188 | |
189 | This parameter lets you use Module::Build::Compat during the |
190 | C<distdir> (or C<dist>) action to automatically create a Makefile.PL |
191 | for compatibility with ExtUtils::MakeMaker. The parameter's value |
7a827510 |
192 | should be one of the styles named in the L<Module::Build::Compat> |
dc8021d3 |
193 | documentation. |
194 | |
195 | =item create_readme |
196 | |
197 | [version 0.22] |
198 | |
199 | This parameter tells Module::Build to automatically create a F<README> |
200 | file at the top level of your distribution. Currently it will simply |
201 | use C<Pod::Text> (or C<Pod::Readme> if it's installed) on the file |
202 | indicated by C<dist_version_from> and put the result in the F<README> |
203 | file. This is by no means the only recommended style for writing a |
204 | README, but it seems to be one common one used on the CPAN. |
205 | |
206 | If you generate a F<README> in this way, it's probably a good idea to |
207 | create a separate F<INSTALL> file if that information isn't in the |
208 | generated F<README>. |
209 | |
210 | =item dist_abstract |
211 | |
212 | [version 0.20] |
213 | |
15cb7b9d |
214 | This should be a short description of the distribution. This is used when |
215 | generating metadata for F<META.yml> and PPD files. If it is not given |
216 | then C<Module::Build> looks in the POD of the module from which it gets |
217 | the distribution's version. If it finds a POD section marked "=head1 |
218 | NAME", then it looks for the first line matching C<\s+-\s+(.+)>, |
219 | and uses the captured text as the abstract. |
dc8021d3 |
220 | |
221 | =item dist_author |
222 | |
223 | [version 0.20] |
224 | |
225 | This should be something like "John Doe <jdoe@example.com>", or if |
226 | there are multiple authors, an anonymous array of strings may be |
227 | specified. This is used when generating metadata for F<META.yml> and |
228 | PPD files. If this is not specified, then C<Module::Build> looks at |
229 | the module from which it gets the distribution's version. If it finds |
230 | a POD section marked "=head1 AUTHOR", then it uses the contents of |
231 | this section. |
232 | |
233 | =item dist_name |
234 | |
235 | [version 0.11] |
236 | |
237 | Specifies the name for this distribution. Most authors won't need to |
238 | set this directly, they can use C<module_name> to set C<dist_name> to |
239 | a reasonable default. However, some agglomerative distributions like |
240 | C<libwww-perl> or C<bioperl> have names that don't correspond directly |
241 | to a module name, so C<dist_name> can be set independently. |
242 | |
243 | =item dist_version |
244 | |
245 | [version 0.11] |
246 | |
7a827510 |
247 | Specifies a version number for the distribution. See L</module_name> |
248 | or L</dist_version_from> for ways to have this set automatically from a |
dc8021d3 |
249 | C<$VERSION> variable in a module. One way or another, a version |
250 | number needs to be set. |
251 | |
252 | =item dist_version_from |
253 | |
254 | [version 0.11] |
255 | |
256 | Specifies a file to look for the distribution version in. Most |
7a827510 |
257 | authors won't need to set this directly, they can use L</module_name> |
dc8021d3 |
258 | to set it to a reasonable default. |
259 | |
260 | The version is extracted from the specified file according to the same |
7a827510 |
261 | rules as L<ExtUtils::MakeMaker> and C<CPAN.pm>. It involves finding |
dc8021d3 |
262 | the first line that matches the regular expression |
263 | |
264 | /([\$*])(([\w\:\']*)\bVERSION)\b.*\=/ |
265 | |
266 | eval()-ing that line, then checking the value of the C<$VERSION> |
267 | variable. Quite ugly, really, but all the modules on CPAN depend on |
268 | this process, so there's no real opportunity to change to something |
269 | better. |
270 | |
15cb7b9d |
271 | If the target file of L</dist_version_from> contains more than one package |
272 | declaration, the version returned will be the one matching the configured |
273 | L</module_name>. |
274 | |
dc8021d3 |
275 | =item dynamic_config |
276 | |
277 | [version 0.07] |
278 | |
279 | A boolean flag indicating whether the F<Build.PL> file must be |
280 | executed, or whether this module can be built, tested and installed |
281 | solely from consulting its metadata file. The main reason to set this |
282 | to a true value is that your module performs some dynamic |
283 | configuration as part of its build/install process. If the flag is |
284 | omitted, the F<META.yml> spec says that installation tools should |
285 | treat it as 1 (true), because this is a safer way to behave. |
286 | |
287 | Currently C<Module::Build> doesn't actually do anything with this flag |
7a827510 |
288 | - it's up to higher-level tools like C<CPAN.pm> to do something useful |
289 | with it. It can potentially bring lots of security, packaging, and |
290 | convenience improvements. |
dc8021d3 |
291 | |
292 | =item extra_compiler_flags |
293 | |
294 | =item extra_linker_flags |
295 | |
296 | [version 0.19] |
297 | |
298 | These parameters can contain array references (or strings, in which |
299 | case they will be split into arrays) to pass through to the compiler |
300 | and linker phases when compiling/linking C code. For example, to tell |
301 | the compiler that your code is C++, you might do: |
302 | |
303 | my $build = Module::Build->new |
304 | ( |
305 | module_name => 'Foo::Bar', |
306 | extra_compiler_flags => ['-x', 'c++'], |
307 | ); |
308 | |
309 | To link your XS code against glib you might write something like: |
310 | |
311 | my $build = Module::Build->new |
312 | ( |
313 | module_name => 'Foo::Bar', |
314 | dynamic_config => 1, |
315 | extra_compiler_flags => scalar `glib-config --cflags`, |
316 | extra_linker_flags => scalar `glib-config --libs`, |
317 | ); |
318 | |
319 | =item get_options |
320 | |
321 | [version 0.26] |
322 | |
323 | You can pass arbitrary command line options to F<Build.PL> or |
324 | F<Build>, and they will be stored in the Module::Build object and can |
7a827510 |
325 | be accessed via the L</args()> method. However, sometimes you want |
dc8021d3 |
326 | more flexibility out of your argument processing than this allows. In |
327 | such cases, use the C<get_options> parameter to pass in a hash |
328 | reference of argument specifications, and the list of arguments to |
329 | F<Build.PL> or F<Build> will be processed according to those |
330 | specifications before they're passed on to C<Module::Build>'s own |
331 | argument processing. |
332 | |
333 | The supported option specification hash keys are: |
334 | |
335 | |
336 | =over 4 |
337 | |
338 | =item type |
339 | |
340 | The type of option. The types are those supported by Getopt::Long; consult |
341 | its documentation for a complete list. Typical types are C<=s> for strings, |
342 | C<+> for additive options, and C<!> for negatable options. If the |
343 | type is not specified, it will be considered a boolean, i.e. no |
344 | argument is taken and a value of 1 will be assigned when the option is |
345 | encountered. |
346 | |
347 | =item store |
348 | |
349 | A reference to a scalar in which to store the value passed to the option. |
350 | If not specified, the value will be stored under the option name in the |
351 | hash returned by the C<args()> method. |
352 | |
353 | =item default |
354 | |
355 | A default value for the option. If no default value is specified and no option |
356 | is passed, then the option key will not exist in the hash returned by |
357 | C<args()>. |
358 | |
359 | =back |
360 | |
361 | |
362 | You can combine references to your own variables or subroutines with |
363 | unreferenced specifications, for which the result will also be stored in the |
364 | hash returned by C<args()>. For example: |
365 | |
366 | my $loud = 0; |
367 | my $build = Module::Build->new |
368 | ( |
369 | module_name => 'Foo::Bar', |
370 | get_options => { |
371 | loud => { store => \$loud }, |
372 | dbd => { type => '=s' }, |
373 | quantity => { type => '+' }, |
374 | } |
375 | ); |
376 | |
377 | print STDERR "HEY, ARE YOU LISTENING??\n" if $loud; |
378 | print "We'll use the ", $build->args('dbd'), " DBI driver\n"; |
379 | print "Are you sure you want that many?\n" |
380 | if $build->args('quantity') > 2; |
381 | |
382 | The arguments for such a specification can be called like so: |
383 | |
384 | perl Build.PL --loud --dbd=DBD::pg --quantity --quantity --quantity |
385 | |
386 | B<WARNING:> Any option specifications that conflict with Module::Build's own |
387 | options (defined by its properties) will throw an exception. |
388 | |
389 | Consult the Getopt::Long documentation for details on its usage. |
390 | |
391 | =item include_dirs |
392 | |
393 | [version 0.24] |
394 | |
395 | Specifies any additional directories in which to search for C header |
396 | files. May be given as a string indicating a single directory, or as |
397 | a list reference indicating multiple directories. |
398 | |
399 | =item install_path |
400 | |
401 | [version 0.19] |
402 | |
403 | You can set paths for individual installable elements by using the |
404 | C<install_path> parameter: |
405 | |
406 | my $build = Module::Build->new |
407 | ( |
408 | ...other stuff here... |
409 | install_path => { |
410 | lib => '/foo/lib', |
411 | arch => '/foo/lib/arch', |
412 | } |
413 | ); |
414 | |
415 | =item installdirs |
416 | |
417 | [version 0.19] |
418 | |
419 | Determines where files are installed within the normal perl hierarchy |
420 | as determined by F<Config.pm>. Valid values are: C<core>, C<site>, |
421 | C<vendor>. The default is C<site>. See |
422 | L<Module::Build/"INSTALL PATHS"> |
423 | |
424 | =item license |
425 | |
426 | [version 0.07] |
427 | |
428 | Specifies the licensing terms of your distribution. Valid options include: |
429 | |
430 | |
431 | =over 4 |
432 | |
433 | =item apache |
434 | |
435 | The distribution is licensed under the Apache Software License |
7a827510 |
436 | (L<http://opensource.org/licenses/apachepl.php>). |
dc8021d3 |
437 | |
438 | =item artistic |
439 | |
440 | The distribution is licensed under the Artistic License, as specified |
7a827510 |
441 | by the F<Artistic> file in the standard Perl distribution. |
442 | |
443 | =item artistic_2 |
444 | |
445 | The distribution is licensed under the Artistic 2.0 License |
446 | (L<http://opensource.org/licenses/artistic-license-2.0.php>.) |
dc8021d3 |
447 | |
448 | =item bsd |
449 | |
450 | The distribution is licensed under the BSD License |
7a827510 |
451 | (L<http://www.opensource.org/licenses/bsd-license.php>). |
dc8021d3 |
452 | |
453 | =item gpl |
454 | |
7a827510 |
455 | The distribution is licensed under the terms of the GNU General |
456 | Public License (L<http://www.opensource.org/licenses/gpl-license.php>). |
dc8021d3 |
457 | |
458 | =item lgpl |
459 | |
7a827510 |
460 | The distribution is licensed under the terms of the GNU Lesser |
dc8021d3 |
461 | General Public License |
7a827510 |
462 | (L<http://www.opensource.org/licenses/lgpl-license.php>). |
dc8021d3 |
463 | |
464 | =item mit |
465 | |
466 | The distribution is licensed under the MIT License |
7a827510 |
467 | (L<http://opensource.org/licenses/mit-license.php>). |
dc8021d3 |
468 | |
469 | =item mozilla |
470 | |
471 | The distribution is licensed under the Mozilla Public |
7a827510 |
472 | License. (L<http://opensource.org/licenses/mozilla1.0.php> or |
473 | L<http://opensource.org/licenses/mozilla1.1.php>) |
dc8021d3 |
474 | |
475 | =item open_source |
476 | |
477 | The distribution is licensed under some other Open Source |
478 | Initiative-approved license listed at |
7a827510 |
479 | L<http://www.opensource.org/licenses/>. |
dc8021d3 |
480 | |
481 | =item perl |
482 | |
483 | The distribution may be copied and redistributed under the same terms |
7a827510 |
484 | as Perl itself (this is by far the most common licensing option for |
dc8021d3 |
485 | modules on CPAN). This is a dual license, in which the user may |
486 | choose between either the GPL or the Artistic license. |
487 | |
488 | =item restrictive |
489 | |
490 | The distribution may not be redistributed without special permission |
491 | from the author and/or copyright holder. |
492 | |
493 | =item unrestricted |
494 | |
495 | The distribution is licensed under a license that is B<not> approved |
496 | by www.opensource.org but that allows distribution without |
497 | restrictions. |
498 | |
499 | =back |
500 | |
501 | |
502 | Note that you must still include the terms of your license in your |
503 | documentation - this field only lets automated tools figure out your |
504 | licensing restrictions. Humans still need something to read. If you |
505 | choose to provide this field, you should make sure that you keep it in |
506 | sync with your written documentation if you ever change your licensing |
507 | terms. |
508 | |
738349a8 |
509 | You may also use a license type of C<unknown> if you don't wish to |
510 | specify your terms in the metadata. |
511 | |
dc8021d3 |
512 | It is a fatal error to use a license other than the ones mentioned |
513 | above. This is not because I wish to impose licensing terms on you - |
514 | please let me know if you would like another license option to be |
738349a8 |
515 | added to the list. I just started out with a small set of licenses to |
516 | keep things simple, figuring I'd let people with actual working |
517 | knowledge in this area tell me what to do. So if that's you, drop me |
518 | a line. |
dc8021d3 |
519 | |
520 | =item meta_add |
521 | |
522 | [version 0.28] |
523 | |
524 | A hash of key/value pairs that should be added to the F<META.yml> file |
525 | during the C<distmeta> action. Any existing entries with the same |
526 | names will be overridden. |
527 | |
7a827510 |
528 | See the L</"MODULE METADATA"> section for details. |
529 | |
dc8021d3 |
530 | =item meta_merge |
531 | |
532 | [version 0.28] |
533 | |
534 | A hash of key/value pairs that should be merged into the F<META.yml> |
535 | file during the C<distmeta> action. Any existing entries with the |
536 | same names will be overridden. |
537 | |
538 | The only difference between C<meta_add> and C<meta_merge> is their |
539 | behavior on hash-valued and array-valued entries: C<meta_add> will |
540 | completely blow away the existing hash or array value, but |
541 | C<meta_merge> will merge the supplied data into the existing hash or |
542 | array value. |
543 | |
7a827510 |
544 | See the L</"MODULE METADATA"> section for details. |
545 | |
dc8021d3 |
546 | =item module_name |
547 | |
548 | [version 0.03] |
549 | |
550 | The C<module_name> is a shortcut for setting default values of |
551 | C<dist_name> and C<dist_version_from>, reflecting the fact that the |
552 | majority of CPAN distributions are centered around one "main" module. |
553 | For instance, if you set C<module_name> to C<Foo::Bar>, then |
554 | C<dist_name> will default to C<Foo-Bar> and C<dist_version_from> will |
555 | default to C<lib/Foo/Bar.pm>. C<dist_version_from> will in turn be |
556 | used to set C<dist_version>. |
557 | |
558 | Setting C<module_name> won't override a C<dist_*> parameter you |
559 | specify explicitly. |
560 | |
561 | =item PL_files |
562 | |
563 | [version 0.06] |
564 | |
565 | An optional parameter specifying a set of C<.PL> files in your |
566 | distribution. These will be run as Perl scripts prior to processing |
567 | the rest of the files in your distribution. They are usually used as |
568 | templates for creating other files dynamically, so that a file like |
569 | C<lib/Foo/Bar.pm.PL> might create the file C<lib/Foo/Bar.pm>. |
570 | |
571 | The files are specified with the C<.PL> files as hash keys, and the |
572 | file(s) they generate as hash values, like so: |
573 | |
574 | my $build = Module::Build->new |
575 | ( |
576 | module_name => 'Foo::Bar', |
577 | ... |
578 | PL_files => { 'lib/Foo/Bar.pm.PL' => 'lib/Foo/Bar.pm' }, |
579 | ); |
580 | |
581 | Note that the path specifications are I<always> given in Unix-like |
582 | format, not in the style of the local system. |
583 | |
584 | If your C<.PL> scripts don't create any files, or if they create files |
585 | with unexpected names, or even if they create multiple files, you can |
586 | indicate that so that Module::Build can properly handle these created |
587 | files: |
588 | |
589 | PL_files => { |
590 | 'lib/Foo/Bar.pm.PL' => 'lib/Foo/Bar.pm', |
591 | 'lib/something.PL' => ['/lib/something', '/lib/else'], |
592 | 'lib/funny.PL' => [], |
593 | } |
594 | |
595 | =item pm_files |
596 | |
597 | [version 0.19] |
598 | |
599 | An optional parameter specifying the set of C<.pm> files in this |
600 | distribution, specified as a hash reference whose keys are the files' |
601 | locations in the distributions, and whose values are their logical |
602 | locations based on their package name, i.e. where they would be found |
603 | in a "normal" Module::Build-style distribution. This parameter is |
604 | mainly intended to support alternative layouts of files. |
605 | |
606 | For instance, if you have an old-style MakeMaker distribution for a |
607 | module called C<Foo::Bar> and a F<Bar.pm> file at the top level of the |
608 | distribution, you could specify your layout in your C<Build.PL> like |
609 | this: |
610 | |
611 | my $build = Module::Build->new |
612 | ( |
613 | module_name => 'Foo::Bar', |
614 | ... |
615 | pm_files => { 'Bar.pm' => 'lib/Foo/Bar.pm' }, |
616 | ); |
617 | |
618 | Note that the values should include C<lib/>, because this is where |
619 | they would be found in a "normal" Module::Build-style distribution. |
620 | |
621 | Note also that the path specifications are I<always> given in |
622 | Unix-like format, not in the style of the local system. |
623 | |
624 | =item pod_files |
625 | |
626 | [version 0.19] |
627 | |
628 | Just like C<pm_files>, but used for specifying the set of C<.pod> |
629 | files in your distribution. |
630 | |
631 | =item recommends |
632 | |
633 | [version 0.08] |
634 | |
7a827510 |
635 | This is just like the L</requires> argument, except that modules listed |
dc8021d3 |
636 | in this section aren't essential, just a good idea. We'll just print |
637 | a friendly warning if one of these modules aren't found, but we'll |
638 | continue running. |
639 | |
640 | If a module is recommended but not required, all tests should still |
641 | pass if the module isn't installed. This may mean that some tests |
642 | may be skipped if recommended dependencies aren't present. |
643 | |
644 | Automated tools like CPAN.pm should inform the user when recommended |
645 | modules aren't installed, and it should offer to install them if it |
646 | wants to be helpful. |
647 | |
648 | See the documentation for L<Module::Build::Authoring/"PREREQUISITES"> |
649 | for the details of how requirements can be specified. |
650 | |
651 | =item recursive_test_files |
652 | |
653 | [version 0.28] |
654 | |
655 | Normally, C<Module::Build> does not search subdirectories when looking |
656 | for tests to run. When this options is set it will search recursively |
657 | in all subdirectories of the standard 't' test directory. |
658 | |
659 | =item requires |
660 | |
661 | [version 0.07] |
662 | |
663 | An optional C<requires> argument specifies any module prerequisites |
664 | that the current module depends on. |
665 | |
666 | One note: currently C<Module::Build> doesn't actually I<require> the |
667 | user to have dependencies installed, it just strongly urges. In the |
7a827510 |
668 | future we may require it. There's also a L</recommends> section for |
dc8021d3 |
669 | things that aren't absolutely required. |
670 | |
671 | Automated tools like CPAN.pm should refuse to install a module if one |
672 | of its dependencies isn't satisfied, unless a "force" command is given |
673 | by the user. If the tools are helpful, they should also offer to |
674 | install the dependencies. |
675 | |
676 | A synonym for C<requires> is C<prereq>, to help succour people |
677 | transitioning from C<ExtUtils::MakeMaker>. The C<requires> term is |
678 | preferred, but the C<prereq> term will remain valid in future |
679 | distributions. |
680 | |
681 | See the documentation for L<Module::Build::Authoring/"PREREQUISITES"> |
682 | for the details of how requirements can be specified. |
683 | |
684 | =item script_files |
685 | |
686 | [version 0.18] |
687 | |
688 | An optional parameter specifying a set of files that should be |
7a827510 |
689 | installed as executable Perl scripts when the module is installed. |
738349a8 |
690 | May be given as an array reference of the files, as a hash reference |
691 | whose keys are the files (and whose values will currently be ignored), |
692 | as a string giving the name of a directory in which to find scripts, |
693 | or as a string giving the name of a single script file. |
dc8021d3 |
694 | |
738349a8 |
695 | The default is to install any scripts found in a F<bin> directory at |
696 | the top level of the distribution. |
dc8021d3 |
697 | |
698 | For backward compatibility, you may use the parameter C<scripts> |
699 | instead of C<script_files>. Please consider this usage deprecated, |
700 | though it will continue to exist for several version releases. |
701 | |
702 | =item sign |
703 | |
704 | [version 0.16] |
705 | |
7a827510 |
706 | If a true value is specified for this parameter, L<Module::Signature> |
dc8021d3 |
707 | will be used (via the 'distsign' action) to create a SIGNATURE file |
708 | for your distribution during the 'distdir' action, and to add the |
709 | SIGNATURE file to the MANIFEST (therefore, don't add it yourself). |
710 | |
711 | The default value is false. In the future, the default may change to |
712 | true if you have C<Module::Signature> installed on your system. |
713 | |
714 | =item test_files |
715 | |
716 | [version 0.23] |
717 | |
718 | An optional parameter specifying a set of files that should be used as |
719 | C<Test::Harness>-style regression tests to be run during the C<test> |
720 | action. May be given as an array reference of the files, or as a hash |
721 | reference whose keys are the files (and whose values will currently be |
722 | ignored). If the argument is given as a single string (not in an |
723 | array reference), that string will be treated as a C<glob()> pattern |
724 | specifying the files to use. |
725 | |
726 | The default is to look for a F<test.pl> script in the top-level |
727 | directory of the distribution, and any files matching the glob pattern |
728 | C<*.t> in the F<t/> subdirectory. If the C<recursive_test_files> |
729 | property is true, then the C<t/> directory will be scanned recursively |
730 | for C<*.t> files. |
731 | |
738349a8 |
732 | =item use_tap_harness |
733 | |
734 | [version 0.2808_03] |
735 | |
736 | An optional parameter indicating whether or not to use TAP::Harness for |
737 | testing rather than Test::Harness. Defaults to false. If set to true, you must |
738 | therefore be sure to add TAP::Harness as a requirement for your module in |
739 | L</build_requires>. Implicitly set to a true value if C<tap_harness_args> is |
740 | specified. |
741 | |
742 | =item tap_harness_args |
743 | |
744 | [version 0.2808_03] |
745 | |
746 | An optional parameter specifying parameters to be passed to TAP::Harness when |
747 | running tests. Must be given as a hash reference of parameters; see the |
748 | L<TAP::Harness|TAP::Harness> documentation for details. Note that specifying |
749 | this parameter will implicitly set C<use_tap_harness> to a true value. You |
750 | must therefore be sure to add TAP::Harness as a requirement for your module in |
751 | L</build_requires>. |
77e96e88 |
752 | |
dc8021d3 |
753 | =item xs_files |
754 | |
755 | [version 0.19] |
756 | |
757 | Just like C<pm_files>, but used for specifying the set of C<.xs> |
758 | files in your distribution. |
759 | |
760 | =back |
761 | |
762 | |
763 | =item new_from_context(%args) |
764 | |
765 | [version 0.28] |
766 | |
767 | When called from a directory containing a F<Build.PL> script and a |
768 | F<META.yml> file (in other words, the base directory of a |
769 | distribution), this method will run the F<Build.PL> and return the |
770 | resulting C<Module::Build> object to the caller. Any key-value |
771 | arguments given to C<new_from_context()> are essentially like |
772 | command line arguments given to the F<Build.PL> script, so for example |
773 | you could pass C<< verbose => 1 >> to this method to turn on |
774 | verbosity. |
775 | |
776 | =item resume() |
777 | |
778 | [version 0.03] |
779 | |
780 | You'll probably never call this method directly, it's only called from |
781 | the auto-generated C<Build> script. The C<new()> method is only |
782 | called once, when the user runs C<perl Build.PL>. Thereafter, when |
783 | the user runs C<Build test> or another action, the C<Module::Build> |
784 | object is created using the C<resume()> method to re-instantiate with |
785 | the settings given earlier to C<new()>. |
786 | |
787 | =item subclass() |
788 | |
789 | [version 0.06] |
790 | |
791 | This creates a new C<Module::Build> subclass on the fly, as described |
792 | in the L<Module::Build::Authoring/"SUBCLASSING"> section. The caller |
793 | must provide either a C<class> or C<code> parameter, or both. The |
794 | C<class> parameter indicates the name to use for the new subclass, and |
795 | defaults to C<MyModuleBuilder>. The C<code> parameter specifies Perl |
796 | code to use as the body of the subclass. |
797 | |
15cb7b9d |
798 | =item add_property |
799 | |
800 | [version 0.31] |
801 | |
802 | package 'My::Build'; |
803 | use base 'Module::Build'; |
804 | __PACKAGE__->add_property( 'pedantic' ); |
805 | __PACKAGE__->add_property( answer => 42 ); |
806 | __PACKAGE__->add_property( |
807 | 'epoch', |
808 | default => sub { time }, |
809 | check => sub { |
810 | return 1 if /^\d+$/; |
811 | shift->property_error( "'$_' is not an epoch time" ); |
812 | return 0; |
813 | }, |
814 | ); |
815 | |
816 | Adds a property to a Module::Build class. Properties are those attributes of a |
817 | Module::Build object which can be passed to the constructor and which have |
818 | accessors to get and set them. All of the core properties, such as |
819 | C<module_name> and C<license>, are defined using this class method. |
820 | |
821 | The first argument to C<add_property()> is always the name of the property. |
822 | The second argument can be either a default value for the property, or a list |
823 | of key/value pairs. The supported keys are: |
824 | |
825 | =over |
826 | |
827 | =item C<default> |
828 | |
829 | The default value. May optionally be specified as a code reference, in which |
830 | case the return value from the execution of the code reference will be used. |
831 | If you need the default to be a code reference, just use a code reference to |
832 | return it, e.g.: |
833 | |
834 | default => sub { sub { ... } }, |
835 | |
836 | =item C<check> |
837 | |
838 | A code reference that checks that a value specified for the property is valid. |
839 | During the execution of the code reference, the new value will be included in |
840 | the C<$_> variable. If the value is correct, the C<check> code reference |
841 | should return true. If the value is not correct, it sends an error message to |
842 | C<property_error()> and returns false. |
843 | |
844 | =back |
845 | |
846 | When this method is called, a new property will be installed in the |
847 | Module::Build class, and an accessor will be built to allow the property to be |
848 | get or set on the build object. |
849 | |
850 | print $build->pedantic, $/; |
851 | $build->pedantic(0); |
852 | |
853 | If the default value is a hash reference, this generetes a special-case |
854 | accessor method, wherein individual key/value pairs may be set or fetched: |
855 | |
856 | print "stuff{foo} is: ", $build->stuff( 'foo' ), $/; |
857 | $build->stuff( foo => 'bar' ); |
858 | print $build->stuff( 'foo' ), $/; # Outputs "bar" |
859 | |
860 | Of course, you can still set the entire hash reference at once, as well: |
861 | |
862 | $build->stuff( { foo => 'bar', baz => 'yo' } ); |
863 | |
864 | In either case, if a C<check> has been specified for the property, it will be |
865 | applied to the entire hash. So the check code reference should look something |
866 | like: |
867 | |
868 | check => sub { |
869 | return 1 if defined $_ && exists $_->{foo}; |
870 | shift->property_error(qq{Property "stuff" needs "foo"}); |
871 | return 0; |
872 | }, |
873 | |
874 | =item property_error |
875 | |
876 | [version 0.31] |
877 | |
dc8021d3 |
878 | =back |
879 | |
880 | |
881 | =head2 METHODS |
882 | |
883 | =over 4 |
884 | |
885 | =item add_build_element($type) |
886 | |
887 | [version 0.26] |
888 | |
889 | Adds a new type of entry to the build process. Accepts a single |
890 | string specifying its type-name. There must also be a method defined |
891 | to process things of that type, e.g. if you add a build element called |
892 | C<'foo'>, then you must also define a method called |
893 | C<process_foo_files()>. |
894 | |
895 | See also |
896 | L<Module::Build::Cookbook/"Adding new file types to the build process">. |
897 | |
898 | =item add_to_cleanup(@files) |
899 | |
900 | [version 0.03] |
901 | |
902 | You may call C<< $self->add_to_cleanup(@patterns) >> to tell |
903 | C<Module::Build> that certain files should be removed when the user |
904 | performs the C<Build clean> action. The arguments to the method are |
905 | patterns suitable for passing to Perl's C<glob()> function, specified |
906 | in either Unix format or the current machine's native format. It's |
907 | usually convenient to use Unix format when you hard-code the filenames |
908 | (e.g. in F<Build.PL>) and the native format when the names are |
909 | programmatically generated (e.g. in a testing script). |
910 | |
911 | I decided to provide a dynamic method of the C<$build> object, rather |
912 | than just use a static list of files named in the F<Build.PL>, because |
913 | these static lists can get difficult to manage. I usually prefer to |
914 | keep the responsibility for registering temporary files close to the |
915 | code that creates them. |
916 | |
917 | =item args() |
918 | |
919 | [version 0.26] |
920 | |
921 | my $args_href = $build->args; |
922 | my %args = $build->args; |
923 | my $arg_value = $build->args($key); |
924 | $build->args($key, $value); |
925 | |
926 | This method is the preferred interface for retrieving the arguments passed via |
927 | command line options to F<Build.PL> or F<Build>, minus the Module-Build |
928 | specific options. |
929 | |
930 | When called in in a scalar context with no arguments, this method returns a |
931 | reference to the hash storing all of the arguments; in an array context, it |
932 | returns the hash itself. When passed a single argument, it returns the value |
933 | stored in the args hash for that option key. When called with two arguments, |
934 | the second argument is assigned to the args hash under the key passed as the |
935 | first argument. |
936 | |
937 | =item autosplit_file($from, $to) |
938 | |
939 | [version 0.28] |
940 | |
7a827510 |
941 | Invokes the L<AutoSplit> module on the C<$from> file, sending the |
dc8021d3 |
942 | output to the C<lib/auto> directory inside C<$to>. C<$to> is |
943 | typically the C<blib/> directory. |
944 | |
945 | =item base_dir() |
946 | |
947 | [version 0.14] |
948 | |
949 | Returns a string containing the root-level directory of this build, |
950 | i.e. where the C<Build.PL> script and the C<lib> directory can be |
951 | found. This is usually the same as the current working directory, |
952 | because the C<Build> script will C<chdir()> into this directory as |
953 | soon as it begins execution. |
954 | |
955 | =item build_requires() |
956 | |
957 | [version 0.21] |
958 | |
959 | Returns a hash reference indicating the C<build_requires> |
960 | prerequisites that were passed to the C<new()> method. |
961 | |
738349a8 |
962 | =item cbuilder() |
963 | |
964 | [version 0.2809] |
965 | |
966 | Returns the internal ExtUtils::CBuilder object that can be used for |
967 | compiling & linking C code. If no such object is available (e.g. if |
968 | the system has no compiler installed) an exception will be thrown. |
969 | |
dc8021d3 |
970 | =item check_installed_status($module, $version) |
971 | |
972 | [version 0.11] |
973 | |
974 | This method returns a hash reference indicating whether a version |
975 | dependency on a certain module is satisfied. The C<$module> argument |
976 | is given as a string like C<"Data::Dumper"> or C<"perl">, and the |
7a827510 |
977 | C<$version> argument can take any of the forms described in L</requires> |
dc8021d3 |
978 | above. This allows very fine-grained version checking. |
979 | |
980 | The returned hash reference has the following structure: |
981 | |
982 | { |
983 | ok => $whether_the_dependency_is_satisfied, |
984 | have => $version_already_installed, |
985 | need => $version_requested, # Same as incoming $version argument |
986 | message => $informative_error_message, |
987 | } |
988 | |
989 | If no version of C<$module> is currently installed, the C<have> value |
990 | will be the string C<< "<none>" >>. Otherwise the C<have> value will |
991 | simply be the version of the installed module. Note that this means |
992 | that if C<$module> is installed but doesn't define a version number, |
993 | the C<have> value will be C<undef> - this is why we don't use C<undef> |
994 | for the case when C<$module> isn't installed at all. |
995 | |
996 | This method may be called either as an object method |
997 | (C<< $build->check_installed_status($module, $version) >>) |
7a827510 |
998 | or as a class method |
dc8021d3 |
999 | (C<< Module::Build->check_installed_status($module, $version) >>). |
1000 | |
1001 | =item check_installed_version($module, $version) |
1002 | |
1003 | [version 0.05] |
1004 | |
7a827510 |
1005 | Like L<check_installed_status()|/"check_installed_status($module, $version)">, |
1006 | but simply returns true or false depending on whether module |
1007 | C<$module> satisfies the dependency C<$version>. |
dc8021d3 |
1008 | |
1009 | If the check succeeds, the return value is the actual version of |
1010 | C<$module> installed on the system. This allows you to do the |
1011 | following: |
1012 | |
1013 | my $installed = $build->check_installed_version('DBI', '1.15'); |
1014 | if ($installed) { |
1015 | print "Congratulations, version $installed of DBI is installed.\n"; |
1016 | } else { |
1017 | die "Sorry, you must install DBI.\n"; |
1018 | } |
1019 | |
1020 | If the check fails, we return false and set C<$@> to an informative |
1021 | error message. |
1022 | |
1023 | If C<$version> is any non-true value (notably zero) and any version of |
1024 | C<$module> is installed, we return true. In this case, if C<$module> |
1025 | doesn't define a version, or if its version is zero, we return the |
1026 | special value "0 but true", which is numerically zero, but logically |
1027 | true. |
1028 | |
1029 | In general you might prefer to use C<check_installed_status> if you |
1030 | need detailed information, or this method if you just need a yes/no |
1031 | answer. |
1032 | |
1033 | =item compare_versions($v1, $op, $v2) |
1034 | |
1035 | [version 0.28] |
1036 | |
1037 | Compares two module versions C<$v1> and C<$v2> using the operator |
1038 | C<$op>, which should be one of Perl's numeric operators like C<!=> or |
1039 | C<< >= >> or the like. We do at least a halfway-decent job of |
1040 | handling versions that aren't strictly numeric, like C<0.27_02>, but |
1041 | exotic stuff will likely cause problems. |
1042 | |
1043 | In the future, the guts of this method might be replaced with a call |
1044 | out to C<version.pm>. |
1045 | |
77e96e88 |
1046 | =item config($key) |
1047 | |
1048 | =item config($key, $value) |
1049 | |
1050 | =item config() [deprecated] |
dc8021d3 |
1051 | |
1052 | [version 0.22] |
1053 | |
77e96e88 |
1054 | With a single argument C<$key>, returns the value associated with that |
1055 | key in the C<Config.pm> hash, including any changes the author or user |
7a827510 |
1056 | has specified. |
77e96e88 |
1057 | |
1058 | With C<$key> and C<$value> arguments, sets the value for future |
1059 | callers of C<config($key)>. |
1060 | |
1061 | With no arguments, returns a hash reference containing all such |
1062 | key-value pairs. This usage is deprecated, though, because it's a |
1063 | resource hog and violates encapsulation. |
dc8021d3 |
1064 | |
1065 | =item config_data($name) |
1066 | |
1067 | =item config_data($name => $value) |
1068 | |
1069 | [version 0.26] |
1070 | |
1071 | With a single argument, returns the value of the configuration |
1072 | variable C<$name>. With two arguments, sets the given configuration |
7a827510 |
1073 | variable to the given value. The value may be any Perl scalar that's |
dc8021d3 |
1074 | serializable with C<Data::Dumper>. For instance, if you write a |
1075 | module that can use a MySQL or PostgreSQL back-end, you might create |
1076 | configuration variables called C<mysql_connect> and |
1077 | C<postgres_connect>, and set each to an array of connection parameters |
1078 | for C<< DBI->connect() >>. |
1079 | |
1080 | Configuration values set in this way using the Module::Build object |
1081 | will be available for querying during the build/test process and after |
1082 | installation via the generated C<...::ConfigData> module, as |
1083 | C<< ...::ConfigData->config($name) >>. |
1084 | |
7a827510 |
1085 | The L<feature()|/"feature($name)"> and C<config_data()> methods represent |
dc8021d3 |
1086 | Module::Build's main support for configuration of installed modules. |
1087 | See also L<Module::Build::Authoring/"SAVING CONFIGURATION INFORMATION">. |
1088 | |
1089 | =item conflicts() |
1090 | |
1091 | [version 0.21] |
1092 | |
1093 | Returns a hash reference indicating the C<conflicts> prerequisites |
1094 | that were passed to the C<new()> method. |
1095 | |
1096 | =item contains_pod($file) |
1097 | |
1098 | [version 0.20] |
1099 | |
1100 | [Deprecated] Please see L<Module::Build::ModuleInfo> instead. |
1101 | |
1102 | Returns true if the given file appears to contain POD documentation. |
1103 | Currently this checks whether the file has a line beginning with |
1104 | '=pod', '=head', or '=item', but the exact semantics may change in the |
1105 | future. |
1106 | |
1107 | =item copy_if_modified(%parameters) |
1108 | |
1109 | [version 0.19] |
1110 | |
1111 | Takes the file in the C<from> parameter and copies it to the file in |
1112 | the C<to> parameter, or the directory in the C<to_dir> parameter, if |
1113 | the file has changed since it was last copied (or if it doesn't exist |
1114 | in the new location). By default the entire directory structure of |
1115 | C<from> will be copied into C<to_dir>; an optional C<flatten> |
1116 | parameter will copy into C<to_dir> without doing so. |
1117 | |
1118 | Returns the path to the destination file, or C<undef> if nothing |
1119 | needed to be copied. |
1120 | |
1121 | Any directories that need to be created in order to perform the |
1122 | copying will be automatically created. |
1123 | |
1124 | The destination file is set to read-only. If the source file has the |
1125 | executable bit set, then the destination file will be made executable. |
1126 | |
1127 | =item create_build_script() |
1128 | |
1129 | [version 0.05] |
1130 | |
1131 | Creates an executable script called C<Build> in the current directory |
1132 | that will be used to execute further user actions. This script is |
1133 | roughly analogous (in function, not in form) to the Makefile created |
1134 | by C<ExtUtils::MakeMaker>. This method also creates some temporary |
1135 | data in a directory called C<_build/>. Both of these will be removed |
1136 | when the C<realclean> action is performed. |
1137 | |
7253302f |
1138 | Among the files created in C<_build/> is a F<_build/prereqs> file |
1139 | containing the set of prerequisites for this distribution, as a hash |
1140 | of hashes. This file may be C<eval()>-ed to obtain the authoritative |
7a827510 |
1141 | set of prereqs, which might be different from the contents of |
1142 | F<META.yml> (because F<Build.PL> might have set them dynamically). |
1143 | But fancy developers take heed: do not put any fancy custom runtime |
1144 | code in the F<_build/prereqs> file, leave it as a static declaration |
1145 | containing only strings and numbers. Similarly, do not alter the |
1146 | structure of the internal C<< $self->{properties}{requires} >> (etc.) |
1147 | data members, because that's where this data comes from. |
7253302f |
1148 | |
dc8021d3 |
1149 | =item current_action() |
1150 | |
1151 | [version 0.28] |
1152 | |
1153 | Returns the name of the currently-running action, such as "build" or |
1154 | "test". This action is not necessarily the action that was originally |
1155 | invoked by the user. For example, if the user invoked the "test" |
1156 | action, current_action() would initially return "test". However, |
1157 | action "test" depends on action "code", so current_action() will |
1158 | return "code" while that dependency is being executed. Once that |
1159 | action has completed, current_action() will again return "test". |
1160 | |
1161 | If you need to know the name of the original action invoked by the |
7a827510 |
1162 | user, see L</invoked_action()> below. |
dc8021d3 |
1163 | |
1164 | =item depends_on(@actions) |
1165 | |
1166 | [version 0.28] |
1167 | |
1168 | Invokes the named action or list of actions in sequence. Using this |
1169 | method is preferred to calling the action explicitly because it |
1170 | performs some internal record-keeping, and it ensures that the same |
1171 | action is not invoked multiple times (note: in future versions of |
1172 | Module::Build it's conceivable that this run-only-once mechanism will |
1173 | be changed to something more intelligent). |
1174 | |
1175 | Note that the name of this method is something of a misnomer; it |
1176 | should really be called something like |
1177 | C<invoke_actions_unless_already_invoked()> or something, but for |
1178 | better or worse (perhaps better!) we were still thinking in |
1179 | C<make>-like dependency terms when we created this method. |
1180 | |
7a827510 |
1181 | See also L<dispatch()|/"dispatch($action, %args)">. The main |
1182 | distinction between the two is that C<depends_on()> is meant to call |
1183 | an action from inside another action, whereas C<dispatch()> is meant |
1184 | to set the very top action in motion. |
dc8021d3 |
1185 | |
1186 | =item dir_contains($first_dir, $second_dir) |
1187 | |
1188 | [version 0.28] |
1189 | |
1190 | Returns true if the first directory logically contains the second |
1191 | directory. This is just a convenience function because C<File::Spec> |
1192 | doesn't really provide an easy way to figure this out (but |
1193 | C<Path::Class> does...). |
1194 | |
1195 | =item dispatch($action, %args) |
1196 | |
1197 | [version 0.03] |
1198 | |
1199 | Invokes the build action C<$action>. Optionally, a list of options |
1200 | and their values can be passed in. This is equivalent to invoking an |
1201 | action at the command line, passing in a list of options. |
1202 | |
1203 | Custom options that have not been registered must be passed in as a |
1204 | hash reference in a key named "args": |
1205 | |
1206 | $build->dispatch('foo', verbose => 1, args => { my_option => 'value' }); |
1207 | |
1208 | This method is intended to be used to programmatically invoke build |
1209 | actions, e.g. by applications controlling Module::Build-based builds |
1210 | rather than by subclasses. |
1211 | |
7a827510 |
1212 | See also L<depends_on()|/"depends_on(@actions)">. The main |
1213 | distinction between the two is that C<depends_on()> is meant to call |
1214 | an action from inside another action, whereas C<dispatch()> is meant |
1215 | to set the very top action in motion. |
dc8021d3 |
1216 | |
1217 | =item dist_dir() |
1218 | |
1219 | [version 0.28] |
1220 | |
1221 | Returns the name of the directory that will be created during the |
1222 | C<dist> action. The name is derived from the C<dist_name> and |
1223 | C<dist_version> properties. |
1224 | |
1225 | =item dist_name() |
1226 | |
1227 | [version 0.21] |
1228 | |
1229 | Returns the name of the current distribution, as passed to the |
1230 | C<new()> method in a C<dist_name> or modified C<module_name> |
1231 | parameter. |
1232 | |
1233 | =item dist_version() |
1234 | |
1235 | [version 0.21] |
1236 | |
1237 | Returns the version of the current distribution, as determined by the |
1238 | C<new()> method from a C<dist_version>, C<dist_version_from>, or |
1239 | C<module_name> parameter. |
1240 | |
1241 | =item do_system($cmd, @args) |
1242 | |
1243 | [version 0.21] |
1244 | |
1245 | This is a fairly simple wrapper around Perl's C<system()> built-in |
1246 | command. Given a command and an array of optional arguments, this |
1247 | method will print the command to C<STDOUT>, and then execute it using |
1248 | Perl's C<system()>. It returns true or false to indicate success or |
1249 | failure (the opposite of how C<system()> works, but more intuitive). |
1250 | |
1251 | Note that if you supply a single argument to C<do_system()>, it |
1252 | will/may be processed by the systems's shell, and any special |
1253 | characters will do their special things. If you supply multiple |
1254 | arguments, no shell will get involved and the command will be executed |
1255 | directly. |
1256 | |
1257 | =item feature($name) |
1258 | |
1259 | =item feature($name => $value) |
1260 | |
1261 | [version 0.26] |
1262 | |
1263 | With a single argument, returns true if the given feature is set. |
1264 | With two arguments, sets the given feature to the given boolean value. |
1265 | In this context, a "feature" is any optional functionality of an |
1266 | installed module. For instance, if you write a module that could |
1267 | optionally support a MySQL or PostgreSQL backend, you might create |
1268 | features called C<mysql_support> and C<postgres_support>, and set them |
1269 | to true/false depending on whether the user has the proper databases |
1270 | installed and configured. |
1271 | |
1272 | Features set in this way using the Module::Build object will be |
1273 | available for querying during the build/test process and after |
7a827510 |
1274 | installation via the generated C<...::ConfigData> module, as |
dc8021d3 |
1275 | C<< ...::ConfigData->feature($name) >>. |
1276 | |
1277 | The C<feature()> and C<config_data()> methods represent |
1278 | Module::Build's main support for configuration of installed modules. |
1279 | See also L<Module::Build::Authoring/"SAVING CONFIGURATION INFORMATION">. |
1280 | |
738349a8 |
1281 | =item fix_shebang_line(@files) |
1282 | |
1283 | [version 0.??] |
1284 | |
1285 | Modify any "shebang" line in the specified files to use the path to the |
1286 | perl executable being used for the current build. Files are modified |
1287 | in-place. The existing shebang line must have a command that contains |
1288 | "C<perl>"; arguments to the command do not count. In particular, this |
1289 | means that the use of C<#!/usr/bin/env perl> will not be changed. |
1290 | |
1291 | For an explanation of shebang lines, see |
1292 | L<http://en.wikipedia.org/wiki/Shebang_%28Unix%29>. |
1293 | |
dc8021d3 |
1294 | =item have_c_compiler() |
1295 | |
1296 | [version 0.21] |
1297 | |
1298 | Returns true if the current system seems to have a working C compiler. |
1299 | We currently determine this by attempting to compile a simple C source |
1300 | file and reporting whether the attempt was successful. |
1301 | |
1302 | =item install_base_relpaths() |
1303 | |
1304 | =item install_base_relpaths($type) |
1305 | |
1306 | =item install_base_relpaths($type => $path) |
1307 | |
1308 | [version 0.28] |
1309 | |
1310 | Set or retrieve the relative paths that are appended to |
1311 | C<install_base> for any installable element. This is useful if you |
1312 | want to set the relative install path for custom build elements. |
1313 | |
1314 | With no argument, it returns a reference to a hash containing all |
1315 | elements and their respective values. This hash should not be modified |
1316 | directly; use the multi-argument below form to change values. |
1317 | |
1318 | The single argument form returns the value associated with the |
1319 | element C<$type>. |
1320 | |
1321 | The multi-argument form allows you to set the paths for element types. |
1322 | C<$value> must be a relative path using unix-like paths. (A series of |
1323 | directories seperated by slashes. Eg 'foo/bar'.) The return value is a |
1324 | localized path based on C<$value>. |
1325 | |
1326 | Assigning the value C<undef> to an element causes it to be removed. |
1327 | |
1328 | =item install_destination($type) |
1329 | |
1330 | [version 0.28] |
1331 | |
1332 | Returns the directory in which items of type C<$type> (e.g. C<lib>, |
7a827510 |
1333 | C<arch>, C<bin>, or anything else returned by the L</install_types()> |
dc8021d3 |
1334 | method) will be installed during the C<install> action. Any settings |
1335 | for C<install_path>, C<install_base>, and C<prefix> are taken into |
1336 | account when determining the return value. |
1337 | |
1338 | =item install_path() |
1339 | |
1340 | =item install_path($type) |
1341 | |
1342 | =item install_path($type => $path) |
1343 | |
1344 | [version 0.28] |
1345 | |
1346 | Set or retrieve paths for specific installable elements. This is |
1347 | useful when you want to examine any explicit install paths specified |
1348 | by the user on the command line, or if you want to set the install |
1349 | path for a specific installable element based on another attribute |
1350 | like C<install_base()>. |
1351 | |
1352 | With no argument, it returns a reference to a hash containing all |
1353 | elements and their respective values. This hash should not be modified |
1354 | directly; use the multi-argument below form to change values. |
1355 | |
1356 | The single argument form returns the value associated with the |
1357 | element C<$type>. |
1358 | |
1359 | The multi-argument form allows you to set the paths for element types. |
1360 | The supplied C<$path> should be an absolute path to install elements |
1361 | of C<$type>. The return value is C<$path>. |
1362 | |
1363 | Assigning the value C<undef> to an element causes it to be removed. |
1364 | |
1365 | =item install_types() |
1366 | |
1367 | [version 0.28] |
1368 | |
1369 | Returns a list of installable types that this build knows about. |
1370 | These types each correspond to the name of a directory in F<blib/>, |
1371 | and the list usually includes items such as C<lib>, C<arch>, C<bin>, |
1372 | C<script>, C<libdoc>, C<bindoc>, and if HTML documentation is to be |
1373 | built, C<libhtml> and C<binhtml>. Other user-defined types may also |
1374 | exist. |
1375 | |
1376 | =item invoked_action() |
1377 | |
1378 | [version 0.28] |
1379 | |
1380 | This is the name of the original action invoked by the user. This |
1381 | value is set when the user invokes F<Build.PL>, the F<Build> script, |
7a827510 |
1382 | or programatically through the L<dispatch()|/"dispatch($action, %args)"> |
1383 | method. It does not change as sub-actions are executed as |
1384 | dependencies are evaluated. |
dc8021d3 |
1385 | |
1386 | To get the name of the currently executing dependency, see |
7a827510 |
1387 | L</current_action()> above. |
dc8021d3 |
1388 | |
1389 | =item notes() |
1390 | |
1391 | =item notes($key) |
1392 | |
1393 | =item notes($key => $value) |
1394 | |
1395 | [version 0.20] |
1396 | |
1397 | The C<notes()> value allows you to store your own persistent |
1398 | information about the build, and to share that information among |
1399 | different entities involved in the build. See the example in the |
1400 | C<current()> method. |
1401 | |
1402 | The C<notes()> method is essentally a glorified hash access. With no |
1403 | arguments, C<notes()> returns the entire hash of notes. With one argument, |
1404 | C<notes($key)> returns the value associated with the given key. With two |
1405 | arguments, C<notes($key, $value)> sets the value associated with the given key |
1406 | to C<$value> and returns the new value. |
1407 | |
1408 | The lifetime of the C<notes> data is for "a build" - that is, the |
1409 | C<notes> hash is created when C<perl Build.PL> is run (or when the |
1410 | C<new()> method is run, if the Module::Build Perl API is being used |
1411 | instead of called from a shell), and lasts until C<perl Build.PL> is |
1412 | run again or the C<clean> action is run. |
1413 | |
1414 | =item orig_dir() |
1415 | |
1416 | [version 0.28] |
1417 | |
1418 | Returns a string containing the working directory that was in effect |
1419 | before the F<Build> script chdir()-ed into the C<base_dir>. This |
1420 | might be useful for writing wrapper tools that might need to chdir() |
1421 | back out. |
1422 | |
1423 | =item os_type() |
1424 | |
1425 | [version 0.04] |
1426 | |
1427 | If you're subclassing Module::Build and some code needs to alter its |
1428 | behavior based on the current platform, you may only need to know |
1429 | whether you're running on Windows, Unix, MacOS, VMS, etc., and not the |
1430 | fine-grained value of Perl's C<$^O> variable. The C<os_type()> method |
1431 | will return a string like C<Windows>, C<Unix>, C<MacOS>, C<VMS>, or |
1432 | whatever is appropriate. If you're running on an unknown platform, it |
1433 | will return C<undef> - there shouldn't be many unknown platforms |
1434 | though. |
1435 | |
c1d8f74e |
1436 | =item is_vmsish() |
1437 | |
1438 | =item is_windowsish() |
1439 | |
1440 | =item is_unixish() |
1441 | |
1442 | Convenience functions that return a boolean value indicating whether |
1443 | this platform behaves respectively like VMS, Windows, or Unix. For |
1444 | arbitrary reasons other platforms don't get their own such functions, |
1445 | at least not yet. |
1446 | |
1447 | |
dc8021d3 |
1448 | =item prefix_relpaths() |
1449 | |
1450 | =item prefix_relpaths($installdirs) |
1451 | |
1452 | =item prefix_relpaths($installdirs, $type) |
1453 | |
1454 | =item prefix_relpaths($installdirs, $type => $path) |
1455 | |
1456 | [version 0.28] |
1457 | |
1458 | Set or retrieve the relative paths that are appended to C<prefix> for |
1459 | any installable element. This is useful if you want to set the |
1460 | relative install path for custom build elements. |
1461 | |
1462 | With no argument, it returns a reference to a hash containing all |
1463 | elements and their respective values as defined by the current |
1464 | C<installdirs> setting. |
1465 | |
1466 | With a single argument, it returns a reference to a hash containing |
1467 | all elements and their respective values as defined by |
1468 | C<$installdirs>. |
1469 | |
1470 | The hash returned by the above calls should not be modified directly; |
1471 | use the three-argument below form to change values. |
1472 | |
1473 | The two argument form returns the value associated with the |
1474 | element C<$type>. |
1475 | |
1476 | The multi-argument form allows you to set the paths for element types. |
1477 | C<$value> must be a relative path using unix-like paths. (A series of |
1478 | directories seperated by slashes. Eg 'foo/bar'.) The return value is a |
1479 | localized path based on C<$value>. |
1480 | |
1481 | Assigning the value C<undef> to an element causes it to be removed. |
1482 | |
1483 | =item prepare_metadata() |
1484 | |
1485 | [version 0.28] |
1486 | |
1487 | This method is provided for authors to override to customize the |
1488 | fields of F<META.yml>. It is passed a YAML::Node node object which can |
1489 | be modified as desired and then returned. E.g. |
1490 | |
1491 | package My::Builder; |
1492 | use base 'Module::Build'; |
1493 | |
1494 | sub prepare_metadata { |
1495 | my $self = shift; |
1496 | my $node = $self->SUPER::prepare_metadata( shift ); |
1497 | $node->{custom_field} = 'foo'; |
1498 | return $node; |
1499 | } |
1500 | |
1501 | =item prereq_failures() |
1502 | |
1503 | [version 0.11] |
1504 | |
1505 | Returns a data structure containing information about any failed |
1506 | prerequisites (of any of the types described above), or C<undef> if |
1507 | all prerequisites are met. |
1508 | |
1509 | The data structure returned is a hash reference. The top level keys |
1510 | are the type of prerequisite failed, one of "requires", |
1511 | "build_requires", "conflicts", or "recommends". The associated values |
1512 | are hash references whose keys are the names of required (or |
1513 | conflicting) modules. The associated values of those are hash |
1514 | references indicating some information about the failure. For example: |
1515 | |
1516 | { |
1517 | have => '0.42', |
1518 | need => '0.59', |
1519 | message => 'Version 0.42 is installed, but we need version 0.59', |
1520 | } |
1521 | |
1522 | or |
1523 | |
1524 | { |
1525 | have => '<none>', |
1526 | need => '0.59', |
1527 | message => 'Prerequisite Foo isn't installed', |
1528 | } |
1529 | |
1530 | This hash has the same structure as the hash returned by the |
1531 | C<check_installed_status()> method, except that in the case of |
1532 | "conflicts" dependencies we change the "need" key to "conflicts" and |
1533 | construct a proper message. |
1534 | |
1535 | Examples: |
1536 | |
1537 | # Check a required dependency on Foo::Bar |
1538 | if ( $build->prereq_failures->{requires}{Foo::Bar} ) { ... |
1539 | |
1540 | # Check whether there were any failures |
1541 | if ( $build->prereq_failures ) { ... |
1542 | |
1543 | # Show messages for all failures |
1544 | my $failures = $build->prereq_failures; |
1545 | while (my ($type, $list) = each %$failures) { |
1546 | while (my ($name, $hash) = each %$list) { |
1547 | print "Failure for $name: $hash->{message}\n"; |
1548 | } |
1549 | } |
1550 | |
1551 | =item prereq_report() |
1552 | |
1553 | [version 0.28] |
1554 | |
1555 | Returns a human-readable (table-form) string showing all |
1556 | prerequisites, the versions required, and the versions actually |
1557 | installed. This can be useful for reviewing the configuration of your |
1558 | system prior to a build, or when compiling data to send for a bug |
1559 | report. The C<prereq_report> action is just a thin wrapper around the |
1560 | C<prereq_report()> method. |
1561 | |
1562 | =item prompt($message, $default) |
1563 | |
1564 | [version 0.12] |
1565 | |
1566 | Asks the user a question and returns their response as a string. The |
1567 | first argument specifies the message to display to the user (for |
1568 | example, C<"Where do you keep your money?">). The second argument, |
1569 | which is optional, specifies a default answer (for example, |
1570 | C<"wallet">). The user will be asked the question once. |
1571 | |
1572 | If C<prompt()> detects that it is not running interactively and there |
1573 | is nothing on STDIN or if the PERL_MM_USE_DEFAULT environment variable |
7253302f |
1574 | is set to true, the $default will be used without prompting. |
1575 | |
1576 | To prevent automated processes from blocking, the user must either set |
1577 | PERL_MM_USE_DEFAULT or attach something to STDIN (this can be a |
1578 | pipe/file containing a scripted set of answers or /dev/null.) |
dc8021d3 |
1579 | |
7253302f |
1580 | If no $default is provided an empty string will be used instead. In |
1581 | non-interactive mode, the absence of $default is an error (though |
1582 | explicitly passing C<undef()> as the default is valid as of 0.27.) |
dc8021d3 |
1583 | |
1584 | This method may be called as a class or object method. |
1585 | |
1586 | =item recommends() |
1587 | |
1588 | [version 0.21] |
1589 | |
1590 | Returns a hash reference indicating the C<recommends> prerequisites |
1591 | that were passed to the C<new()> method. |
1592 | |
1593 | =item requires() |
1594 | |
1595 | [version 0.21] |
1596 | |
1597 | Returns a hash reference indicating the C<requires> prerequisites that |
1598 | were passed to the C<new()> method. |
1599 | |
1600 | =item rscan_dir($dir, $pattern) |
1601 | |
1602 | [version 0.28] |
1603 | |
1604 | Uses C<File::Find> to traverse the directory C<$dir>, returning a |
1605 | reference to an array of entries matching C<$pattern>. C<$pattern> |
1606 | may either be a regular expression (using C<qr//> or just a plain |
1607 | string), or a reference to a subroutine that will return true for |
1608 | wanted entries. If C<$pattern> is not given, all entries will be |
1609 | returned. |
1610 | |
1611 | Examples: |
1612 | |
1613 | # All the *.pm files in lib/ |
1614 | $m->rscan_dir('lib', qr/\.pm$/) |
7a827510 |
1615 | |
dc8021d3 |
1616 | # All the files in blib/ that aren't *.html files |
1617 | $m->rscan_dir('blib', sub {-f $_ and not /\.html$/}); |
1618 | |
1619 | # All the files in t/ |
1620 | $m->rscan_dir('t'); |
1621 | |
1622 | =item runtime_params() |
1623 | |
1624 | =item runtime_params($key) |
1625 | |
1626 | [version 0.28] |
1627 | |
1628 | The C<runtime_params()> method stores the values passed on the command line |
1629 | for valid properties (that is, any command line options for which |
1630 | C<valid_property()> returns a true value). The value on the command line may |
1631 | override the default value for a property, as well as any value specified in a |
1632 | call to C<new()>. This allows you to programmatically tell if C<perl Build.PL> |
1633 | or any execution of C<./Build> had command line options specified that |
1634 | override valid properties. |
1635 | |
1636 | The C<runtime_params()> method is essentally a glorified read-only hash. With |
1637 | no arguments, C<runtime_params()> returns the entire hash of properties |
1638 | specified on the command line. With one argument, C<runtime_params($key)> |
1639 | returns the value associated with the given key. |
1640 | |
1641 | The lifetime of the C<runtime_params> data is for "a build" - that is, the |
1642 | C<runtime_params> hash is created when C<perl Build.PL> is run (or when the |
1643 | C<new()> method is called, if the Module::Build Perl API is being used instead |
1644 | of called from a shell), and lasts until C<perl Build.PL> is run again or the |
1645 | C<clean> action is run. |
1646 | |
1647 | =item script_files() |
1648 | |
1649 | [version 0.18] |
1650 | |
1651 | Returns a hash reference whose keys are the perl script files to be |
1652 | installed, if any. This corresponds to the C<script_files> parameter to the |
1653 | C<new()> method. With an optional argument, this parameter may be set |
1654 | dynamically. |
1655 | |
1656 | For backward compatibility, the C<scripts()> method does exactly the |
1657 | same thing as C<script_files()>. C<scripts()> is deprecated, but it |
1658 | will stay around for several versions to give people time to |
1659 | transition. |
1660 | |
1661 | =item up_to_date($source_file, $derived_file) |
1662 | |
1663 | =item up_to_date(\@source_files, \@derived_files) |
1664 | |
1665 | [version 0.20] |
1666 | |
1667 | This method can be used to compare a set of source files to a set of |
1668 | derived files. If any of the source files are newer than any of the |
1669 | derived files, it returns false. Additionally, if any of the derived |
1670 | files do not exist, it returns false. Otherwise it returns true. |
1671 | |
1672 | The arguments may be either a scalar or an array reference of file |
1673 | names. |
1674 | |
1675 | =item y_n($message, $default) |
1676 | |
1677 | [version 0.12] |
1678 | |
1679 | Asks the user a yes/no question using C<prompt()> and returns true or |
1680 | false accordingly. The user will be asked the question repeatedly |
1681 | until they give an answer that looks like "yes" or "no". |
1682 | |
1683 | The first argument specifies the message to display to the user (for |
1684 | example, C<"Shall I invest your money for you?">), and the second |
1685 | argument specifies the default answer (for example, C<"y">). |
1686 | |
1687 | Note that the default is specified as a string like C<"y"> or C<"n">, |
1688 | and the return value is a Perl boolean value like 1 or 0. I thought |
1689 | about this for a while and this seemed like the most useful way to do |
1690 | it. |
1691 | |
1692 | This method may be called as a class or object method. |
1693 | |
1694 | =back |
1695 | |
1696 | |
1697 | =head2 Autogenerated Accessors |
1698 | |
1699 | In addition to the aforementioned methods, there are also some get/set |
1700 | accessor methods for the following properties: |
1701 | |
1702 | =over 4 |
1703 | |
1704 | =item PL_files() |
1705 | |
0ec9ad96 |
1706 | =item allow_mb_mismatch() |
1707 | |
dc8021d3 |
1708 | =item autosplit() |
1709 | |
1710 | =item base_dir() |
1711 | |
1712 | =item bindoc_dirs() |
1713 | |
1714 | =item blib() |
1715 | |
1716 | =item build_bat() |
1717 | |
1718 | =item build_class() |
1719 | |
1720 | =item build_elements() |
1721 | |
1722 | =item build_requires() |
1723 | |
1724 | =item build_script() |
1725 | |
1726 | =item c_source() |
1727 | |
dc8021d3 |
1728 | =item config_dir() |
1729 | |
7a827510 |
1730 | =item configure_requires() |
1731 | |
dc8021d3 |
1732 | =item conflicts() |
1733 | |
15cb7b9d |
1734 | =item create_license() |
1735 | |
dc8021d3 |
1736 | =item create_makefile_pl() |
1737 | |
1738 | =item create_packlist() |
1739 | |
1740 | =item create_readme() |
1741 | |
1742 | =item debugger() |
1743 | |
1744 | =item destdir() |
1745 | |
1746 | =item get_options() |
1747 | |
1748 | =item html_css() |
1749 | |
1750 | =item include_dirs() |
1751 | |
1752 | =item install_base() |
1753 | |
1754 | =item install_sets() |
1755 | |
1756 | =item installdirs() |
1757 | |
1758 | =item libdoc_dirs() |
1759 | |
1760 | =item license() |
1761 | |
1762 | =item magic_number() |
1763 | |
1764 | =item mb_version() |
1765 | |
1766 | =item meta_add() |
1767 | |
1768 | =item meta_merge() |
1769 | |
1770 | =item metafile() |
1771 | |
1772 | =item module_name() |
1773 | |
1774 | =item orig_dir() |
1775 | |
1776 | =item original_prefix() |
1777 | |
1778 | =item perl() |
1779 | |
1780 | =item pm_files() |
1781 | |
1782 | =item pod_files() |
1783 | |
1784 | =item pollute() |
1785 | |
1786 | =item prefix() |
1787 | |
1788 | =item prereq_action_types() |
1789 | |
738349a8 |
1790 | =item program_name() |
1791 | |
dc8021d3 |
1792 | =item quiet() |
1793 | |
1794 | =item recommends() |
1795 | |
1796 | =item recurse_into() |
1797 | |
1798 | =item recursive_test_files() |
1799 | |
1800 | =item requires() |
1801 | |
1802 | =item scripts() |
1803 | |
738349a8 |
1804 | =item sign() |
1805 | |
1806 | =item tap_harness_args() |
1807 | |
1808 | =item test_file_exts() |
1809 | |
dc8021d3 |
1810 | =item use_rcfile() |
1811 | |
738349a8 |
1812 | =item use_tap_harness() |
1813 | |
dc8021d3 |
1814 | =item verbose() |
1815 | |
1816 | =item xs_files() |
1817 | |
1818 | =back |
1819 | |
1820 | |
7a827510 |
1821 | =head1 MODULE METADATA |
1822 | |
1823 | If you would like to add other useful metadata, C<Module::Build> |
1824 | supports this with the C<meta_add> and C<meta_merge> arguments to |
1825 | L</new>. The authoritative list of supported metadata can be found at |
1826 | L<http://module-build.sourceforge.net/META-spec-current.html>, but for |
1827 | convenience - here are a few of the more useful ones: |
1828 | |
1829 | =over 4 |
1830 | |
1831 | =item keywords |
1832 | |
1833 | For describing the distribution using keyword (or "tags") in order to |
1834 | make CPAN.org indexing and search more efficient and useful. |
1835 | |
1836 | See L<http://module-build.sourceforge.net/META-spec-current.html#keywords>. |
1837 | |
1838 | =item resources |
1839 | |
1840 | A list of additional resources available for users of the |
1841 | distribution. This can include links to a homepage on the web, a |
1842 | bugtracker, the repository location, a even subscription page for the |
1843 | distribution mailing list. |
1844 | |
1845 | See L<http://module-build.sourceforge.net/META-spec-current.html#resources>. |
1846 | |
1847 | =back |
1848 | |
1849 | |
dc8021d3 |
1850 | =head1 AUTHOR |
1851 | |
1852 | Ken Williams <kwilliams@cpan.org> |
1853 | |
1854 | |
1855 | =head1 COPYRIGHT |
1856 | |
1857 | Copyright (c) 2001-2006 Ken Williams. All rights reserved. |
1858 | |
1859 | This library is free software; you can redistribute it and/or |
1860 | modify it under the same terms as Perl itself. |
1861 | |
1862 | |
1863 | =head1 SEE ALSO |
1864 | |
1865 | perl(1), L<Module::Build>(3), L<Module::Build::Authoring>(3), |
1866 | L<Module::Build::Cookbook>(3), L<ExtUtils::MakeMaker>(3), L<YAML>(3) |
1867 | |
1868 | F<META.yml> Specification: |
77e96e88 |
1869 | L<http://module-build.sourceforge.net/META-spec-current.html> |
dc8021d3 |
1870 | |
1871 | =cut |