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