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