1Module::Build::API(3) User Contributed Perl DocumentationModule::Build::API(3)
2
3
4

NAME

6       Module::Build::API - API Reference for Module Authors
7

DESCRIPTION

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

MODULE METADATA

1894       If you would like to add other useful metadata, "Module::Build"
1895       supports this with the "meta_add" and "meta_merge" arguments to
1896       "new()". The authoritative list of supported metadata can be found at
1897       CPAN::Meta::Spec but for convenience - here are a few of the more
1898       useful ones:
1899
1900       keywords
1901           For describing the distribution using keyword (or "tags") in order
1902           to make CPAN.org indexing and search more efficient and useful.
1903
1904       resources
1905           A list of additional resources available for users of the
1906           distribution. This can include links to a homepage on the web, a
1907           bug tracker, the repository location, and even a subscription page
1908           for the distribution mailing list.
1909

AUTHOR

1911       Ken Williams <kwilliams@cpan.org>
1912
1914       Copyright (c) 2001-2006 Ken Williams.  All rights reserved.
1915
1916       This library is free software; you can redistribute it and/or modify it
1917       under the same terms as Perl itself.
1918

SEE ALSO

1920       perl(1), Module::Build(3), Module::Build::Authoring(3),
1921       Module::Build::Cookbook(3), ExtUtils::MakeMaker(3)
1922
1923       META.yml Specification: CPAN::Meta::Spec
1924
1925
1926
1927perl v5.30.1                      2020-01-29             Module::Build::API(3)
Impressum