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