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