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