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 License,
429 Version 2.0 (http://apache.org/licenses/LICENSE-2.0
430 <http://apache.org/licenses/LICENSE-2.0>).
431 apache_1_1
433 The distribution is licensed under the Apache Software
434 License, Version 1.1
435 (http://apache.org/licenses/LICENSE-1.1
436 <http://apache.org/licenses/LICENSE-1.1>).
437 artistic
439 The distribution is licensed under the Artistic License, as
440 specified by the Artistic file in the standard Perl
441 distribution.
442 artistic_2
444 The distribution is licensed under the Artistic 2.0 License
445 (http://opensource.org/licenses/artistic-license-2.0.php
446 <http://opensource.org/licenses/artistic-license-2.0.php>.)
447 bsd The distribution is licensed under the BSD License
449 (http://www.opensource.org/licenses/bsd-license.php
450 <http://www.opensource.org/licenses/bsd-license.php>).
451 gpl The distribution is licensed under the terms of the GNU
453 General Public License
454 (http://www.opensource.org/licenses/gpl-license.php
455 <http://www.opensource.org/licenses/gpl-license.php>).
456 lgpl
458 The distribution is licensed under the terms of the GNU
459 Lesser General Public License
460 (http://www.opensource.org/licenses/lgpl-license.php
461 <http://www.opensource.org/licenses/lgpl-license.php>).
462 mit The distribution is licensed under the MIT License
464 (http://opensource.org/licenses/mit-license.php
465 <http://opensource.org/licenses/mit-license.php>).
466 mozilla
468 The distribution is licensed under the Mozilla Public
469 License. (<http://opensource.org/licenses/mozilla1.0.php>
470 or <http://opensource.org/licenses/mozilla1.1.php>)
471 open_source
473 The distribution is licensed under some other Open Source
474 Initiative-approved license listed at
475 <http://www.opensource.org/licenses/>.
476 perl
478 The distribution may be copied and redistributed under the
479 same terms as Perl itself (this is by far the most common
480 licensing option for modules on CPAN). This is a dual
481 license, in which the user may choose between either the
482 GPL or the Artistic license.
483 restrictive
485 The distribution may not be redistributed without special
486 permission from the author and/or copyright holder.
487 unrestricted
489 The distribution is licensed under a license that is not
490 approved by www.opensource.org but that allows distribution
491 without restrictions.
492 Note that you must still include the terms of your license in
494 your documentation - this field only lets automated tools
495 figure out your licensing restrictions. Humans still need
496 something to read. If you choose to provide this field, you
497 should make sure that you keep it in sync with your written
498 documentation if you ever change your licensing terms.
499 You may also use a license type of "unknown" if you don't wish
501 to specify your terms in the metadata.
502 It is a fatal error to use a license other than the ones
504 mentioned above. This is not because I wish to impose
505 licensing terms on you - please let me know if you would like
506 another license option to be added to the list. I just started
507 out with a small set of licenses to keep things simple,
508 figuring I'd let people with actual working knowledge in this
509 area tell me what to do. So if that's you, drop me a line.
510 meta_add
512 [version 0.28]
513 A hash of key/value pairs that should be added to the META.yml
515 file during the "distmeta" action. Any existing entries with
516 the same names will be overridden.
517 See the "MODULE METADATA" section for details.
519 meta_merge
521 [version 0.28]
522 A hash of key/value pairs that should be merged into the
524 META.yml file during the "distmeta" action. Any existing
525 entries with the same names will be overridden.
526 The only difference between "meta_add" and "meta_merge" is
528 their behavior on hash-valued and array-valued entries:
529 "meta_add" will completely blow away the existing hash or array
530 value, but "meta_merge" will merge the supplied data into the
531 existing hash or array value.
532 See the "MODULE METADATA" section for details.
534 module_name
536 [version 0.03]
537 The "module_name" is a shortcut for setting default values of
539 "dist_name" and "dist_version_from", reflecting the fact that
540 the majority of CPAN distributions are centered around one
541 "main" module. For instance, if you set "module_name" to
542 "Foo::Bar", then "dist_name" will default to "Foo-Bar" and
543 "dist_version_from" will default to "lib/Foo/Bar.pm".
544 "dist_version_from" will in turn be used to set "dist_version".
545 Setting "module_name" won't override a "dist_*" parameter you
547 specify explicitly.
548 needs_compiler
550 [version 0.36]
551 The "needs_compiler" parameter indicates whether a compiler is
553 required to build the distsribution. The default is false,
554 unless XS files are found or the "c_source" parameter is set,
555 in which case it is true. If true, ExtUtils::CBuilder is
556 automatically added to "build_requires" if needed.
557 For a distribution where a compiler is optional, e.g. a dual
559 XS/pure-Perl distribution, "needs_compiler" should explicitly
560 be set to a false value.
561 PL_files
563 [version 0.06]
564 An optional parameter specifying a set of ".PL" files in your
566 distribution. These will be run as Perl scripts prior to
567 processing the rest of the files in your distribution with the
568 name of the file they're generating as an argument. They are
569 usually used as templates for creating other files dynamically,
570 so that a file like "lib/Foo/Bar.pm.PL" might create the file
571 "lib/Foo/Bar.pm".
572 The files are specified with the ".PL" files as hash keys, and
574 the file(s) they generate as hash values, like so:
575 my $build = Module::Build->new
577 (
578 module_name => 'Foo::Bar',
579 ...
580 PL_files => { 'lib/Foo/Bar.pm.PL' => 'lib/Foo/Bar.pm' },
581 );
582 Note that the path specifications are always given in Unix-like
584 format, not in the style of the local system.
585 If your ".PL" scripts don't create any files, or if they create
587 files with unexpected names, or even if they create multiple
588 files, you can indicate that so that Module::Build can properly
589 handle these created files:
590 PL_files => {
592 'lib/Foo/Bar.pm.PL' => 'lib/Foo/Bar.pm',
593 'lib/something.PL' => ['/lib/something', '/lib/else'],
594 'lib/funny.PL' => [],
595 }
596 Here's an example of a simple PL file.
598 my $output_file = shift;
600 open my $fh, ">", $output_file or die "Can't open $output_file: $!";
601 print $fh <<'END';
603 #!/usr/bin/perl
604 print "Hello, world!\n";
606 END
607 PL files are not installed by default, so its safe to put them
609 in lib/ and bin/.
610 pm_files
612 [version 0.19]
613 An optional parameter specifying the set of ".pm" files in this
615 distribution, specified as a hash reference whose keys are the
616 files' locations in the distributions, and whose values are
617 their logical locations based on their package name, i.e. where
618 they would be found in a "normal" Module::Build-style
619 distribution. This parameter is mainly intended to support
620 alternative layouts of files.
621 For instance, if you have an old-style "MakeMaker" distribution
623 for a module called "Foo::Bar" and a Bar.pm file at the top
624 level of the distribution, you could specify your layout in
625 your "Build.PL" like this:
626 my $build = Module::Build->new
628 (
629 module_name => 'Foo::Bar',
630 ...
631 pm_files => { 'Bar.pm' => 'lib/Foo/Bar.pm' },
632 );
633 Note that the values should include "lib/", because this is
635 where they would be found in a "normal" Module::Build-style
636 distribution.
637 Note also that the path specifications are always given in
639 Unix-like format, not in the style of the local system.
640 pod_files
642 [version 0.19]
643 Just like "pm_files", but used for specifying the set of ".pod"
645 files in your distribution.
646 recommends
648 [version 0.08]
649 This is just like the "requires" argument, except that modules
651 listed in this section aren't essential, just a good idea.
652 We'll just print a friendly warning if one of these modules
653 aren't found, but we'll continue running.
654 If a module is recommended but not required, all tests should
656 still pass if the module isn't installed. This may mean that
657 some tests may be skipped if recommended dependencies aren't
658 present.
659 Automated tools like CPAN.pm should inform the user when
661 recommended modules aren't installed, and it should offer to
662 install them if it wants to be helpful.
663 See the documentation for "PREREQUISITES" in
665 Module::Build::Authoring for the details of how requirements
666 can be specified.
667 recursive_test_files
669 [version 0.28]
670 Normally, "Module::Build" does not search subdirectories when
672 looking for tests to run. When this options is set it will
673 search recursively in all subdirectories of the standard 't'
674 test directory.
675 requires
677 [version 0.07]
678 An optional "requires" argument specifies any module
680 prerequisites that the current module depends on.
681 One note: currently "Module::Build" doesn't actually require
683 the user to have dependencies installed, it just strongly
684 urges. In the future we may require it. There's also a
685 "recommends" section for things that aren't absolutely
686 required.
687 Automated tools like CPAN.pm should refuse to install a module
689 if one of its dependencies isn't satisfied, unless a "force"
690 command is given by the user. If the tools are helpful, they
691 should also offer to install the dependencies.
692 A synonym for "requires" is "prereq", to help succour people
694 transitioning from "ExtUtils::MakeMaker". The "requires" term
695 is preferred, but the "prereq" term will remain valid in future
696 distributions.
697 See the documentation for "PREREQUISITES" in
699 Module::Build::Authoring for the details of how requirements
700 can be specified.
701 script_files
703 [version 0.18]
704 An optional parameter specifying a set of files that should be
706 installed as executable Perl scripts when the module is
707 installed. May be given as an array reference of the files, as
708 a hash reference whose keys are the files (and whose values
709 will currently be ignored), as a string giving the name of a
710 directory in which to find scripts, or as a string giving the
711 name of a single script file.
712 The default is to install any scripts found in a bin directory
714 at the top level of the distribution, minus any keys of
715 PL_files.
716 For backward compatibility, you may use the parameter "scripts"
718 instead of "script_files". Please consider this usage
719 deprecated, though it will continue to exist for several
720 version releases.
721 share_dir
723 [version 0.36]
724 An optional parameter specifying directories of static data
726 files to be installed as read-only files for use with
727 File::ShareDir. The "share_dir" property supports both
728 distribution-level and module-level share files.
729 The simplest use of "share_dir" is to set it to a directory
731 name or an arrayref of directory names containing files to be
732 installed in the distribution-level share directory.
733 share_dir => 'share'
735 Alternatively, if "share_dir" is a hashref, it may have "dist"
737 or "module" keys providing full flexibility in defining how
738 share directories should be installed.
739 share_dir => {
741 dist => [ 'examples', 'more_examples' ],
742 module => {
743 Foo::Templates => ['share/html', 'share/text'],
744 Foo::Config => 'share/config',
745 }
746 }
747 If "share_dir" is set, then File::ShareDir will automatically
749 be added to the "requires" hash.
750 sign
752 [version 0.16]
753 If a true value is specified for this parameter,
755 Module::Signature will be used (via the 'distsign' action) to
756 create a SIGNATURE file for your distribution during the
757 'distdir' action, and to add the SIGNATURE file to the MANIFEST
758 (therefore, don't add it yourself).
759 The default value is false. In the future, the default may
761 change to true if you have "Module::Signature" installed on
762 your system.
763 test_files
765 [version 0.23]
766 An optional parameter specifying a set of files that should be
768 used as "Test::Harness"-style regression tests to be run during
769 the "test" action. May be given as an array reference of the
770 files, or as a hash reference whose keys are the files (and
771 whose values will currently be ignored). If the argument is
772 given as a single string (not in an array reference), that
773 string will be treated as a "glob()" pattern specifying the
774 files to use.
775 The default is to look for a test.pl script in the top-level
777 directory of the distribution, and any files matching the glob
778 pattern "*.t" in the t/ subdirectory. If the
779 "recursive_test_files" property is true, then the "t/"
780 directory will be scanned recursively for "*.t" files.
781 use_tap_harness
783 [version 0.2808_03]
784 An optional parameter indicating whether or not to use
786 TAP::Harness for testing rather than Test::Harness. Defaults to
787 false. If set to true, you must therefore be sure to add
788 TAP::Harness as a requirement for your module in
789 "build_requires". Implicitly set to a true value if
790 "tap_harness_args" is specified.
791 tap_harness_args
793 [version 0.2808_03]
794 An optional parameter specifying parameters to be passed to
796 TAP::Harness when running tests. Must be given as a hash
797 reference of parameters; see the TAP::Harness documentation for
798 details. Note that specifying this parameter will implicitly
799 set "use_tap_harness" to a true value. You must therefore be
800 sure to add TAP::Harness as a requirement for your module in
801 "build_requires".
802 xs_files
804 [version 0.19]
805 Just like "pm_files", but used for specifying the set of ".xs"
807 files in your distribution.
808 new_from_context(%args)
810 [version 0.28]
811 When called from a directory containing a Build.PL script (in other
813 words, the base directory of a distribution), this method will run
814 the Build.PL and call "resume()" to return the resulting
815 "Module::Build" object to the caller. Any key-value arguments
816 given to "new_from_context()" are essentially like command line
817 arguments given to the Build.PL script, so for example you could
818 pass "verbose => 1" to this method to turn on verbosity.
819 resume()
821 [version 0.03]
822 You'll probably never call this method directly, it's only called
824 from the auto-generated "Build" script (and the "new_from_context"
825 method). The "new()" method is only called once, when the user
826 runs "perl Build.PL". Thereafter, when the user runs "Build test"
827 or another action, the "Module::Build" object is created using the
828 "resume()" method to re-instantiate with the settings given earlier
829 to "new()".
830 subclass()
832 [version 0.06]
833 This creates a new "Module::Build" subclass on the fly, as
835 described in the "SUBCLASSING" in Module::Build::Authoring section.
836 The caller must provide either a "class" or "code" parameter, or
837 both. The "class" parameter indicates the name to use for the new
838 subclass, and defaults to "MyModuleBuilder". The "code" parameter
839 specifies Perl code to use as the body of the subclass.
840 add_property
842 [version 0.31]
843 package 'My::Build';
845 use base 'Module::Build';
846 __PACKAGE__->add_property( 'pedantic' );
847 __PACKAGE__->add_property( answer => 42 );
848 __PACKAGE__->add_property(
849 'epoch',
850 default => sub { time },
851 check => sub {
852 return 1 if /^\d+$/;
853 shift->property_error( "'$_' is not an epoch time" );
854 return 0;
855 },
856 );
857 Adds a property to a Module::Build class. Properties are those
859 attributes of a Module::Build object which can be passed to the
860 constructor and which have accessors to get and set them. All of
861 the core properties, such as "module_name" and "license", are
862 defined using this class method.
863 The first argument to "add_property()" is always the name of the
865 property. The second argument can be either a default value for
866 the property, or a list of key/value pairs. The supported keys are:
867 "default"
869 The default value. May optionally be specified as a code
870 reference, in which case the return value from the execution of
871 the code reference will be used. If you need the default to be
872 a code reference, just use a code reference to return it, e.g.:
873 default => sub { sub { ... } },
875 "check"
877 A code reference that checks that a value specified for the
878 property is valid. During the execution of the code reference,
879 the new value will be included in the $_ variable. If the value
880 is correct, the "check" code reference should return true. If
881 the value is not correct, it sends an error message to
882 "property_error()" and returns false.
883 When this method is called, a new property will be installed in the
885 Module::Build class, and an accessor will be built to allow the
886 property to be get or set on the build object.
887 print $build->pedantic, $/;
889 $build->pedantic(0);
890 If the default value is a hash reference, this generates a special-
892 case accessor method, wherein individual key/value pairs may be set
893 or fetched:
894 print "stuff{foo} is: ", $build->stuff( 'foo' ), $/;
896 $build->stuff( foo => 'bar' );
897 print $build->stuff( 'foo' ), $/; # Outputs "bar"
898 Of course, you can still set the entire hash reference at once, as
900 well:
901 $build->stuff( { foo => 'bar', baz => 'yo' } );
903 In either case, if a "check" has been specified for the property,
905 it will be applied to the entire hash. So the check code reference
906 should look something like:
907 check => sub {
909 return 1 if defined $_ && exists $_->{foo};
910 shift->property_error(qq{Property "stuff" needs "foo"});
911 return 0;
912 },
913 property_error
915 [version 0.31]
916 METHODS
918 add_build_element($type)
919 [version 0.26]
920 Adds a new type of entry to the build process. Accepts a single
922 string specifying its type-name. There must also be a method
923 defined to process things of that type, e.g. if you add a build
924 element called 'foo', then you must also define a method called
925 "process_foo_files()".
926 See also "Adding new file types to the build process" in
928 Module::Build::Cookbook.
929 add_to_cleanup(@files)
931 [version 0.03]
932 You may call "$self->add_to_cleanup(@patterns)" to tell
934 "Module::Build" that certain files should be removed when the user
935 performs the "Build clean" action. The arguments to the method are
936 patterns suitable for passing to Perl's "glob()" function,
937 specified in either Unix format or the current machine's native
938 format. It's usually convenient to use Unix format when you hard-
939 code the filenames (e.g. in Build.PL) and the native format when
940 the names are programmatically generated (e.g. in a testing
941 script).
942 I decided to provide a dynamic method of the $build object, rather
944 than just use a static list of files named in the Build.PL, because
945 these static lists can get difficult to manage. I usually prefer
946 to keep the responsibility for registering temporary files close to
947 the code that creates them.
948 args()
950 [version 0.26]
951 my $args_href = $build->args;
953 my %args = $build->args;
954 my $arg_value = $build->args($key);
955 $build->args($key, $value);
956 This method is the preferred interface for retrieving the arguments
958 passed via command line options to Build.PL or Build, minus the
959 Module-Build specific options.
960 When called in in a scalar context with no arguments, this method
962 returns a reference to the hash storing all of the arguments; in an
963 array context, it returns the hash itself. When passed a single
964 argument, it returns the value stored in the args hash for that
965 option key. When called with two arguments, the second argument is
966 assigned to the args hash under the key passed as the first
967 argument.
968 autosplit_file($from, $to)
970 [version 0.28]
971 Invokes the AutoSplit module on the $from file, sending the output
973 to the "lib/auto" directory inside $to. $to is typically the
974 "blib/" directory.
975 base_dir()
977 [version 0.14]
978 Returns a string containing the root-level directory of this build,
980 i.e. where the "Build.PL" script and the "lib" directory can be
981 found. This is usually the same as the current working directory,
982 because the "Build" script will "chdir()" into this directory as
983 soon as it begins execution.
984 build_requires()
986 [version 0.21]
987 Returns a hash reference indicating the "build_requires"
989 prerequisites that were passed to the "new()" method.
990 can_action( $action )
992 Returns a reference to the method that defines $action, or false
993 otherwise. This is handy for actions defined (or maybe not!) in
994 subclasses.
995 [version 0.32_xx]
997 cbuilder()
999 [version 0.2809]
1000 Returns the internal ExtUtils::CBuilder object that can be used for
1002 compiling & linking C code. If no such object is available (e.g.
1003 if the system has no compiler installed) an exception will be
1004 thrown.
1005 check_installed_status($module, $version)
1007 [version 0.11]
1008 This method returns a hash reference indicating whether a version
1010 dependency on a certain module is satisfied. The $module argument
1011 is given as a string like "Data::Dumper" or "perl", and the
1012 $version argument can take any of the forms described in "requires"
1013 above. This allows very fine-grained version checking.
1014 The returned hash reference has the following structure:
1016 {
1018 ok => $whether_the_dependency_is_satisfied,
1019 have => $version_already_installed,
1020 need => $version_requested, # Same as incoming $version argument
1021 message => $informative_error_message,
1022 }
1023 If no version of $module is currently installed, the "have" value
1025 will be the string "<none>". Otherwise the "have" value will
1026 simply be the version of the installed module. Note that this
1027 means that if $module is installed but doesn't define a version
1028 number, the "have" value will be "undef" - this is why we don't use
1029 "undef" for the case when $module isn't installed at all.
1030 This method may be called either as an object method
1032 ("$build->check_installed_status($module, $version)") or as a class
1033 method ("Module::Build->check_installed_status($module,
1034 $version)").
1035 check_installed_version($module, $version)
1037 [version 0.05]
1038 Like check_installed_status(), but simply returns true or false
1040 depending on whether module $module satisfies the dependency
1041 $version.
1042 If the check succeeds, the return value is the actual version of
1044 $module installed on the system. This allows you to do the
1045 following:
1046 my $installed = $build->check_installed_version('DBI', '1.15');
1048 if ($installed) {
1049 print "Congratulations, version $installed of DBI is installed.\n";
1050 } else {
1051 die "Sorry, you must install DBI.\n";
1052 }
1053 If the check fails, we return false and set $@ to an informative
1055 error message.
1056 If $version is any non-true value (notably zero) and any version of
1058 $module is installed, we return true. In this case, if $module
1059 doesn't define a version, or if its version is zero, we return the
1060 special value "0 but true", which is numerically zero, but
1061 logically true.
1062 In general you might prefer to use "check_installed_status" if you
1064 need detailed information, or this method if you just need a yes/no
1065 answer.
1066 compare_versions($v1, $op, $v2)
1068 [version 0.28]
1069 Compares two module versions $v1 and $v2 using the operator $op,
1071 which should be one of Perl's numeric operators like "!=" or ">="
1072 or the like. We do at least a halfway-decent job of handling
1073 versions that aren't strictly numeric, like "0.27_02", but exotic
1074 stuff will likely cause problems.
1075 In the future, the guts of this method might be replaced with a
1077 call out to "version.pm".
1078 config($key)
1080 config($key, $value)
1081 config() [deprecated]
1082 [version 0.22]
1083 With a single argument $key, returns the value associated with that
1085 key in the "Config.pm" hash, including any changes the author or
1086 user has specified.
1087 With $key and $value arguments, sets the value for future callers
1089 of "config($key)".
1090 With no arguments, returns a hash reference containing all such
1092 key-value pairs. This usage is deprecated, though, because it's a
1093 resource hog and violates encapsulation.
1094 config_data($name)
1096 config_data($name => $value)
1097 [version 0.26]
1098 With a single argument, returns the value of the configuration
1100 variable $name. With two arguments, sets the given configuration
1101 variable to the given value. The value may be any Perl scalar
1102 that's serializable with "Data::Dumper". For instance, if you
1103 write a module that can use a MySQL or PostgreSQL back-end, you
1104 might create configuration variables called "mysql_connect" and
1105 "postgres_connect", and set each to an array of connection
1106 parameters for "DBI->connect()".
1107 Configuration values set in this way using the Module::Build object
1109 will be available for querying during the build/test process and
1110 after installation via the generated "...::ConfigData" module, as
1111 "...::ConfigData->config($name)".
1112 The feature() and "config_data()" methods represent Module::Build's
1114 main support for configuration of installed modules. See also
1115 "SAVING CONFIGURATION INFORMATION" in Module::Build::Authoring.
1116 conflicts()
1118 [version 0.21]
1119 Returns a hash reference indicating the "conflicts" prerequisites
1121 that were passed to the "new()" method.
1122 contains_pod($file) [deprecated]
1124 [version 0.20]
1125 [Deprecated] Please see Module::Build::ModuleInfo instead.
1127 Returns true if the given file appears to contain POD
1129 documentation. Currently this checks whether the file has a line
1130 beginning with '=pod', '=head', or '=item', but the exact semantics
1131 may change in the future.
1132 copy_if_modified(%parameters)
1134 [version 0.19]
1135 Takes the file in the "from" parameter and copies it to the file in
1137 the "to" parameter, or the directory in the "to_dir" parameter, if
1138 the file has changed since it was last copied (or if it doesn't
1139 exist in the new location). By default the entire directory
1140 structure of "from" will be copied into "to_dir"; an optional
1141 "flatten" parameter will copy into "to_dir" without doing so.
1142 Returns the path to the destination file, or "undef" if nothing
1144 needed to be copied.
1145 Any directories that need to be created in order to perform the
1147 copying will be automatically created.
1148 The destination file is set to read-only. If the source file has
1150 the executable bit set, then the destination file will be made
1151 executable.
1152 create_build_script()
1154 [version 0.05]
1155 Creates an executable script called "Build" in the current
1157 directory that will be used to execute further user actions. This
1158 script is roughly analogous (in function, not in form) to the
1159 Makefile created by "ExtUtils::MakeMaker". This method also
1160 creates some temporary data in a directory called "_build/". Both
1161 of these will be removed when the "realclean" action is performed.
1162 Among the files created in "_build/" is a _build/prereqs file
1164 containing the set of prerequisites for this distribution, as a
1165 hash of hashes. This file may be "eval()"-ed to obtain the
1166 authoritative set of prerequisites, which might be different from
1167 the contents of META.yml (because Build.PL might have set them
1168 dynamically). But fancy developers take heed: do not put any fancy
1169 custom runtime code in the _build/prereqs file, leave it as a
1170 static declaration containing only strings and numbers. Similarly,
1171 do not alter the structure of the internal
1172 "$self->{properties}{requires}" (etc.) data members, because
1173 that's where this data comes from.
1174 current_action()
1176 [version 0.28]
1177 Returns the name of the currently-running action, such as "build"
1179 or "test". This action is not necessarily the action that was
1180 originally invoked by the user. For example, if the user invoked
1181 the "test" action, current_action() would initially return "test".
1182 However, action "test" depends on action "code", so
1183 current_action() will return "code" while that dependency is being
1184 executed. Once that action has completed, current_action() will
1185 again return "test".
1186 If you need to know the name of the original action invoked by the
1188 user, see "invoked_action()" below.
1189 depends_on(@actions)
1191 [version 0.28]
1192 Invokes the named action or list of actions in sequence. Using
1194 this method is preferred to calling the action explicitly because
1195 it performs some internal record-keeping, and it ensures that the
1196 same action is not invoked multiple times (note: in future versions
1197 of Module::Build it's conceivable that this run-only-once mechanism
1198 will be changed to something more intelligent).
1199 Note that the name of this method is something of a misnomer; it
1201 should really be called something like
1202 "invoke_actions_unless_already_invoked()" or something, but for
1203 better or worse (perhaps better!) we were still thinking in
1204 "make"-like dependency terms when we created this method.
1205 See also dispatch(). The main distinction between the two is that
1207 "depends_on()" is meant to call an action from inside another
1208 action, whereas "dispatch()" is meant to set the very top action in
1209 motion.
1210 dir_contains($first_dir, $second_dir)
1212 [version 0.28]
1213 Returns true if the first directory logically contains the second
1215 directory. This is just a convenience function because
1216 "File::Spec" doesn't really provide an easy way to figure this out
1217 (but "Path::Class" does...).
1218 dispatch($action, %args)
1220 [version 0.03]
1221 Invokes the build action $action. Optionally, a list of options
1223 and their values can be passed in. This is equivalent to invoking
1224 an action at the command line, passing in a list of options.
1225 Custom options that have not been registered must be passed in as a
1227 hash reference in a key named "args":
1228 $build->dispatch('foo', verbose => 1, args => { my_option => 'value' });
1230 This method is intended to be used to programmatically invoke build
1232 actions, e.g. by applications controlling Module::Build-based
1233 builds rather than by subclasses.
1234 See also depends_on(). The main distinction between the two is
1236 that "depends_on()" is meant to call an action from inside another
1237 action, whereas "dispatch()" is meant to set the very top action in
1238 motion.
1239 dist_dir()
1241 [version 0.28]
1242 Returns the name of the directory that will be created during the
1244 "dist" action. The name is derived from the "dist_name" and
1245 "dist_version" properties.
1246 dist_name()
1248 [version 0.21]
1249 Returns the name of the current distribution, as passed to the
1251 "new()" method in a "dist_name" or modified "module_name"
1252 parameter.
1253 dist_version()
1255 [version 0.21]
1256 Returns the version of the current distribution, as determined by
1258 the "new()" method from a "dist_version", "dist_version_from", or
1259 "module_name" parameter.
1260 do_system($cmd, @args)
1262 [version 0.21]
1263 This is a fairly simple wrapper around Perl's "system()" built-in
1265 command. Given a command and an array of optional arguments, this
1266 method will print the command to "STDOUT", and then execute it
1267 using Perl's "system()". It returns true or false to indicate
1268 success or failure (the opposite of how "system()" works, but more
1269 intuitive).
1270 Note that if you supply a single argument to "do_system()", it
1272 will/may be processed by the system's shell, and any special
1273 characters will do their special things. If you supply multiple
1274 arguments, no shell will get involved and the command will be
1275 executed directly.
1276 feature($name)
1278 feature($name => $value)
1279 [version 0.26]
1280 With a single argument, returns true if the given feature is set.
1282 With two arguments, sets the given feature to the given boolean
1283 value. In this context, a "feature" is any optional functionality
1284 of an installed module. For instance, if you write a module that
1285 could optionally support a MySQL or PostgreSQL backend, you might
1286 create features called "mysql_support" and "postgres_support", and
1287 set them to true/false depending on whether the user has the proper
1288 databases installed and configured.
1289 Features set in this way using the Module::Build object will be
1291 available for querying during the build/test process and after
1292 installation via the generated "...::ConfigData" module, as
1293 "...::ConfigData->feature($name)".
1294 The "feature()" and "config_data()" methods represent
1296 Module::Build's main support for configuration of installed
1297 modules. See also "SAVING CONFIGURATION INFORMATION" in
1298 Module::Build::Authoring.
1299 fix_shebang_line(@files)
1301 [version 0.??]
1302 Modify any "shebang" line in the specified files to use the path to
1304 the perl executable being used for the current build. Files are
1305 modified in-place. The existing shebang line must have a command
1306 that contains ""perl""; arguments to the command do not count. In
1307 particular, this means that the use of "#!/usr/bin/env perl" will
1308 not be changed.
1309 For an explanation of shebang lines, see
1311 <http://en.wikipedia.org/wiki/Shebang_%28Unix%29>.
1312 have_c_compiler()
1314 [version 0.21]
1315 Returns true if the current system seems to have a working C
1317 compiler. We currently determine this by attempting to compile a
1318 simple C source file and reporting whether the attempt was
1319 successful.
1320 install_base_relpaths()
1322 install_base_relpaths($type)
1323 install_base_relpaths($type => $path)
1324 [version 0.28]
1325 Set or retrieve the relative paths that are appended to
1327 "install_base" for any installable element. This is useful if you
1328 want to set the relative install path for custom build elements.
1329 With no argument, it returns a reference to a hash containing all
1331 elements and their respective values. This hash should not be
1332 modified directly; use the multiple argument below form to change
1333 values.
1334 The single argument form returns the value associated with the
1336 element $type.
1337 The multiple argument form allows you to set the paths for element
1339 types. $value must be a relative path using Unix-like paths. (A
1340 series of directories separated by slashes, e.g. "foo/bar".) The
1341 return value is a localized path based on $value.
1342 Assigning the value "undef" to an element causes it to be removed.
1344 install_destination($type)
1346 [version 0.28]
1347 Returns the directory in which items of type $type (e.g. "lib",
1349 "arch", "bin", or anything else returned by the "install_types()"
1350 method) will be installed during the "install" action. Any
1351 settings for "install_path", "install_base", and "prefix" are taken
1352 into account when determining the return value.
1353 install_path()
1355 install_path($type)
1356 install_path($type => $path)
1357 [version 0.28]
1358 Set or retrieve paths for specific installable elements. This is
1360 useful when you want to examine any explicit install paths
1361 specified by the user on the command line, or if you want to set
1362 the install path for a specific installable element based on
1363 another attribute like "install_base()".
1364 With no argument, it returns a reference to a hash containing all
1366 elements and their respective values. This hash should not be
1367 modified directly; use the multiple argument below form to change
1368 values.
1369 The single argument form returns the value associated with the
1371 element $type.
1372 The multiple argument form allows you to set the paths for element
1374 types. The supplied $path should be an absolute path to install
1375 elements of $type. The return value is $path.
1376 Assigning the value "undef" to an element causes it to be removed.
1378 install_types()
1380 [version 0.28]
1381 Returns a list of installable types that this build knows about.
1383 These types each correspond to the name of a directory in blib/,
1384 and the list usually includes items such as "lib", "arch", "bin",
1385 "script", "libdoc", "bindoc", and if HTML documentation is to be
1386 built, "libhtml" and "binhtml". Other user-defined types may also
1387 exist.
1388 invoked_action()
1390 [version 0.28]
1391 This is the name of the original action invoked by the user. This
1393 value is set when the user invokes Build.PL, the Build script, or
1394 programmatically through the dispatch() method. It does not change
1395 as sub-actions are executed as dependencies are evaluated.
1396 To get the name of the currently executing dependency, see
1398 "current_action()" above.
1399 notes()
1401 notes($key)
1402 notes($key => $value)
1403 [version 0.20]
1404 The "notes()" value allows you to store your own persistent
1406 information about the build, and to share that information among
1407 different entities involved in the build. See the example in the
1408 "current()" method.
1409 The "notes()" method is essentially a glorified hash access. With
1411 no arguments, "notes()" returns the entire hash of notes. With one
1412 argument, "notes($key)" returns the value associated with the given
1413 key. With two arguments, "notes($key, $value)" sets the value
1414 associated with the given key to $value and returns the new value.
1415 The lifetime of the "notes" data is for "a build" - that is, the
1417 "notes" hash is created when "perl Build.PL" is run (or when the
1418 "new()" method is run, if the Module::Build Perl API is being used
1419 instead of called from a shell), and lasts until "perl Build.PL" is
1420 run again or the "clean" action is run.
1421 orig_dir()
1423 [version 0.28]
1424 Returns a string containing the working directory that was in
1426 effect before the Build script chdir()-ed into the "base_dir".
1427 This might be useful for writing wrapper tools that might need to
1428 chdir() back out.
1429 os_type()
1431 [version 0.04]
1432 If you're subclassing Module::Build and some code needs to alter
1434 its behavior based on the current platform, you may only need to
1435 know whether you're running on Windows, Unix, MacOS, VMS, etc., and
1436 not the fine-grained value of Perl's $^O variable. The "os_type()"
1437 method will return a string like "Windows", "Unix", "MacOS", "VMS",
1438 or whatever is appropriate. If you're running on an unknown
1439 platform, it will return "undef" - there shouldn't be many unknown
1440 platforms though.
1441 is_vmsish()
1443 is_windowsish()
1444 is_unixish()
1445 Convenience functions that return a boolean value indicating
1446 whether this platform behaves respectively like VMS, Windows, or
1447 Unix. For arbitrary reasons other platforms don't get their own
1448 such functions, at least not yet.
1449 prefix_relpaths()
1451 prefix_relpaths($installdirs)
1452 prefix_relpaths($installdirs, $type)
1453 prefix_relpaths($installdirs, $type => $path)
1454 [version 0.28]
1455 Set or retrieve the relative paths that are appended to "prefix"
1457 for any installable element. This is useful if you want to set the
1458 relative install path for custom build elements.
1459 With no argument, it returns a reference to a hash containing all
1461 elements and their respective values as defined by the current
1462 "installdirs" setting.
1463 With a single argument, it returns a reference to a hash containing
1465 all elements and their respective values as defined by
1466 $installdirs.
1467 The hash returned by the above calls should not be modified
1469 directly; use the three-argument below form to change values.
1470 The two argument form returns the value associated with the element
1472 $type.
1473 The multiple argument form allows you to set the paths for element
1475 types. $value must be a relative path using Unix-like paths. (A
1476 series of directories separated by slashes, e.g. "foo/bar".) The
1477 return value is a localized path based on $value.
1478 Assigning the value "undef" to an element causes it to be removed.
1480 get_metadata()
1482 [version 0.36]
1483 This method returns a hash reference of metadata that can be used
1485 to create a YAML datastream. It is provided for authors to override
1486 or customize the fields of META.yml. E.g.
1487 package My::Builder;
1489 use base 'Module::Build';
1490 sub get_metadata {
1492 my $self, @args = @_;
1493 my $data = $self->SUPER::get_metadata(@args);
1494 $data->{custom_field} = 'foo';
1495 return $data;
1496 }
1497 The only valid argument is "fatal", which indicates whether missing
1499 required metadata fields should be a fatal error or not. For META
1500 creation, it generally should, but for MYMETA creation for end-
1501 users, it should not be fatal.
1502 This method is a wrapper around the old prepare_metadata API now
1504 that we no longer use YAML::Node to hold metadata.
1505 prepare_metadata() [deprecated]
1507 [version 0.36]
1508 [Deprecated] As of 0.36, authors should use "get_metadata" instead.
1510 This method is preserved for backwards compatibility only.
1511 It takes three positional arguments: a hashref (to which metadata
1513 will be added), an optional arrayref (to which metadata keys will
1514 be added in order if the arrayref exists), and a hashref of
1515 arguments (as provided to get_metadata). The latter argument is
1516 new as of 0.36. Earlier versions are always fatal on errors.
1517 Prior to version 0.36, this method took a YAML::Node as an argument
1519 to hold assembled metadata.
1520 prereq_failures()
1522 [version 0.11]
1523 Returns a data structure containing information about any failed
1525 prerequisites (of any of the types described above), or "undef" if
1526 all prerequisites are met.
1527 The data structure returned is a hash reference. The top level
1529 keys are the type of prerequisite failed, one of "requires",
1530 "build_requires", "conflicts", or "recommends". The associated
1531 values are hash references whose keys are the names of required (or
1532 conflicting) modules. The associated values of those are hash
1533 references indicating some information about the failure. For
1534 example:
1535 {
1537 have => '0.42',
1538 need => '0.59',
1539 message => 'Version 0.42 is installed, but we need version 0.59',
1540 }
1541 or
1543 {
1545 have => '<none>',
1546 need => '0.59',
1547 message => 'Prerequisite Foo isn't installed',
1548 }
1549 This hash has the same structure as the hash returned by the
1551 "check_installed_status()" method, except that in the case of
1552 "conflicts" dependencies we change the "need" key to "conflicts"
1553 and construct a proper message.
1554 Examples:
1556 # Check a required dependency on Foo::Bar
1558 if ( $build->prereq_failures->{requires}{Foo::Bar} ) { ...
1559 # Check whether there were any failures
1561 if ( $build->prereq_failures ) { ...
1562 # Show messages for all failures
1564 my $failures = $build->prereq_failures;
1565 while (my ($type, $list) = each %$failures) {
1566 while (my ($name, $hash) = each %$list) {
1567 print "Failure for $name: $hash->{message}\n";
1568 }
1569 }
1570 prereq_data()
1572 [version 0.32]
1573 Returns a reference to a hash describing all prerequisites. The
1575 keys of the hash will the various prerequisite types ('requires',
1576 'build_requires', 'configure_requires', 'recommends', or
1577 'conflicts') and the values will references to hashes of module
1578 names and version numbers. Only prerequisites types that are
1579 defined will be included. The "prereq_data" action is just a thin
1580 wrapper around the "prereq_data()" method and dumps the hash as a
1581 string that can be loaded using "eval()".
1582 prereq_report()
1584 [version 0.28]
1585 Returns a human-readable (table-form) string showing all
1587 prerequisites, the versions required, and the versions actually
1588 installed. This can be useful for reviewing the configuration of
1589 your system prior to a build, or when compiling data to send for a
1590 bug report. The "prereq_report" action is just a thin wrapper
1591 around the "prereq_report()" method.
1592 prompt($message, $default)
1594 [version 0.12]
1595 Asks the user a question and returns their response as a string.
1597 The first argument specifies the message to display to the user
1598 (for example, "Where do you keep your money?"). The second
1599 argument, which is optional, specifies a default answer (for
1600 example, "wallet"). The user will be asked the question once.
1601 If "prompt()" detects that it is not running interactively and
1603 there is nothing on STDIN or if the PERL_MM_USE_DEFAULT environment
1604 variable is set to true, the $default will be used without
1605 prompting.
1606 To prevent automated processes from blocking, the user must either
1608 set PERL_MM_USE_DEFAULT or attach something to STDIN (this can be a
1609 pipe/file containing a scripted set of answers or /dev/null.)
1610 If no $default is provided an empty string will be used instead.
1612 In non-interactive mode, the absence of $default is an error
1613 (though explicitly passing "undef()" as the default is valid as of
1614 0.27.)
1615 This method may be called as a class or object method.
1617 recommends()
1619 [version 0.21]
1620 Returns a hash reference indicating the "recommends" prerequisites
1622 that were passed to the "new()" method.
1623 requires()
1625 [version 0.21]
1626 Returns a hash reference indicating the "requires" prerequisites
1628 that were passed to the "new()" method.
1629 rscan_dir($dir, $pattern)
1631 [version 0.28]
1632 Uses "File::Find" to traverse the directory $dir, returning a
1634 reference to an array of entries matching $pattern. $pattern may
1635 either be a regular expression (using "qr//" or just a plain
1636 string), or a reference to a subroutine that will return true for
1637 wanted entries. If $pattern is not given, all entries will be
1638 returned.
1639 Examples:
1641 # All the *.pm files in lib/
1643 $m->rscan_dir('lib', qr/\.pm$/)
1644 # All the files in blib/ that aren't *.html files
1646 $m->rscan_dir('blib', sub {-f $_ and not /\.html$/});
1647 # All the files in t/
1649 $m->rscan_dir('t');
1650 runtime_params()
1652 runtime_params($key)
1653 [version 0.28]
1654 The "runtime_params()" method stores the values passed on the
1656 command line for valid properties (that is, any command line
1657 options for which "valid_property()" returns a true value). The
1658 value on the command line may override the default value for a
1659 property, as well as any value specified in a call to "new()".
1660 This allows you to programmatically tell if "perl Build.PL" or any
1661 execution of "./Build" had command line options specified that
1662 override valid properties.
1663 The "runtime_params()" method is essentially a glorified read-only
1665 hash. With no arguments, "runtime_params()" returns the entire
1666 hash of properties specified on the command line. With one
1667 argument, "runtime_params($key)" returns the value associated with
1668 the given key.
1669 The lifetime of the "runtime_params" data is for "a build" - that
1671 is, the "runtime_params" hash is created when "perl Build.PL" is
1672 run (or when the "new()" method is called, if the Module::Build
1673 Perl API is being used instead of called from a shell), and lasts
1674 until "perl Build.PL" is run again or the "clean" action is run.
1675 script_files()
1677 [version 0.18]
1678 Returns a hash reference whose keys are the perl script files to be
1680 installed, if any. This corresponds to the "script_files"
1681 parameter to the "new()" method. With an optional argument, this
1682 parameter may be set dynamically.
1683 For backward compatibility, the "scripts()" method does exactly the
1685 same thing as "script_files()". "scripts()" is deprecated, but it
1686 will stay around for several versions to give people time to
1687 transition.
1688 up_to_date($source_file, $derived_file)
1690 up_to_date(\@source_files, \@derived_files)
1691 [version 0.20]
1692 This method can be used to compare a set of source files to a set
1694 of derived files. If any of the source files are newer than any of
1695 the derived files, it returns false. Additionally, if any of the
1696 derived files do not exist, it returns false. Otherwise it returns
1697 true.
1698 The arguments may be either a scalar or an array reference of file
1700 names.
1701 y_n($message, $default)
1703 [version 0.12]
1704 Asks the user a yes/no question using "prompt()" and returns true
1706 or false accordingly. The user will be asked the question
1707 repeatedly until they give an answer that looks like "yes" or "no".
1708 The first argument specifies the message to display to the user
1710 (for example, "Shall I invest your money for you?"), and the second
1711 argument specifies the default answer (for example, "y").
1712 Note that the default is specified as a string like "y" or "n", and
1714 the return value is a Perl boolean value like 1 or 0. I thought
1715 about this for a while and this seemed like the most useful way to
1716 do it.
1717 This method may be called as a class or object method.
1719 Autogenerated Accessors
1721 In addition to the aforementioned methods, there are also some get/set
1722 accessor methods for the following properties:
1723 <autogenerated_accessors>
1725
1727 If you would like to add other useful metadata, "Module::Build"
1728 supports this with the "meta_add" and "meta_merge" arguments to "new".
1729 The authoritative list of supported metadata can be found at
1730 http://module-build.sourceforge.net/META-spec-current.html
1731 <http://module-build.sourceforge.net/META-spec-current.html>, but for
1732 convenience - here are a few of the more useful ones:
1733 keywords
1735 For describing the distribution using keyword (or "tags") in order
1736 to make CPAN.org indexing and search more efficient and useful.
1737 See
1739 http://module-build.sourceforge.net/META-spec-current.html#keywords
1740 <http://module-build.sourceforge.net/META-spec-
1741 current.html#keywords>.
1742 resources
1744 A list of additional resources available for users of the
1745 distribution. This can include links to a homepage on the web, a
1746 bug tracker, the repository location, a even subscription page for
1747 the distribution mailing list.
1748 See
1750 http://module-build.sourceforge.net/META-spec-current.html#resources
1751 <http://module-build.sourceforge.net/META-spec-
1752 current.html#resources>.
1753
1755 Ken Williams <kwilliams@cpan.org>
1756
1758 Copyright (c) 2001-2006 Ken Williams. All rights reserved.
1759 This library is free software; you can redistribute it and/or modify it
1761 under the same terms as Perl itself.
1762
1764 perl(1), Module::Build(3), Module::Build::Authoring(3),
1765 Module::Build::Cookbook(3), ExtUtils::MakeMaker(3), YAML::Tiny(3)
1766 META.yml Specification:
1768 http://module-build.sourceforge.net/META-spec-current.html
1769 <http://module-build.sourceforge.net/META-spec-current.html>
1770perl v5.12.4 2011-06-07 Module::Build::API(3pm)