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

MODULE METADATA

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

AUTHOR

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

SEE ALSO

1918       perl(1), Module::Build(3), Module::Build::Authoring(3),
1919       Module::Build::Cookbook(3), ExtUtils::MakeMaker(3)
1920
1921       META.yml Specification: CPAN::Meta::Spec
1922
1923
1924
1925perl v5.30.0                      2019-07-26             Module::Build::API(3)
Impressum