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