1Module::Build::API(3) User Contributed Perl DocumentationModule::Build::API(3)
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()
18 [version 0.20]
19 This method returns a reasonable facsimile of the currently-execut‐
21 ing "Module::Build" object representing the current build. You can
22 use this object to query its "notes()" method, inquire about
23 installed modules, and so on. This is a great way to share infor‐
24 mation between different parts of your build process. For
25 instance, you can ask the user a question during "perl Build.PL",
26 then use their answer during a regression test:
27 # In Build.PL:
29 my $color = $build->prompt("What is your favorite color?");
30 $build->notes(color => $color);
31 # In t/colortest.t:
33 use Module::Build;
34 my $build = Module::Build->current;
35 my $color = $build->notes('color');
36 ...
37 The way the "current()" method is currently implemented, there may
39 be slight differences between the $build object in Build.PL and the
40 one in "t/colortest.t". It is our goal to minimize these differ‐
41 ences in future releases of Module::Build, so please report any
42 anomalies you find.
43 One important caveat: in its current implementation, "current()"
45 will NOT work correctly if you have changed out of the directory
46 that "Module::Build" was invoked from.
47 new()
49 [version 0.03]
50 Creates a new Module::Build object. Arguments to the new() method
52 are listed below. Most arguments are optional, but you must pro‐
53 vide either the "module_name" argument, or "dist_name" and one of
54 "dist_version" or "dist_version_from". In other words, you must
55 provide enough information to determine both a distribution name
56 and version.
57 add_to_cleanup
59 [version 0.19]
60 An array reference of files to be cleaned up when the "clean"
62 action is performed. See also the add_to_cleanup() method.
63 auto_features
65 [version 0.26]
66 This parameter supports the setting of features (see fea‐
68 ture($name)) automatically based on a set of prerequisites.
69 For instance, for a module that could optionally use either
70 MySQL or PostgreSQL databases, you might use "auto_features"
71 like this:
72 my $build = Module::Build->new
74 (
75 ...other stuff here...
76 auto_features => {
77 pg_support => {
78 description => "Interface with Postgres databases",
79 requires => { 'DBD::Pg' => 23.3,
80 'DateTime::Format::Pg' => 0 },
81 },
82 mysql_support => {
83 description => "Interface with MySQL databases",
84 requires => { 'DBD::mysql' => 17.9,
85 'DateTime::Format::MySQL' => 0 },
86 },
87 }
88 );
89 For each feature named, the required prerequisites will be
91 checked, and if there are no failures, the feature will be
92 enabled (set to 1). Otherwise the failures will be displayed
93 to the user and the feature will be disabled (set to 0).
94 See the documentation for requires for the details of how
96 requirements can be specified.
97 autosplit
99 [version 0.04]
100 An optional "autosplit" argument specifies a file which should
102 be run through the "Autosplit::autosplit()" function. If mul‐
103 tiple files should be split, the argument may be given as an
104 array of the files to split.
105 In general I don't consider autosplitting a great idea, because
107 it's not always clear that autosplitting achieves its intended
108 performance benefits. It may even harm performance in environ‐
109 ments like mod_perl, where as much as possible of a module's
110 code should be loaded during startup.
111 build_class
113 [version 0.28]
114 The Module::Build class or subclass to use in the build script.
116 Defaults to "Module::Build" or the class name passed to or cre‐
117 ated by a call to "subclass()". This property is useful if
118 you're writing a custom Module::Build subclass and have a boot‐
119 strapping problem--that is, your subclass requires modules that
120 may not be installed when "perl Build.PL" is executed, but
121 you've listed in "build_requires" so that they should be avail‐
122 able when "./Build" is executed.
123 build_requires
125 [version 0.07]
126 Modules listed in this section are necessary to build and
128 install the given module, but are not necessary for regular
129 usage of it. This is actually an important distinction - it
130 allows for tighter control over the body of installed modules,
131 and facilitates correct dependency checking on binary/packaged
132 distributions of the module.
133 See the documentation for "PREREQUISITES" in Mod‐
135 ule::Build::Authoring for the details of how requirements can
136 be specified.
137 create_packlist
139 [version 0.28]
140 If true, this parameter tells Module::Build to create a .pack‐
142 list file during the "install" action, just like ExtU‐
143 tils::MakeMaker does. The file is created in a subdirectory of
144 the "arch" installation location. It is used by some other
145 tools (CPAN, CPANPLUS, etc.) for determining what files are
146 part of an install.
147 The default value is true. This parameter was introduced in
149 Module::Build version 0.2609; previously no packlists were ever
150 created by Module::Build.
151 c_source
153 [version 0.04]
154 An optional "c_source" argument specifies a directory which
156 contains C source files that the rest of the build may depend
157 on. Any ".c" files in the directory will be compiled to object
158 files. The directory will be added to the search path during
159 the compilation and linking phases of any C or XS files.
160 conflicts
162 [version 0.07]
163 Modules listed in this section conflict in some serious way
165 with the given module. "Module::Build" (or some higher-level
166 tool) will refuse to install the given module if the given mod‐
167 ule/version is also installed.
168 See the documentation for "PREREQUISITES" in Mod‐
170 ule::Build::Authoring for the details of how requirements can
171 be specified.
172 create_makefile_pl
174 [version 0.19]
175 This parameter lets you use Module::Build::Compat during the
177 "distdir" (or "dist") action to automatically create a Make‐
178 file.PL for compatibility with ExtUtils::MakeMaker. The param‐
179 eter's value should be one of the styles named in the Mod‐
180 ule::Build::Compat documentation.
181 create_readme
183 [version 0.22]
184 This parameter tells Module::Build to automatically create a
186 README file at the top level of your distribution. Currently
187 it will simply use "Pod::Text" (or "Pod::Readme" if it's
188 installed) on the file indicated by "dist_version_from" and put
189 the result in the README file. This is by no means the only
190 recommended style for writing a README, but it seems to be one
191 common one used on the CPAN.
192 If you generate a README in this way, it's probably a good idea
194 to create a separate INSTALL file if that information isn't in
195 the generated README.
196 dist_abstract
198 [version 0.20]
199 This should be a short description of the distribution. This
201 is used when generating metadata for META.yml and PPD files.
202 If it is not given then "Module::Build" looks in the POD of the
203 module from which it gets the distribution's version. It looks
204 for the first line matching "$package\s-\s(.+)", and uses the
205 captured text as the abstract.
206 dist_author
208 [version 0.20]
209 This should be something like "John Doe <jdoe@example.com>", or
211 if there are multiple authors, an anonymous array of strings
212 may be specified. This is used when generating metadata for
213 META.yml and PPD files. If this is not specified, then "Mod‐
214 ule::Build" looks at the module from which it gets the distri‐
215 bution's version. If it finds a POD section marked "=head1
216 AUTHOR", then it uses the contents of this section.
217 dist_name
219 [version 0.11]
220 Specifies the name for this distribution. Most authors won't
222 need to set this directly, they can use "module_name" to set
223 "dist_name" to a reasonable default. However, some agglomera‐
224 tive distributions like "libwww-perl" or "bioperl" have names
225 that don't correspond directly to a module name, so "dist_name"
226 can be set independently.
227 dist_version
229 [version 0.11]
230 Specifies a version number for the distribution. See "mod‐
232 ule_name" or "dist_version_from" for ways to have this set
233 automatically from a $VERSION variable in a module. One way or
234 another, a version number needs to be set.
235 dist_version_from
237 [version 0.11]
238 Specifies a file to look for the distribution version in. Most
240 authors won't need to set this directly, they can use "mod‐
241 ule_name" to set it to a reasonable default.
242 The version is extracted from the specified file according to
244 the same rules as "ExtUtils::MakeMaker" and "CPAN.pm". It
245 involves finding the first line that matches the regular
246 expression
247 /([\$*])(([\w\:\']*)\bVERSION)\b.*\=/
249 eval()-ing that line, then checking the value of the $VERSION
251 variable. Quite ugly, really, but all the modules on CPAN
252 depend on this process, so there's no real opportunity to
253 change to something better.
254 dynamic_config
256 [version 0.07]
257 A boolean flag indicating whether the Build.PL file must be
259 executed, or whether this module can be built, tested and
260 installed solely from consulting its metadata file. The main
261 reason to set this to a true value is that your module performs
262 some dynamic configuration as part of its build/install
263 process. If the flag is omitted, the META.yml spec says that
264 installation tools should treat it as 1 (true), because this is
265 a safer way to behave.
266 Currently "Module::Build" doesn't actually do anything with
268 this flag - it's up to higher-level tools like "CPAN.pm" to do
269 something useful with it. It can potentially bring lots of
270 security, packaging, and convenience improvements.
271 extra_compiler_flags
273 extra_linker_flags
274 [version 0.19]
275 These parameters can contain array references (or strings, in
277 which case they will be split into arrays) to pass through to
278 the compiler and linker phases when compiling/linking C code.
279 For example, to tell the compiler that your code is C++, you
280 might do:
281 my $build = Module::Build->new
283 (
284 module_name => 'Foo::Bar',
285 extra_compiler_flags => ['-x', 'c++'],
286 );
287 To link your XS code against glib you might write something
289 like:
290 my $build = Module::Build->new
292 (
293 module_name => 'Foo::Bar',
294 dynamic_config => 1,
295 extra_compiler_flags => scalar `glib-config --cflags`,
296 extra_linker_flags => scalar `glib-config --libs`,
297 );
298 get_options
300 [version 0.26]
301 You can pass arbitrary command line options to Build.PL or
303 Build, and they will be stored in the Module::Build object and
304 can be accessed via the "args()" method. However, sometimes
305 you want more flexibility out of your argument processing than
306 this allows. In such cases, use the "get_options" parameter to
307 pass in a hash reference of argument specifications, and the
308 list of arguments to Build.PL or Build will be processed
309 according to those specifications before they're passed on to
310 "Module::Build"'s own argument processing.
311 The supported option specification hash keys are:
313 type
315 The type of option. The types are those supported by
316 Getopt::Long; consult its documentation for a complete
317 list. Typical types are "=s" for strings, "+" for additive
318 options, and "!" for negatable options. If the type is not
319 specified, it will be considered a boolean, i.e. no argu‐
320 ment is taken and a value of 1 will be assigned when the
321 option is encountered.
322 store
324 A reference to a scalar in which to store the value passed
325 to the option. If not specified, the value will be stored
326 under the option name in the hash returned by the "args()"
327 method.
328 default
330 A default value for the option. If no default value is
331 specified and no option is passed, then the option key will
332 not exist in the hash returned by "args()".
333 You can combine references to your own variables or subroutines
335 with unreferenced specifications, for which the result will
336 also be stored in the hash returned by "args()". For example:
337 my $loud = 0;
339 my $build = Module::Build->new
340 (
341 module_name => 'Foo::Bar',
342 get_options => {
343 loud => { store => \$loud },
344 dbd => { type => '=s' },
345 quantity => { type => '+' },
346 }
347 );
348 print STDERR "HEY, ARE YOU LISTENING??\n" if $loud;
350 print "We'll use the ", $build->args('dbd'), " DBI driver\n";
351 print "Are you sure you want that many?\n"
352 if $build->args('quantity') > 2;
353 The arguments for such a specification can be called like so:
355 perl Build.PL --loud --dbd=DBD::pg --quantity --quantity --quantity
357 WARNING: Any option specifications that conflict with Mod‐
359 ule::Build's own options (defined by its properties) will throw
360 an exception.
361 Consult the Getopt::Long documentation for details on its
363 usage.
364 include_dirs
366 [version 0.24]
367 Specifies any additional directories in which to search for C
369 header files. May be given as a string indicating a single
370 directory, or as a list reference indicating multiple directo‐
371 ries.
372 install_path
374 [version 0.19]
375 You can set paths for individual installable elements by using
377 the "install_path" parameter:
378 my $build = Module::Build->new
380 (
381 ...other stuff here...
382 install_path => {
383 lib => '/foo/lib',
384 arch => '/foo/lib/arch',
385 }
386 );
387 installdirs
389 [version 0.19]
390 Determines where files are installed within the normal perl
392 hierarchy as determined by Config.pm. Valid values are:
393 "core", "site", "vendor". The default is "site". See "INSTALL
394 PATHS" in Module::Build
395 license
397 [version 0.07]
398 Specifies the licensing terms of your distribution. Valid
400 options include:
401 apache
403 The distribution is licensed under the Apache Software
404 License (http://opensource.org/licenses/apachepl.php).
405 artistic
407 The distribution is licensed under the Artistic License, as
408 specified by the Artistic file in the standard perl distri‐
409 bution.
410 bsd The distribution is licensed under the BSD License
412 (http://www.opensource.org/licenses/bsd-license.php).
413 gpl The distribution is licensed under the terms of the Gnu
415 General Public License (http://www.open‐
416 source.org/licenses/gpl-license.php).
417 lgpl
419 The distribution is licensed under the terms of the Gnu
420 Lesser General Public License (http://www.open‐
421 source.org/licenses/lgpl-license.php).
422 mit The distribution is licensed under the MIT License
424 (http://opensource.org/licenses/mit-license.php).
425 mozilla
427 The distribution is licensed under the Mozilla Public
428 License. (http://opensource.org/licenses/mozilla1.0.php or
429 http://opensource.org/licenses/mozilla1.1.php)
430 open_source
432 The distribution is licensed under some other Open Source
433 Initiative-approved license listed at http://www.open‐
434 source.org/licenses/ .
435 perl
437 The distribution may be copied and redistributed under the
438 same terms as perl itself (this is by far the most common
439 licensing option for modules on CPAN). This is a dual
440 license, in which the user may choose between either the
441 GPL or the Artistic license.
442 restrictive
444 The distribution may not be redistributed without special
445 permission from the author and/or copyright holder.
446 unrestricted
448 The distribution is licensed under a license that is not
449 approved by www.opensource.org but that allows distribution
450 without restrictions.
451 Note that you must still include the terms of your license in
453 your documentation - this field only lets automated tools fig‐
454 ure out your licensing restrictions. Humans still need some‐
455 thing to read. If you choose to provide this field, you should
456 make sure that you keep it in sync with your written documenta‐
457 tion if you ever change your licensing terms.
458 It is a fatal error to use a license other than the ones men‐
460 tioned above. This is not because I wish to impose licensing
461 terms on you - please let me know if you would like another
462 license option to be added to the list. You may also use a
463 license type of "unknown" if you don't wish to specify your
464 terms (but this is usually not a good idea for you to do!).
465 I just started out with a small set of licenses to keep things
467 simple, figuring I'd let people with actual working knowledge
468 in this area tell me what to do. So if that's you, drop me a
469 line.
470 meta_add
472 [version 0.28]
473 A hash of key/value pairs that should be added to the META.yml
475 file during the "distmeta" action. Any existing entries with
476 the same names will be overridden.
477 meta_merge
479 [version 0.28]
480 A hash of key/value pairs that should be merged into the
482 META.yml file during the "distmeta" action. Any existing
483 entries with the same names will be overridden.
484 The only difference between "meta_add" and "meta_merge" is
486 their behavior on hash-valued and array-valued entries:
487 "meta_add" will completely blow away the existing hash or array
488 value, but "meta_merge" will merge the supplied data into the
489 existing hash or array value.
490 module_name
492 [version 0.03]
493 The "module_name" is a shortcut for setting default values of
495 "dist_name" and "dist_version_from", reflecting the fact that
496 the majority of CPAN distributions are centered around one
497 "main" module. For instance, if you set "module_name" to
498 "Foo::Bar", then "dist_name" will default to "Foo-Bar" and
499 "dist_version_from" will default to "lib/Foo/Bar.pm".
500 "dist_version_from" will in turn be used to set "dist_version".
501 Setting "module_name" won't override a "dist_*" parameter you
503 specify explicitly.
504 PL_files
506 [version 0.06]
507 An optional parameter specifying a set of ".PL" files in your
509 distribution. These will be run as Perl scripts prior to pro‐
510 cessing the rest of the files in your distribution. They are
511 usually used as templates for creating other files dynamically,
512 so that a file like "lib/Foo/Bar.pm.PL" might create the file
513 "lib/Foo/Bar.pm".
514 The files are specified with the ".PL" files as hash keys, and
516 the file(s) they generate as hash values, like so:
517 my $build = Module::Build->new
519 (
520 module_name => 'Foo::Bar',
521 ...
522 PL_files => { 'lib/Foo/Bar.pm.PL' => 'lib/Foo/Bar.pm' },
523 );
524 Note that the path specifications are always given in Unix-like
526 format, not in the style of the local system.
527 If your ".PL" scripts don't create any files, or if they create
529 files with unexpected names, or even if they create multiple
530 files, you can indicate that so that Module::Build can properly
531 handle these created files:
532 PL_files => {
534 'lib/Foo/Bar.pm.PL' => 'lib/Foo/Bar.pm',
535 'lib/something.PL' => ['/lib/something', '/lib/else'],
536 'lib/funny.PL' => [],
537 }
538 pm_files
540 [version 0.19]
541 An optional parameter specifying the set of ".pm" files in this
543 distribution, specified as a hash reference whose keys are the
544 files' locations in the distributions, and whose values are
545 their logical locations based on their package name, i.e. where
546 they would be found in a "normal" Module::Build-style distribu‐
547 tion. This parameter is mainly intended to support alternative
548 layouts of files.
549 For instance, if you have an old-style MakeMaker distribution
551 for a module called "Foo::Bar" and a Bar.pm file at the top
552 level of the distribution, you could specify your layout in
553 your "Build.PL" like this:
554 my $build = Module::Build->new
556 (
557 module_name => 'Foo::Bar',
558 ...
559 pm_files => { 'Bar.pm' => 'lib/Foo/Bar.pm' },
560 );
561 Note that the values should include "lib/", because this is
563 where they would be found in a "normal" Module::Build-style
564 distribution.
565 Note also that the path specifications are always given in
567 Unix-like format, not in the style of the local system.
568 pod_files
570 [version 0.19]
571 Just like "pm_files", but used for specifying the set of ".pod"
573 files in your distribution.
574 recommends
576 [version 0.08]
577 This is just like the "requires" argument, except that modules
579 listed in this section aren't essential, just a good idea.
580 We'll just print a friendly warning if one of these modules
581 aren't found, but we'll continue running.
582 If a module is recommended but not required, all tests should
584 still pass if the module isn't installed. This may mean that
585 some tests may be skipped if recommended dependencies aren't
586 present.
587 Automated tools like CPAN.pm should inform the user when recom‐
589 mended modules aren't installed, and it should offer to install
590 them if it wants to be helpful.
591 See the documentation for "PREREQUISITES" in Mod‐
593 ule::Build::Authoring for the details of how requirements can
594 be specified.
595 recursive_test_files
597 [version 0.28]
598 Normally, "Module::Build" does not search subdirectories when
600 looking for tests to run. When this options is set it will
601 search recursively in all subdirectories of the standard 't'
602 test directory.
603 requires
605 [version 0.07]
606 An optional "requires" argument specifies any module prerequi‐
608 sites that the current module depends on.
609 One note: currently "Module::Build" doesn't actually require
611 the user to have dependencies installed, it just strongly
612 urges. In the future we may require it. There's also a "rec‐
613 ommends" section for things that aren't absolutely required.
614 Automated tools like CPAN.pm should refuse to install a module
616 if one of its dependencies isn't satisfied, unless a "force"
617 command is given by the user. If the tools are helpful, they
618 should also offer to install the dependencies.
619 A synonym for "requires" is "prereq", to help succour people
621 transitioning from "ExtUtils::MakeMaker". The "requires" term
622 is preferred, but the "prereq" term will remain valid in future
623 distributions.
624 See the documentation for "PREREQUISITES" in Mod‐
626 ule::Build::Authoring for the details of how requirements can
627 be specified.
628 script_files
630 [version 0.18]
631 An optional parameter specifying a set of files that should be
633 installed as executable perl scripts when the module is
634 installed. May be given as an array reference of the files, or
635 as a hash reference whose keys are the files (and whose values
636 will currently be ignored).
637 The default is to install no script files - in other words,
639 there is no default location where Module::Build will look for
640 script files to install.
641 For backward compatibility, you may use the parameter "scripts"
643 instead of "script_files". Please consider this usage depre‐
644 cated, though it will continue to exist for several version
645 releases.
646 sign
648 [version 0.16]
649 If a true value is specified for this parameter, "Module::Sig‐
651 nature" will be used (via the 'distsign' action) to create a
652 SIGNATURE file for your distribution during the 'distdir'
653 action, and to add the SIGNATURE file to the MANIFEST (there‐
654 fore, don't add it yourself).
655 The default value is false. In the future, the default may
657 change to true if you have "Module::Signature" installed on
658 your system.
659 test_files
661 [version 0.23]
662 An optional parameter specifying a set of files that should be
664 used as "Test::Harness"-style regression tests to be run during
665 the "test" action. May be given as an array reference of the
666 files, or as a hash reference whose keys are the files (and
667 whose values will currently be ignored). If the argument is
668 given as a single string (not in an array reference), that
669 string will be treated as a "glob()" pattern specifying the
670 files to use.
671 The default is to look for a test.pl script in the top-level
673 directory of the distribution, and any files matching the glob
674 pattern "*.t" in the t/ subdirectory. If the "recur‐
675 sive_test_files" property is true, then the "t/" directory will
676 be scanned recursively for "*.t" files.
677 xs_files
679 [version 0.19]
680 Just like "pm_files", but used for specifying the set of ".xs"
682 files in your distribution.
683 new_from_context(%args)
685 [version 0.28]
686 When called from a directory containing a Build.PL script and a
688 META.yml file (in other words, the base directory of a distribu‐
689 tion), this method will run the Build.PL and return the resulting
690 "Module::Build" object to the caller. Any key-value arguments
691 given to "new_from_context()" are essentially like command line
692 arguments given to the Build.PL script, so for example you could
693 pass "verbose => 1" to this method to turn on verbosity.
694 resume()
696 [version 0.03]
697 You'll probably never call this method directly, it's only called
699 from the auto-generated "Build" script. The "new()" method is only
700 called once, when the user runs "perl Build.PL". Thereafter, when
701 the user runs "Build test" or another action, the "Module::Build"
702 object is created using the "resume()" method to re-instantiate
703 with the settings given earlier to "new()".
704 subclass()
706 [version 0.06]
707 This creates a new "Module::Build" subclass on the fly, as
709 described in the "SUBCLASSING" in Module::Build::Authoring section.
710 The caller must provide either a "class" or "code" parameter, or
711 both. The "class" parameter indicates the name to use for the new
712 subclass, and defaults to "MyModuleBuilder". The "code" parameter
713 specifies Perl code to use as the body of the subclass.
714 METHODS
716 add_build_element($type)
718 [version 0.26]
719 Adds a new type of entry to the build process. Accepts a single
721 string specifying its type-name. There must also be a method
722 defined to process things of that type, e.g. if you add a build
723 element called 'foo', then you must also define a method called
724 "process_foo_files()".
725 See also "Adding new file types to the build process" in Mod‐
727 ule::Build::Cookbook.
728 add_to_cleanup(@files)
730 [version 0.03]
731 You may call "$self->add_to_cleanup(@patterns)" to tell "Mod‐
733 ule::Build" that certain files should be removed when the user per‐
734 forms the "Build clean" action. The arguments to the method are
735 patterns suitable for passing to Perl's "glob()" function, speci‐
736 fied in either Unix format or the current machine's native format.
737 It's usually convenient to use Unix format when you hard-code the
738 filenames (e.g. in Build.PL) and the native format when the names
739 are programmatically generated (e.g. in a testing script).
740 I decided to provide a dynamic method of the $build object, rather
742 than just use a static list of files named in the Build.PL, because
743 these static lists can get difficult to manage. I usually prefer
744 to keep the responsibility for registering temporary files close to
745 the code that creates them.
746 args()
748 [version 0.26]
749 my $args_href = $build->args;
751 my %args = $build->args;
752 my $arg_value = $build->args($key);
753 $build->args($key, $value);
754 This method is the preferred interface for retrieving the arguments
756 passed via command line options to Build.PL or Build, minus the
757 Module-Build specific options.
758 When called in in a scalar context with no arguments, this method
760 returns a reference to the hash storing all of the arguments; in an
761 array context, it returns the hash itself. When passed a single
762 argument, it returns the value stored in the args hash for that
763 option key. When called with two arguments, the second argument is
764 assigned to the args hash under the key passed as the first argu‐
765 ment.
766 autosplit_file($from, $to)
768 [version 0.28]
769 Invokes the "AutoSplit" module on the $from file, sending the out‐
771 put to the "lib/auto" directory inside $to. $to is typically the
772 "blib/" directory.
773 base_dir()
775 [version 0.14]
776 Returns a string containing the root-level directory of this build,
778 i.e. where the "Build.PL" script and the "lib" directory can be
779 found. This is usually the same as the current working directory,
780 because the "Build" script will "chdir()" into this directory as
781 soon as it begins execution.
782 build_requires()
784 [version 0.21]
785 Returns a hash reference indicating the "build_requires" prerequi‐
787 sites that were passed to the "new()" method.
788 check_installed_status($module, $version)
790 [version 0.11]
791 This method returns a hash reference indicating whether a version
793 dependency on a certain module is satisfied. The $module argument
794 is given as a string like "Data::Dumper" or "perl", and the $ver‐
795 sion argument can take any of the forms described in requires
796 above. This allows very fine-grained version checking.
797 The returned hash reference has the following structure:
799 {
801 ok => $whether_the_dependency_is_satisfied,
802 have => $version_already_installed,
803 need => $version_requested, # Same as incoming $version argument
804 message => $informative_error_message,
805 }
806 If no version of $module is currently installed, the "have" value
808 will be the string "<none>". Otherwise the "have" value will sim‐
809 ply be the version of the installed module. Note that this means
810 that if $module is installed but doesn't define a version number,
811 the "have" value will be "undef" - this is why we don't use "undef"
812 for the case when $module isn't installed at all.
813 This method may be called either as an object method
815 ("$build->check_installed_status($module, $version)") or as a class
816 method ("Module::Build->check_installed_status($module, $ver‐
817 sion)").
818 check_installed_version($module, $version)
820 [version 0.05]
821 Like "check_installed_status()", but simply returns true or false
823 depending on whether module $module satisfies the dependency $ver‐
824 sion.
825 If the check succeeds, the return value is the actual version of
827 $module installed on the system. This allows you to do the follow‐
828 ing:
829 my $installed = $build->check_installed_version('DBI', '1.15');
831 if ($installed) {
832 print "Congratulations, version $installed of DBI is installed.\n";
833 } else {
834 die "Sorry, you must install DBI.\n";
835 }
836 If the check fails, we return false and set $@ to an informative
838 error message.
839 If $version is any non-true value (notably zero) and any version of
841 $module is installed, we return true. In this case, if $module
842 doesn't define a version, or if its version is zero, we return the
843 special value "0 but true", which is numerically zero, but logi‐
844 cally true.
845 In general you might prefer to use "check_installed_status" if you
847 need detailed information, or this method if you just need a yes/no
848 answer.
849 compare_versions($v1, $op, $v2)
851 [version 0.28]
852 Compares two module versions $v1 and $v2 using the operator $op,
854 which should be one of Perl's numeric operators like "!=" or ">="
855 or the like. We do at least a halfway-decent job of handling ver‐
856 sions that aren't strictly numeric, like "0.27_02", but exotic
857 stuff will likely cause problems.
858 In the future, the guts of this method might be replaced with a
860 call out to "version.pm".
861 config($key)
863 config($key, $value)
864 config() [deprecated]
865 [version 0.22]
866 With a single argument $key, returns the value associated with that
868 key in the "Config.pm" hash, including any changes the author or
869 user has specified.
870 With $key and $value arguments, sets the value for future callers
872 of "config($key)".
873 With no arguments, returns a hash reference containing all such
875 key-value pairs. This usage is deprecated, though, because it's a
876 resource hog and violates encapsulation.
877 config_data($name)
879 config_data($name => $value)
880 [version 0.26]
881 With a single argument, returns the value of the configuration
883 variable $name. With two arguments, sets the given configuration
884 variable to the given value. The value may be any perl scalar
885 that's serializable with "Data::Dumper". For instance, if you
886 write a module that can use a MySQL or PostgreSQL back-end, you
887 might create configuration variables called "mysql_connect" and
888 "postgres_connect", and set each to an array of connection parame‐
889 ters for "DBI->connect()".
890 Configuration values set in this way using the Module::Build object
892 will be available for querying during the build/test process and
893 after installation via the generated "...::ConfigData" module, as
894 "...::ConfigData->config($name)".
895 The "feature()" and "config_data()" methods represent Mod‐
897 ule::Build's main support for configuration of installed modules.
898 See also "SAVING CONFIGURATION INFORMATION" in Mod‐
899 ule::Build::Authoring.
900 conflicts()
902 [version 0.21]
903 Returns a hash reference indicating the "conflicts" prerequisites
905 that were passed to the "new()" method.
906 contains_pod($file)
908 [version 0.20]
909 [Deprecated] Please see Module::Build::ModuleInfo instead.
911 Returns true if the given file appears to contain POD documenta‐
913 tion. Currently this checks whether the file has a line beginning
914 with '=pod', '=head', or '=item', but the exact semantics may
915 change in the future.
916 copy_if_modified(%parameters)
918 [version 0.19]
919 Takes the file in the "from" parameter and copies it to the file in
921 the "to" parameter, or the directory in the "to_dir" parameter, if
922 the file has changed since it was last copied (or if it doesn't
923 exist in the new location). By default the entire directory struc‐
924 ture of "from" will be copied into "to_dir"; an optional "flatten"
925 parameter will copy into "to_dir" without doing so.
926 Returns the path to the destination file, or "undef" if nothing
928 needed to be copied.
929 Any directories that need to be created in order to perform the
931 copying will be automatically created.
932 The destination file is set to read-only. If the source file has
934 the executable bit set, then the destination file will be made exe‐
935 cutable.
936 create_build_script()
938 [version 0.05]
939 Creates an executable script called "Build" in the current direc‐
941 tory that will be used to execute further user actions. This
942 script is roughly analogous (in function, not in form) to the Make‐
943 file created by "ExtUtils::MakeMaker". This method also creates
944 some temporary data in a directory called "_build/". Both of these
945 will be removed when the "realclean" action is performed.
946 Among the files created in "_build/" is a _build/prereqs file con‐
948 taining the set of prerequisites for this distribution, as a hash
949 of hashes. This file may be "eval()"-ed to obtain the authorita‐
950 tive set of prereqs, which might be different from the contents of
951 META.yml (because Build.PL might have set them dynamically). But
952 fancy developers take heed: do not put any fancy custom runtime
953 code in the _build/prereqs file, leave it as a static declaration
954 containing only strings and numbers. Similarly, do not alter the
955 structure of the internal "$self->{properties}{requires}" (etc.)
956 data members, because that's where this data comes from.
957 current_action()
959 [version 0.28]
960 Returns the name of the currently-running action, such as "build"
962 or "test". This action is not necessarily the action that was
963 originally invoked by the user. For example, if the user invoked
964 the "test" action, current_action() would initially return "test".
965 However, action "test" depends on action "code", so cur‐
966 rent_action() will return "code" while that dependency is being
967 executed. Once that action has completed, current_action() will
968 again return "test".
969 If you need to know the name of the original action invoked by the
971 user, see invoked_action() below.
972 depends_on(@actions)
974 [version 0.28]
975 Invokes the named action or list of actions in sequence. Using
977 this method is preferred to calling the action explicitly because
978 it performs some internal record-keeping, and it ensures that the
979 same action is not invoked multiple times (note: in future versions
980 of Module::Build it's conceivable that this run-only-once mechanism
981 will be changed to something more intelligent).
982 Note that the name of this method is something of a misnomer; it
984 should really be called something like
985 "invoke_actions_unless_already_invoked()" or something, but for
986 better or worse (perhaps better!) we were still thinking in
987 "make"-like dependency terms when we created this method.
988 See also "dispatch()". The main distinction between the two is
990 that "depends_on()" is meant to call an action from inside another
991 action, whereas "dispatch()" is meant to set the very top action in
992 motion.
993 dir_contains($first_dir, $second_dir)
995 [version 0.28]
996 Returns true if the first directory logically contains the second
998 directory. This is just a convenience function because
999 "File::Spec" doesn't really provide an easy way to figure this out
1000 (but "Path::Class" does...).
1001 dispatch($action, %args)
1003 [version 0.03]
1004 Invokes the build action $action. Optionally, a list of options
1006 and their values can be passed in. This is equivalent to invoking
1007 an action at the command line, passing in a list of options.
1008 Custom options that have not been registered must be passed in as a
1010 hash reference in a key named "args":
1011 $build->dispatch('foo', verbose => 1, args => { my_option => 'value' });
1013 This method is intended to be used to programmatically invoke build
1015 actions, e.g. by applications controlling Module::Build-based
1016 builds rather than by subclasses.
1017 See also "depends_on()". The main distinction between the two is
1019 that "depends_on()" is meant to call an action from inside another
1020 action, whereas "dispatch()" is meant to set the very top action in
1021 motion.
1022 dist_dir()
1024 [version 0.28]
1025 Returns the name of the directory that will be created during the
1027 "dist" action. The name is derived from the "dist_name" and
1028 "dist_version" properties.
1029 dist_name()
1031 [version 0.21]
1032 Returns the name of the current distribution, as passed to the
1034 "new()" method in a "dist_name" or modified "module_name" parame‐
1035 ter.
1036 dist_version()
1038 [version 0.21]
1039 Returns the version of the current distribution, as determined by
1041 the "new()" method from a "dist_version", "dist_version_from", or
1042 "module_name" parameter.
1043 do_system($cmd, @args)
1045 [version 0.21]
1046 This is a fairly simple wrapper around Perl's "system()" built-in
1048 command. Given a command and an array of optional arguments, this
1049 method will print the command to "STDOUT", and then execute it
1050 using Perl's "system()". It returns true or false to indicate suc‐
1051 cess or failure (the opposite of how "system()" works, but more
1052 intuitive).
1053 Note that if you supply a single argument to "do_system()", it
1055 will/may be processed by the systems's shell, and any special char‐
1056 acters will do their special things. If you supply multiple argu‐
1057 ments, no shell will get involved and the command will be executed
1058 directly.
1059 feature($name)
1061 feature($name => $value)
1062 [version 0.26]
1063 With a single argument, returns true if the given feature is set.
1065 With two arguments, sets the given feature to the given boolean
1066 value. In this context, a "feature" is any optional functionality
1067 of an installed module. For instance, if you write a module that
1068 could optionally support a MySQL or PostgreSQL backend, you might
1069 create features called "mysql_support" and "postgres_support", and
1070 set them to true/false depending on whether the user has the proper
1071 databases installed and configured.
1072 Features set in this way using the Module::Build object will be
1074 available for querying during the build/test process and after
1075 installation via the generated "...::ConfigData" module, as
1076 "...::ConfigData->feature($name)".
1077 The "feature()" and "config_data()" methods represent Mod‐
1079 ule::Build's main support for configuration of installed modules.
1080 See also "SAVING CONFIGURATION INFORMATION" in Mod‐
1081 ule::Build::Authoring.
1082 have_c_compiler()
1084 [version 0.21]
1085 Returns true if the current system seems to have a working C com‐
1087 piler. We currently determine this by attempting to compile a sim‐
1088 ple C source file and reporting whether the attempt was successful.
1089 install_base_relpaths()
1091 install_base_relpaths($type)
1092 install_base_relpaths($type => $path)
1093 [version 0.28]
1094 Set or retrieve the relative paths that are appended to
1096 "install_base" for any installable element. This is useful if you
1097 want to set the relative install path for custom build elements.
1098 With no argument, it returns a reference to a hash containing all
1100 elements and their respective values. This hash should not be modi‐
1101 fied directly; use the multi-argument below form to change values.
1102 The single argument form returns the value associated with the ele‐
1104 ment $type.
1105 The multi-argument form allows you to set the paths for element
1107 types. $value must be a relative path using unix-like paths. (A
1108 series of directories seperated by slashes. Eg 'foo/bar'.) The
1109 return value is a localized path based on $value.
1110 Assigning the value "undef" to an element causes it to be removed.
1112 install_destination($type)
1114 [version 0.28]
1115 Returns the directory in which items of type $type (e.g. "lib",
1117 "arch", "bin", or anything else returned by the "install_types()"
1118 method) will be installed during the "install" action. Any set‐
1119 tings for "install_path", "install_base", and "prefix" are taken
1120 into account when determining the return value.
1121 install_path()
1123 install_path($type)
1124 install_path($type => $path)
1125 [version 0.28]
1126 Set or retrieve paths for specific installable elements. This is
1128 useful when you want to examine any explicit install paths speci‐
1129 fied by the user on the command line, or if you want to set the
1130 install path for a specific installable element based on another
1131 attribute like "install_base()".
1132 With no argument, it returns a reference to a hash containing all
1134 elements and their respective values. This hash should not be modi‐
1135 fied directly; use the multi-argument below form to change values.
1136 The single argument form returns the value associated with the ele‐
1138 ment $type.
1139 The multi-argument form allows you to set the paths for element
1141 types. The supplied $path should be an absolute path to install
1142 elements of $type. The return value is $path.
1143 Assigning the value "undef" to an element causes it to be removed.
1145 install_types()
1147 [version 0.28]
1148 Returns a list of installable types that this build knows about.
1150 These types each correspond to the name of a directory in blib/,
1151 and the list usually includes items such as "lib", "arch", "bin",
1152 "script", "libdoc", "bindoc", and if HTML documentation is to be
1153 built, "libhtml" and "binhtml". Other user-defined types may also
1154 exist.
1155 invoked_action()
1157 [version 0.28]
1158 This is the name of the original action invoked by the user. This
1160 value is set when the user invokes Build.PL, the Build script, or
1161 programatically through the dispatch() method. It does not change
1162 as sub-actions are executed as dependencies are evaluated.
1163 To get the name of the currently executing dependency, see cur‐
1165 rent_action() above.
1166 notes()
1168 notes($key)
1169 notes($key => $value)
1170 [version 0.20]
1171 The "notes()" value allows you to store your own persistent infor‐
1173 mation about the build, and to share that information among differ‐
1174 ent entities involved in the build. See the example in the "cur‐
1175 rent()" method.
1176 The "notes()" method is essentally a glorified hash access. With
1178 no arguments, "notes()" returns the entire hash of notes. With one
1179 argument, "notes($key)" returns the value associated with the given
1180 key. With two arguments, "notes($key, $value)" sets the value
1181 associated with the given key to $value and returns the new value.
1182 The lifetime of the "notes" data is for "a build" - that is, the
1184 "notes" hash is created when "perl Build.PL" is run (or when the
1185 "new()" method is run, if the Module::Build Perl API is being used
1186 instead of called from a shell), and lasts until "perl Build.PL" is
1187 run again or the "clean" action is run.
1188 orig_dir()
1190 [version 0.28]
1191 Returns a string containing the working directory that was in
1193 effect before the Build script chdir()-ed into the "base_dir".
1194 This might be useful for writing wrapper tools that might need to
1195 chdir() back out.
1196 os_type()
1198 [version 0.04]
1199 If you're subclassing Module::Build and some code needs to alter
1201 its behavior based on the current platform, you may only need to
1202 know whether you're running on Windows, Unix, MacOS, VMS, etc., and
1203 not the fine-grained value of Perl's $^O variable. The "os_type()"
1204 method will return a string like "Windows", "Unix", "MacOS", "VMS",
1205 or whatever is appropriate. If you're running on an unknown plat‐
1206 form, it will return "undef" - there shouldn't be many unknown
1207 platforms though.
1208 prefix_relpaths()
1210 prefix_relpaths($installdirs)
1211 prefix_relpaths($installdirs, $type)
1212 prefix_relpaths($installdirs, $type => $path)
1213 [version 0.28]
1214 Set or retrieve the relative paths that are appended to "prefix"
1216 for any installable element. This is useful if you want to set the
1217 relative install path for custom build elements.
1218 With no argument, it returns a reference to a hash containing all
1220 elements and their respective values as defined by the current
1221 "installdirs" setting.
1222 With a single argument, it returns a reference to a hash containing
1224 all elements and their respective values as defined by
1225 $installdirs.
1226 The hash returned by the above calls should not be modified
1228 directly; use the three-argument below form to change values.
1229 The two argument form returns the value associated with the element
1231 $type.
1232 The multi-argument form allows you to set the paths for element
1234 types. $value must be a relative path using unix-like paths. (A
1235 series of directories seperated by slashes. Eg 'foo/bar'.) The
1236 return value is a localized path based on $value.
1237 Assigning the value "undef" to an element causes it to be removed.
1239 prepare_metadata()
1241 [version 0.28]
1242 This method is provided for authors to override to customize the
1244 fields of META.yml. It is passed a YAML::Node node object which
1245 can be modified as desired and then returned. E.g.
1246 package My::Builder;
1248 use base 'Module::Build';
1249 sub prepare_metadata {
1251 my $self = shift;
1252 my $node = $self->SUPER::prepare_metadata( shift );
1253 $node->{custom_field} = 'foo';
1254 return $node;
1255 }
1256 prereq_failures()
1258 [version 0.11]
1259 Returns a data structure containing information about any failed
1261 prerequisites (of any of the types described above), or "undef" if
1262 all prerequisites are met.
1263 The data structure returned is a hash reference. The top level
1265 keys are the type of prerequisite failed, one of "requires",
1266 "build_requires", "conflicts", or "recommends". The associated
1267 values are hash references whose keys are the names of required (or
1268 conflicting) modules. The associated values of those are hash ref‐
1269 erences indicating some information about the failure. For exam‐
1270 ple:
1271 {
1273 have => '0.42',
1274 need => '0.59',
1275 message => 'Version 0.42 is installed, but we need version 0.59',
1276 }
1277 or
1279 {
1281 have => '<none>',
1282 need => '0.59',
1283 message => 'Prerequisite Foo isn't installed',
1284 }
1285 This hash has the same structure as the hash returned by the
1287 "check_installed_status()" method, except that in the case of "con‐
1288 flicts" dependencies we change the "need" key to "conflicts" and
1289 construct a proper message.
1290 Examples:
1292 # Check a required dependency on Foo::Bar
1294 if ( $build->prereq_failures->{requires}{Foo::Bar} ) { ...
1295 # Check whether there were any failures
1297 if ( $build->prereq_failures ) { ...
1298 # Show messages for all failures
1300 my $failures = $build->prereq_failures;
1301 while (my ($type, $list) = each %$failures) {
1302 while (my ($name, $hash) = each %$list) {
1303 print "Failure for $name: $hash->{message}\n";
1304 }
1305 }
1306 prereq_report()
1308 [version 0.28]
1309 Returns a human-readable (table-form) string showing all prerequi‐
1311 sites, the versions required, and the versions actually installed.
1312 This can be useful for reviewing the configuration of your system
1313 prior to a build, or when compiling data to send for a bug report.
1314 The "prereq_report" action is just a thin wrapper around the "pre‐
1315 req_report()" method.
1316 prompt($message, $default)
1318 [version 0.12]
1319 Asks the user a question and returns their response as a string.
1321 The first argument specifies the message to display to the user
1322 (for example, "Where do you keep your money?"). The second argu‐
1323 ment, which is optional, specifies a default answer (for example,
1324 "wallet"). The user will be asked the question once.
1325 If "prompt()" detects that it is not running interactively and
1327 there is nothing on STDIN or if the PERL_MM_USE_DEFAULT environment
1328 variable is set to true, the $default will be used without prompt‐
1329 ing.
1330 To prevent automated processes from blocking, the user must either
1332 set PERL_MM_USE_DEFAULT or attach something to STDIN (this can be a
1333 pipe/file containing a scripted set of answers or /dev/null.)
1334 If no $default is provided an empty string will be used instead.
1336 In non-interactive mode, the absence of $default is an error
1337 (though explicitly passing "undef()" as the default is valid as of
1338 0.27.)
1339 This method may be called as a class or object method.
1341 recommends()
1343 [version 0.21]
1344 Returns a hash reference indicating the "recommends" prerequisites
1346 that were passed to the "new()" method.
1347 requires()
1349 [version 0.21]
1350 Returns a hash reference indicating the "requires" prerequisites
1352 that were passed to the "new()" method.
1353 rscan_dir($dir, $pattern)
1355 [version 0.28]
1356 Uses "File::Find" to traverse the directory $dir, returning a ref‐
1358 erence to an array of entries matching $pattern. $pattern may
1359 either be a regular expression (using "qr//" or just a plain
1360 string), or a reference to a subroutine that will return true for
1361 wanted entries. If $pattern is not given, all entries will be
1362 returned.
1363 Examples:
1365 # All the *.pm files in lib/
1367 $m->rscan_dir('lib', qr/\.pm$/)
1368 # All the files in blib/ that aren't *.html files
1370 $m->rscan_dir('blib', sub {-f $_ and not /\.html$/});
1371 # All the files in t/
1373 $m->rscan_dir('t');
1374 runtime_params()
1376 runtime_params($key)
1377 [version 0.28]
1378 The "runtime_params()" method stores the values passed on the com‐
1380 mand line for valid properties (that is, any command line options
1381 for which "valid_property()" returns a true value). The value on
1382 the command line may override the default value for a property, as
1383 well as any value specified in a call to "new()". This allows you
1384 to programmatically tell if "perl Build.PL" or any execution of
1385 "./Build" had command line options specified that override valid
1386 properties.
1387 The "runtime_params()" method is essentally a glorified read-only
1389 hash. With no arguments, "runtime_params()" returns the entire
1390 hash of properties specified on the command line. With one argu‐
1391 ment, "runtime_params($key)" returns the value associated with the
1392 given key.
1393 The lifetime of the "runtime_params" data is for "a build" - that
1395 is, the "runtime_params" hash is created when "perl Build.PL" is
1396 run (or when the "new()" method is called, if the Module::Build
1397 Perl API is being used instead of called from a shell), and lasts
1398 until "perl Build.PL" is run again or the "clean" action is run.
1399 script_files()
1401 [version 0.18]
1402 Returns a hash reference whose keys are the perl script files to be
1404 installed, if any. This corresponds to the "script_files" parame‐
1405 ter to the "new()" method. With an optional argument, this parame‐
1406 ter may be set dynamically.
1407 For backward compatibility, the "scripts()" method does exactly the
1409 same thing as "script_files()". "scripts()" is deprecated, but it
1410 will stay around for several versions to give people time to tran‐
1411 sition.
1412 up_to_date($source_file, $derived_file)
1414 up_to_date(\@source_files, \@derived_files)
1415 [version 0.20]
1416 This method can be used to compare a set of source files to a set
1418 of derived files. If any of the source files are newer than any of
1419 the derived files, it returns false. Additionally, if any of the
1420 derived files do not exist, it returns false. Otherwise it returns
1421 true.
1422 The arguments may be either a scalar or an array reference of file
1424 names.
1425 y_n($message, $default)
1427 [version 0.12]
1428 Asks the user a yes/no question using "prompt()" and returns true
1430 or false accordingly. The user will be asked the question repeat‐
1431 edly until they give an answer that looks like "yes" or "no".
1432 The first argument specifies the message to display to the user
1434 (for example, "Shall I invest your money for you?"), and the second
1435 argument specifies the default answer (for example, "y").
1436 Note that the default is specified as a string like "y" or "n", and
1438 the return value is a Perl boolean value like 1 or 0. I thought
1439 about this for a while and this seemed like the most useful way to
1440 do it.
1441 This method may be called as a class or object method.
1443 Autogenerated Accessors
1445 In addition to the aforementioned methods, there are also some get/set
1447 accessor methods for the following properties:
1448 PL_files()
1450 allow_mb_mismatch()
1451 autosplit()
1452 base_dir()
1453 bindoc_dirs()
1454 blib()
1455 build_bat()
1456 build_class()
1457 build_elements()
1458 build_requires()
1459 build_script()
1460 c_source()
1461 config_dir()
1462 conflicts()
1463 create_makefile_pl()
1464 create_packlist()
1465 create_readme()
1466 debugger()
1467 destdir()
1468 get_options()
1469 html_css()
1470 include_dirs()
1471 install_base()
1472 install_sets()
1473 installdirs()
1474 libdoc_dirs()
1475 license()
1476 magic_number()
1477 mb_version()
1478 meta_add()
1479 meta_merge()
1480 metafile()
1481 module_name()
1482 orig_dir()
1483 original_prefix()
1484 perl()
1485 pm_files()
1486 pod_files()
1487 pollute()
1488 prefix()
1489 prereq_action_types()
1490 quiet()
1491 recommends()
1492 recurse_into()
1493 recursive_test_files()
1494 requires()
1495 scripts()
1496 use_rcfile()
1497 verbose()
1498 xs_files()
1499
1501 Ken Williams <kwilliams@cpan.org>
1502
1504 Copyright (c) 2001-2006 Ken Williams. All rights reserved.
1505 This library is free software; you can redistribute it and/or modify it
1507 under the same terms as Perl itself.
1508
1510 perl(1), Module::Build(3), Module::Build::Authoring(3), Mod‐
1511 ule::Build::Cookbook(3), ExtUtils::MakeMaker(3), YAML(3)
1512 META.yml Specification: <http://module-build.source‐
1514 forge.net/META-spec-current.html>
1515perl v5.8.8 2007-04-02 Module::Build::API(3)