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 Use of this parameter is discouraged.
243 create_readme
245 [version 0.22]
246 This parameter tells Module::Build to automatically create a
248 README file at the top level of your distribution. Currently
249 it will simply use "Pod::Text" (or "Pod::Readme" if it's
250 installed) on the file indicated by "dist_version_from" and put
251 the result in the README file. This is by no means the only
252 recommended style for writing a README, but it seems to be one
253 common one used on the CPAN.
254 If you generate a README in this way, it's probably a good idea
256 to create a separate INSTALL file if that information isn't in
257 the generated README.
258 dist_abstract
260 [version 0.20]
261 This should be a short description of the distribution. This
263 is used when generating metadata for META.yml and PPD files.
264 If it is not given then "Module::Build" looks in the POD of the
265 module from which it gets the distribution's version. If it
266 finds a POD section marked "=head1 NAME", then it looks for the
267 first line matching "\s+-\s+(.+)", and uses the captured text
268 as the abstract.
269 dist_author
271 [version 0.20]
272 This should be something like "John Doe <jdoe@example.com>", or
274 if there are multiple authors, an anonymous array of strings
275 may be specified. This is used when generating metadata for
276 META.yml and PPD files. If this is not specified, then
277 "Module::Build" looks at the module from which it gets the
278 distribution's version. If it finds a POD section marked
279 "=head1 AUTHOR", then it uses the contents of this section.
280 dist_name
282 [version 0.11]
283 Specifies the name for this distribution. Most authors won't
285 need to set this directly, they can use "module_name" to set
286 "dist_name" to a reasonable default. However, some
287 agglomerative distributions like "libwww-perl" or "bioperl"
288 have names that don't correspond directly to a module name, so
289 "dist_name" can be set independently.
290 dist_suffix
292 [version 0.37]
293 Specifies an optional suffix to include after the version
295 number in the distribution directory (and tarball) name. The
296 only suffix currently recognized by PAUSE is 'TRIAL', which
297 indicates that the distribution should not be indexed. For
298 example:
299 Foo-Bar-1.23-TRIAL.tar.gz
301 This will automatically do the "right thing" depending on
303 "dist_version" and "release_status". When "dist_version" does
304 not have an underscore and "release_status" is not 'stable',
305 then "dist_suffix" will default to 'TRIAL'. Otherwise it will
306 default to the empty string, disabling the suffix.
307 In general, authors should only set this if they must override
309 the default behavior for some particular purpose.
310 dist_version
312 [version 0.11]
313 Specifies a version number for the distribution. See
315 "module_name" or "dist_version_from" for ways to have this set
316 automatically from a $VERSION variable in a module. One way or
317 another, a version number needs to be set.
318 dist_version_from
320 [version 0.11]
321 Specifies a file to look for the distribution version in. Most
323 authors won't need to set this directly, they can use
324 "module_name" to set it to a reasonable default.
325 The version is extracted from the specified file according to
327 the same rules as ExtUtils::MakeMaker and "CPAN.pm". It
328 involves finding the first line that matches the regular
329 expression
330 /([\$*])(([\w\:\']*)\bVERSION)\b.*\=/
332 eval()-ing that line, then checking the value of the $VERSION
334 variable. Quite ugly, really, but all the modules on CPAN
335 depend on this process, so there's no real opportunity to
336 change to something better.
337 If the target file of "dist_version_from" contains more than
339 one package declaration, the version returned will be the one
340 matching the configured "module_name".
341 dynamic_config
343 [version 0.07]
344 A boolean flag indicating whether the Build.PL file must be
346 executed to determine prerequisites, or whether they can be
347 determined solely from consulting its metadata file. The main
348 reason to set this to a true value is that your module adds or
349 removes prerequisites dynamically in Build.PL. If the flag is
350 omitted, it will be treated as 1 (true), because this is a
351 safer way to behave.
352 Currently "Module::Build" doesn't actually do anything with
354 this flag - it's up to higher-level tools like "CPAN.pm" to do
355 something useful with it. It can also be very helpful for
356 static analysis. See "dynamic_config" in CPAN::Meta::Spec for
357 details on the metadata field.
358 extra_compiler_flags
360 extra_linker_flags
361 [version 0.19]
362 These parameters can contain array references (or strings, in
364 which case they will be split into arrays) to pass through to
365 the compiler and linker phases when compiling/linking C code.
366 For example, to tell the compiler that your code is C++, you
367 might do:
368 my $build = Module::Build->new
370 (
371 module_name => 'Foo::Bar',
372 extra_compiler_flags => ['-x', 'c++'],
373 );
374 To link your XS code against glib you might write something
376 like:
377 my $build = Module::Build->new
379 (
380 module_name => 'Foo::Bar',
381 dynamic_config => 1,
382 extra_compiler_flags => scalar `glib-config --cflags`,
383 extra_linker_flags => scalar `glib-config --libs`,
384 );
385 extra_manify_args
387 [version 0.4006]
388 Any extra arguments to pass to "Pod::Man->new()" when building
390 man pages. One common choice might be "utf8 => 1" to get
391 Unicode support.
392 get_options
394 [version 0.26]
395 You can pass arbitrary command line options to Build.PL or
397 Build, and they will be stored in the Module::Build object and
398 can be accessed via the "args()" method. However, sometimes
399 you want more flexibility out of your argument processing than
400 this allows. In such cases, use the "get_options" parameter to
401 pass in a hash reference of argument specifications, and the
402 list of arguments to Build.PL or Build will be processed
403 according to those specifications before they're passed on to
404 "Module::Build"'s own argument processing.
405 The supported option specification hash keys are:
407 type
409 The type of option. The types are those supported by
410 Getopt::Long; consult its documentation for a complete
411 list. Typical types are "=s" for strings, "+" for additive
412 options, and "!" for negatable options. If the type is not
413 specified, it will be considered a boolean, i.e. no
414 argument is taken and a value of 1 will be assigned when
415 the option is encountered.
416 store
418 A reference to a scalar in which to store the value passed
419 to the option. If not specified, the value will be stored
420 under the option name in the hash returned by the "args()"
421 method.
422 default
424 A default value for the option. If no default value is
425 specified and no option is passed, then the option key will
426 not exist in the hash returned by "args()".
427 You can combine references to your own variables or subroutines
429 with unreferenced specifications, for which the result will
430 also be stored in the hash returned by "args()". For example:
431 my $loud = 0;
433 my $build = Module::Build->new
434 (
435 module_name => 'Foo::Bar',
436 get_options => {
437 Loud => { store => \$loud },
438 Dbd => { type => '=s' },
439 Quantity => { type => '+' },
440 }
441 );
442 print STDERR "HEY, ARE YOU LISTENING??\n" if $loud;
444 print "We'll use the ", $build->args('Dbd'), " DBI driver\n";
445 print "Are you sure you want that many?\n"
446 if $build->args('Quantity') > 2;
447 The arguments for such a specification can be called like so:
449 perl Build.PL --Loud --Dbd=DBD::pg --Quantity --Quantity --Quantity
451 WARNING: Any option specifications that conflict with
453 Module::Build's own options (defined by its properties) will
454 throw an exception. Use capitalized option names to avoid
455 unintended conflicts with future Module::Build options.
456 Consult the Getopt::Long documentation for details on its
458 usage.
459 include_dirs
461 [version 0.24]
462 Specifies any additional directories in which to search for C
464 header files. May be given as a string indicating a single
465 directory, or as a list reference indicating multiple
466 directories.
467 install_path
469 [version 0.19]
470 You can set paths for individual installable elements by using
472 the "install_path" parameter:
473 my $build = Module::Build->new
475 (
476 ...other stuff here...
477 install_path => {
478 lib => '/foo/lib',
479 arch => '/foo/lib/arch',
480 }
481 );
482 installdirs
484 [version 0.19]
485 Determines where files are installed within the normal perl
487 hierarchy as determined by Config.pm. Valid values are:
488 "core", "site", "vendor". The default is "site". See "INSTALL
489 PATHS" in Module::Build
490 license
492 [version 0.07]
493 Specifies the licensing terms of your distribution.
495 As of Module::Build version 0.36_14, you may use a
497 Software::License subclass name (e.g. 'Apache_2_0') instead of
498 one of the keys below.
499 The legacy list of valid license values include:
501 apache
503 The distribution is licensed under the Apache License,
504 Version 2.0 (<http://apache.org/licenses/LICENSE-2.0>).
505 apache_1_1
507 The distribution is licensed under the Apache Software
508 License, Version 1.1
509 (<http://apache.org/licenses/LICENSE-1.1>).
510 artistic
512 The distribution is licensed under the Artistic License, as
513 specified by the Artistic file in the standard Perl
514 distribution.
515 artistic_2
517 The distribution is licensed under the Artistic 2.0 License
518 (<http://opensource.org/licenses/artistic-license-2.0.php>.)
519 bsd The distribution is licensed under the BSD License
521 (<http://www.opensource.org/licenses/bsd-license.php>).
522 gpl The distribution is licensed under the terms of the GNU
524 General Public License
525 (<http://www.opensource.org/licenses/gpl-license.php>).
526 lgpl
528 The distribution is licensed under the terms of the GNU
529 Lesser General Public License
530 (<http://www.opensource.org/licenses/lgpl-license.php>).
531 mit The distribution is licensed under the MIT License
533 (<http://opensource.org/licenses/mit-license.php>).
534 mozilla
536 The distribution is licensed under the Mozilla Public
537 License. (<http://opensource.org/licenses/mozilla1.0.php>
538 or <http://opensource.org/licenses/mozilla1.1.php>)
539 open_source
541 The distribution is licensed under some other Open Source
542 Initiative-approved license listed at
543 <http://www.opensource.org/licenses/>.
544 perl
546 The distribution may be copied and redistributed under the
547 same terms as Perl itself (this is by far the most common
548 licensing option for modules on CPAN). This is a dual
549 license, in which the user may choose between either the
550 GPL or the Artistic license.
551 restrictive
553 The distribution may not be redistributed without special
554 permission from the author and/or copyright holder.
555 unrestricted
557 The distribution is licensed under a license that is not
558 approved by www.opensource.org but that allows distribution
559 without restrictions.
560 Note that you must still include the terms of your license in
562 your code and documentation - this field only sets the
563 information that is included in distribution metadata to let
564 automated tools figure out your licensing restrictions. Humans
565 still need something to read. If you choose to provide this
566 field, you should make sure that you keep it in sync with your
567 written documentation if you ever change your licensing terms.
568 You may also use a license type of "unknown" if you don't wish
570 to specify your terms in the metadata.
571 Also see the "create_license" parameter.
573 meta_add
575 [version 0.28]
576 A hash of key/value pairs that should be added to the META.yml
578 file during the "distmeta" action. Any existing entries with
579 the same names will be overridden.
580 See the "MODULE METADATA" section for details.
582 meta_merge
584 [version 0.28]
585 A hash of key/value pairs that should be merged into the
587 META.yml file during the "distmeta" action. Any existing
588 entries with the same names will be overridden.
589 The only difference between "meta_add" and "meta_merge" is
591 their behavior on hash-valued and array-valued entries:
592 "meta_add" will completely blow away the existing hash or array
593 value, but "meta_merge" will merge the supplied data into the
594 existing hash or array value.
595 See the "MODULE METADATA" section for details.
597 module_name
599 [version 0.03]
600 The "module_name" is a shortcut for setting default values of
602 "dist_name" and "dist_version_from", reflecting the fact that
603 the majority of CPAN distributions are centered around one
604 "main" module. For instance, if you set "module_name" to
605 "Foo::Bar", then "dist_name" will default to "Foo-Bar" and
606 "dist_version_from" will default to "lib/Foo/Bar.pm".
607 "dist_version_from" will in turn be used to set "dist_version".
608 Setting "module_name" won't override a "dist_*" parameter you
610 specify explicitly.
611 needs_compiler
613 [version 0.36]
614 The "needs_compiler" parameter indicates whether a compiler is
616 required to build the distribution. The default is false,
617 unless XS files are found or the "c_source" parameter is set,
618 in which case it is true. If true, ExtUtils::CBuilder is
619 automatically added to "build_requires" if needed.
620 For a distribution where a compiler is optional, e.g. a dual
622 XS/pure-Perl distribution, "needs_compiler" should explicitly
623 be set to a false value.
624 PL_files
626 [version 0.06]
627 An optional parameter specifying a set of ".PL" files in your
629 distribution. These will be run as Perl scripts prior to
630 processing the rest of the files in your distribution with the
631 name of the file they're generating as an argument. They are
632 usually used as templates for creating other files dynamically,
633 so that a file like "lib/Foo/Bar.pm.PL" might create the file
634 "lib/Foo/Bar.pm".
635 The files are specified with the ".PL" files as hash keys, and
637 the file(s) they generate as hash values, like so:
638 my $build = Module::Build->new
640 (
641 module_name => 'Foo::Bar',
642 ...
643 PL_files => { 'lib/Foo/Bar.pm.PL' => 'lib/Foo/Bar.pm' },
644 );
645 Note that the path specifications are always given in Unix-like
647 format, not in the style of the local system.
648 If your ".PL" scripts don't create any files, or if they create
650 files with unexpected names, or even if they create multiple
651 files, you can indicate that so that Module::Build can properly
652 handle these created files:
653 PL_files => {
655 'lib/Foo/Bar.pm.PL' => 'lib/Foo/Bar.pm',
656 'lib/something.PL' => ['/lib/something', '/lib/else'],
657 'lib/funny.PL' => [],
658 }
659 Here's an example of a simple PL file.
661 my $output_file = shift;
663 open my $fh, ">", $output_file or die "Can't open $output_file: $!";
664 print $fh <<'END';
666 #!/usr/bin/perl
667 print "Hello, world!\n";
669 END
670 PL files are not installed by default, so its safe to put them
672 in lib/ and bin/.
673 pm_files
675 [version 0.19]
676 An optional parameter specifying the set of ".pm" files in this
678 distribution, specified as a hash reference whose keys are the
679 files' locations in the distributions, and whose values are
680 their logical locations based on their package name, i.e. where
681 they would be found in a "normal" Module::Build-style
682 distribution. This parameter is mainly intended to support
683 alternative layouts of files.
684 For instance, if you have an old-style "MakeMaker" distribution
686 for a module called "Foo::Bar" and a Bar.pm file at the top
687 level of the distribution, you could specify your layout in
688 your "Build.PL" like this:
689 my $build = Module::Build->new
691 (
692 module_name => 'Foo::Bar',
693 ...
694 pm_files => { 'Bar.pm' => 'lib/Foo/Bar.pm' },
695 );
696 Note that the values should include "lib/", because this is
698 where they would be found in a "normal" Module::Build-style
699 distribution.
700 Note also that the path specifications are always given in
702 Unix-like format, not in the style of the local system.
703 pod_files
705 [version 0.19]
706 Just like "pm_files", but used for specifying the set of ".pod"
708 files in your distribution.
709 recommends
711 [version 0.08]
712 This is just like the "requires" argument, except that modules
714 listed in this section aren't essential, just a good idea.
715 We'll just print a friendly warning if one of these modules
716 aren't found, but we'll continue running.
717 If a module is recommended but not required, all tests should
719 still pass if the module isn't installed. This may mean that
720 some tests may be skipped if recommended dependencies aren't
721 present.
722 Automated tools like CPAN.pm should inform the user when
724 recommended modules aren't installed, and it should offer to
725 install them if it wants to be helpful.
726 See the documentation for "PREREQUISITES" in
728 Module::Build::Authoring for the details of how requirements
729 can be specified.
730 recursive_test_files
732 [version 0.28]
733 Normally, "Module::Build" does not search subdirectories when
735 looking for tests to run. When this options is set it will
736 search recursively in all subdirectories of the standard 't'
737 test directory.
738 release_status
740 [version 0.37]
741 The CPAN Meta Spec version 2 adds "release_status" to allow
743 authors to specify how a distribution should be indexed.
744 Consistent with the spec, this parameter can only have one
745 three values: 'stable', 'testing' or 'unstable'.
746 Unless explicitly set by the author, "release_status" will
748 default to 'stable' unless "dist_version" contains an
749 underscore, in which case it will default to 'testing'.
750 It is an error to specify a "release_status" of 'stable' when
752 "dist_version" contains an underscore character.
753 requires
755 [version 0.07]
756 An optional "requires" argument specifies any module
758 prerequisites that the current module depends on.
759 One note: currently "Module::Build" doesn't actually require
761 the user to have dependencies installed, it just strongly
762 urges. In the future we may require it. There's also a
763 "recommends" section for things that aren't absolutely
764 required.
765 Automated tools like CPAN.pm should refuse to install a module
767 if one of its dependencies isn't satisfied, unless a "force"
768 command is given by the user. If the tools are helpful, they
769 should also offer to install the dependencies.
770 A synonym for "requires" is "prereq", to help succour people
772 transitioning from "ExtUtils::MakeMaker". The "requires" term
773 is preferred, but the "prereq" term will remain valid in future
774 distributions.
775 See the documentation for "PREREQUISITES" in
777 Module::Build::Authoring for the details of how requirements
778 can be specified.
779 script_files
781 [version 0.18]
782 An optional parameter specifying a set of files that should be
784 installed as executable Perl scripts when the module is
785 installed. May be given as an array reference of the files, as
786 a hash reference whose keys are the files (and whose values
787 will currently be ignored), as a string giving the name of a
788 directory in which to find scripts, or as a string giving the
789 name of a single script file.
790 The default is to install any scripts found in a bin directory
792 at the top level of the distribution, minus any keys of
793 PL_files.
794 For backward compatibility, you may use the parameter "scripts"
796 instead of "script_files". Please consider this usage
797 deprecated, though it will continue to exist for several
798 version releases.
799 share_dir
801 [version 0.36]
802 An optional parameter specifying directories of static data
804 files to be installed as read-only files for use with
805 File::ShareDir. The "share_dir" property supports both
806 distribution-level and module-level share files.
807 The simplest use of "share_dir" is to set it to a directory
809 name or an arrayref of directory names containing files to be
810 installed in the distribution-level share directory.
811 share_dir => 'share'
813 Alternatively, if "share_dir" is a hashref, it may have "dist"
815 or "module" keys providing full flexibility in defining how
816 share directories should be installed.
817 share_dir => {
819 dist => [ 'examples', 'more_examples' ],
820 module => {
821 Foo::Templates => ['share/html', 'share/text'],
822 Foo::Config => 'share/config',
823 }
824 }
825 If "share_dir" is set, then File::ShareDir will automatically
827 be added to the "requires" hash.
828 sign
830 [version 0.16]
831 If a true value is specified for this parameter,
833 Module::Signature will be used (via the 'distsign' action) to
834 create a SIGNATURE file for your distribution during the
835 'distdir' action, and to add the SIGNATURE file to the MANIFEST
836 (therefore, don't add it yourself).
837 The default value is false. In the future, the default may
839 change to true if you have "Module::Signature" installed on
840 your system.
841 tap_harness_args
843 [version 0.2808_03]
844 An optional parameter specifying parameters to be passed to
846 TAP::Harness when running tests. Must be given as a hash
847 reference of parameters; see the TAP::Harness documentation for
848 details. Note that specifying this parameter will implicitly
849 set "use_tap_harness" to a true value. You must therefore be
850 sure to add TAP::Harness as a requirement for your module in
851 "build_requires".
852 test_files
854 [version 0.23]
855 An optional parameter specifying a set of files that should be
857 used as "Test::Harness"-style regression tests to be run during
858 the "test" action. May be given as an array reference of the
859 files, or as a hash reference whose keys are the files (and
860 whose values will currently be ignored). If the argument is
861 given as a single string (not in an array reference), that
862 string will be treated as a "glob()" pattern specifying the
863 files to use.
864 The default is to look for a test.pl script in the top-level
866 directory of the distribution, and any files matching the glob
867 pattern "*.t" in the t/ subdirectory. If the
868 "recursive_test_files" property is true, then the "t/"
869 directory will be scanned recursively for "*.t" files.
870 use_tap_harness
872 [version 0.2808_03]
873 An optional parameter indicating whether or not to use
875 TAP::Harness for testing rather than Test::Harness. Defaults to
876 false. If set to true, you must therefore be sure to add
877 TAP::Harness as a requirement for your module in
878 "build_requires". Implicitly set to a true value if
879 "tap_harness_args" is specified.
880 xs_files
882 [version 0.19]
883 Just like "pm_files", but used for specifying the set of ".xs"
885 files in your distribution.
886 new_from_context(%args)
888 [version 0.28]
889 When called from a directory containing a Build.PL script (in other
891 words, the base directory of a distribution), this method will run
892 the Build.PL and call "resume()" to return the resulting
893 "Module::Build" object to the caller. Any key-value arguments
894 given to "new_from_context()" are essentially like command line
895 arguments given to the Build.PL script, so for example you could
896 pass "verbose => 1" to this method to turn on verbosity.
897 resume()
899 [version 0.03]
900 You'll probably never call this method directly, it's only called
902 from the auto-generated "Build" script (and the "new_from_context"
903 method). The "new()" method is only called once, when the user
904 runs "perl Build.PL". Thereafter, when the user runs "Build test"
905 or another action, the "Module::Build" object is created using the
906 "resume()" method to re-instantiate with the settings given earlier
907 to "new()".
908 subclass()
910 [version 0.06]
911 This creates a new "Module::Build" subclass on the fly, as
913 described in the "SUBCLASSING" in Module::Build::Authoring section.
914 The caller must provide either a "class" or "code" parameter, or
915 both. The "class" parameter indicates the name to use for the new
916 subclass, and defaults to "MyModuleBuilder". The "code" parameter
917 specifies Perl code to use as the body of the subclass.
918 add_property
920 [version 0.31]
921 package 'My::Build';
923 use base 'Module::Build';
924 __PACKAGE__->add_property( 'pedantic' );
925 __PACKAGE__->add_property( answer => 42 );
926 __PACKAGE__->add_property(
927 'epoch',
928 default => sub { time },
929 check => sub {
930 return 1 if /^\d+$/;
931 shift->property_error( "'$_' is not an epoch time" );
932 return 0;
933 },
934 );
935 Adds a property to a Module::Build class. Properties are those
937 attributes of a Module::Build object which can be passed to the
938 constructor and which have accessors to get and set them. All of
939 the core properties, such as "module_name" and "license", are
940 defined using this class method.
941 The first argument to "add_property()" is always the name of the
943 property. The second argument can be either a default value for
944 the property, or a list of key/value pairs. The supported keys are:
945 "default"
947 The default value. May optionally be specified as a code
948 reference, in which case the return value from the execution of
949 the code reference will be used. If you need the default to be
950 a code reference, just use a code reference to return it, e.g.:
951 default => sub { sub { ... } },
953 "check"
955 A code reference that checks that a value specified for the
956 property is valid. During the execution of the code reference,
957 the new value will be included in the $_ variable. If the value
958 is correct, the "check" code reference should return true. If
959 the value is not correct, it sends an error message to
960 "property_error()" and returns false.
961 When this method is called, a new property will be installed in the
963 Module::Build class, and an accessor will be built to allow the
964 property to be get or set on the build object.
965 print $build->pedantic, $/;
967 $build->pedantic(0);
968 If the default value is a hash reference, this generates a special-
970 case accessor method, wherein individual key/value pairs may be set
971 or fetched:
972 print "stuff{foo} is: ", $build->stuff( 'foo' ), $/;
974 $build->stuff( foo => 'bar' );
975 print $build->stuff( 'foo' ), $/; # Outputs "bar"
976 Of course, you can still set the entire hash reference at once, as
978 well:
979 $build->stuff( { foo => 'bar', baz => 'yo' } );
981 In either case, if a "check" has been specified for the property,
983 it will be applied to the entire hash. So the check code reference
984 should look something like:
985 check => sub {
987 return 1 if defined $_ && exists $_->{foo};
988 shift->property_error(qq{Property "stuff" needs "foo"});
989 return 0;
990 },
991 property_error
993 [version 0.31]
994 METHODS
996 add_build_element($type)
997 [version 0.26]
998 Adds a new type of entry to the build process. Accepts a single
1000 string specifying its type-name. There must also be a method
1001 defined to process things of that type, e.g. if you add a build
1002 element called 'foo', then you must also define a method called
1003 "process_foo_files()".
1004 See also "Adding new file types to the build process" in
1006 Module::Build::Cookbook.
1007 add_to_cleanup(@files)
1009 [version 0.03]
1010 You may call "$self->add_to_cleanup(@patterns)" to tell
1012 "Module::Build" that certain files should be removed when the user
1013 performs the "Build clean" action. The arguments to the method are
1014 patterns suitable for passing to Perl's "glob()" function,
1015 specified in either Unix format or the current machine's native
1016 format. It's usually convenient to use Unix format when you hard-
1017 code the filenames (e.g. in Build.PL) and the native format when
1018 the names are programmatically generated (e.g. in a testing
1019 script).
1020 I decided to provide a dynamic method of the $build object, rather
1022 than just use a static list of files named in the Build.PL, because
1023 these static lists can get difficult to manage. I usually prefer
1024 to keep the responsibility for registering temporary files close to
1025 the code that creates them.
1026 args()
1028 [version 0.26]
1029 my $args_href = $build->args;
1031 my %args = $build->args;
1032 my $arg_value = $build->args($key);
1033 $build->args($key, $value);
1034 This method is the preferred interface for retrieving the arguments
1036 passed via command line options to Build.PL or Build, minus the
1037 Module-Build specific options.
1038 When called in a scalar context with no arguments, this method
1040 returns a reference to the hash storing all of the arguments; in an
1041 array context, it returns the hash itself. When passed a single
1042 argument, it returns the value stored in the args hash for that
1043 option key. When called with two arguments, the second argument is
1044 assigned to the args hash under the key passed as the first
1045 argument.
1046 autosplit_file($from, $to)
1048 [version 0.28]
1049 Invokes the AutoSplit module on the $from file, sending the output
1051 to the "lib/auto" directory inside $to. $to is typically the
1052 "blib/" directory.
1053 base_dir()
1055 [version 0.14]
1056 Returns a string containing the root-level directory of this build,
1058 i.e. where the "Build.PL" script and the "lib" directory can be
1059 found. This is usually the same as the current working directory,
1060 because the "Build" script will "chdir()" into this directory as
1061 soon as it begins execution.
1062 build_requires()
1064 [version 0.21]
1065 Returns a hash reference indicating the "build_requires"
1067 prerequisites that were passed to the "new()" method.
1068 can_action( $action )
1070 Returns a reference to the method that defines $action, or false
1071 otherwise. This is handy for actions defined (or maybe not!) in
1072 subclasses.
1073 [version 0.32_xx]
1075 cbuilder()
1077 [version 0.2809]
1078 Returns the internal ExtUtils::CBuilder object that can be used for
1080 compiling & linking C code. If no such object is available (e.g.
1081 if the system has no compiler installed) an exception will be
1082 thrown.
1083 check_installed_status($module, $version)
1085 [version 0.11]
1086 This method returns a hash reference indicating whether a version
1088 dependency on a certain module is satisfied. The $module argument
1089 is given as a string like "Data::Dumper" or "perl", and the
1090 $version argument can take any of the forms described in "requires"
1091 above. This allows very fine-grained version checking.
1092 The returned hash reference has the following structure:
1094 {
1096 ok => $whether_the_dependency_is_satisfied,
1097 have => $version_already_installed,
1098 need => $version_requested, # Same as incoming $version argument
1099 message => $informative_error_message,
1100 }
1101 If no version of $module is currently installed, the "have" value
1103 will be the string "<none>". Otherwise the "have" value will
1104 simply be the version of the installed module. Note that this
1105 means that if $module is installed but doesn't define a version
1106 number, the "have" value will be "undef" - this is why we don't use
1107 "undef" for the case when $module isn't installed at all.
1108 This method may be called either as an object method
1110 ("$build->check_installed_status($module, $version)") or as a class
1111 method ("Module::Build->check_installed_status($module,
1112 $version)").
1113 check_installed_version($module, $version)
1115 [version 0.05]
1116 Like check_installed_status(), but simply returns true or false
1118 depending on whether module $module satisfies the dependency
1119 $version.
1120 If the check succeeds, the return value is the actual version of
1122 $module installed on the system. This allows you to do the
1123 following:
1124 my $installed = $build->check_installed_version('DBI', '1.15');
1126 if ($installed) {
1127 print "Congratulations, version $installed of DBI is installed.\n";
1128 } else {
1129 die "Sorry, you must install DBI.\n";
1130 }
1131 If the check fails, we return false and set $@ to an informative
1133 error message.
1134 If $version is any non-true value (notably zero) and any version of
1136 $module is installed, we return true. In this case, if $module
1137 doesn't define a version, or if its version is zero, we return the
1138 special value "0 but true", which is numerically zero, but
1139 logically true.
1140 In general you might prefer to use "check_installed_status" if you
1142 need detailed information, or this method if you just need a yes/no
1143 answer.
1144 compare_versions($v1, $op, $v2)
1146 [version 0.28]
1147 Compares two module versions $v1 and $v2 using the operator $op,
1149 which should be one of Perl's numeric operators like "!=" or ">="
1150 or the like. We do at least a halfway-decent job of handling
1151 versions that aren't strictly numeric, like "0.27_02", but exotic
1152 stuff will likely cause problems.
1153 In the future, the guts of this method might be replaced with a
1155 call out to "version.pm".
1156 config($key)
1158 config($key, $value)
1159 config() [deprecated]
1160 [version 0.22]
1161 With a single argument $key, returns the value associated with that
1163 key in the "Config.pm" hash, including any changes the author or
1164 user has specified.
1165 With $key and $value arguments, sets the value for future callers
1167 of "config($key)".
1168 With no arguments, returns a hash reference containing all such
1170 key-value pairs. This usage is deprecated, though, because it's a
1171 resource hog and violates encapsulation.
1172 config_data($name)
1174 config_data($name => $value)
1175 [version 0.26]
1176 With a single argument, returns the value of the configuration
1178 variable $name. With two arguments, sets the given configuration
1179 variable to the given value. The value may be any Perl scalar
1180 that's serializable with "Data::Dumper". For instance, if you
1181 write a module that can use a MySQL or PostgreSQL back-end, you
1182 might create configuration variables called "mysql_connect" and
1183 "postgres_connect", and set each to an array of connection
1184 parameters for "DBI->connect()".
1185 Configuration values set in this way using the Module::Build object
1187 will be available for querying during the build/test process and
1188 after installation via the generated "...::ConfigData" module, as
1189 "...::ConfigData->config($name)".
1190 The feature() and "config_data()" methods represent Module::Build's
1192 main support for configuration of installed modules. See also
1193 "SAVING CONFIGURATION INFORMATION" in Module::Build::Authoring.
1194 conflicts()
1196 [version 0.21]
1197 Returns a hash reference indicating the "conflicts" prerequisites
1199 that were passed to the "new()" method.
1200 contains_pod($file) [deprecated]
1202 [version 0.20]
1203 [Deprecated] Please see Module::Metadata instead.
1205 Returns true if the given file appears to contain POD
1207 documentation. Currently this checks whether the file has a line
1208 beginning with '=pod', '=head', or '=item', but the exact semantics
1209 may change in the future.
1210 copy_if_modified(%parameters)
1212 [version 0.19]
1213 Takes the file in the "from" parameter and copies it to the file in
1215 the "to" parameter, or the directory in the "to_dir" parameter, if
1216 the file has changed since it was last copied (or if it doesn't
1217 exist in the new location). By default the entire directory
1218 structure of "from" will be copied into "to_dir"; an optional
1219 "flatten" parameter will copy into "to_dir" without doing so.
1220 Returns the path to the destination file, or "undef" if nothing
1222 needed to be copied.
1223 Any directories that need to be created in order to perform the
1225 copying will be automatically created.
1226 The destination file is set to read-only. If the source file has
1228 the executable bit set, then the destination file will be made
1229 executable.
1230 create_build_script()
1232 [version 0.05]
1233 Creates an executable script called "Build" in the current
1235 directory that will be used to execute further user actions. This
1236 script is roughly analogous (in function, not in form) to the
1237 Makefile created by "ExtUtils::MakeMaker". This method also
1238 creates some temporary data in a directory called "_build/". Both
1239 of these will be removed when the "realclean" action is performed.
1240 Among the files created in "_build/" is a _build/prereqs file
1242 containing the set of prerequisites for this distribution, as a
1243 hash of hashes. This file may be "eval()"-ed to obtain the
1244 authoritative set of prerequisites, which might be different from
1245 the contents of META.yml (because Build.PL might have set them
1246 dynamically). But fancy developers take heed: do not put any fancy
1247 custom runtime code in the _build/prereqs file, leave it as a
1248 static declaration containing only strings and numbers. Similarly,
1249 do not alter the structure of the internal
1250 "$self->{properties}{requires}" (etc.) data members, because
1251 that's where this data comes from.
1252 current_action()
1254 [version 0.28]
1255 Returns the name of the currently-running action, such as "build"
1257 or "test". This action is not necessarily the action that was
1258 originally invoked by the user. For example, if the user invoked
1259 the "test" action, current_action() would initially return "test".
1260 However, action "test" depends on action "code", so
1261 current_action() will return "code" while that dependency is being
1262 executed. Once that action has completed, current_action() will
1263 again return "test".
1264 If you need to know the name of the original action invoked by the
1266 user, see "invoked_action()" below.
1267 depends_on(@actions)
1269 [version 0.28]
1270 Invokes the named action or list of actions in sequence. Using
1272 this method is preferred to calling the action explicitly because
1273 it performs some internal record-keeping, and it ensures that the
1274 same action is not invoked multiple times (note: in future versions
1275 of Module::Build it's conceivable that this run-only-once mechanism
1276 will be changed to something more intelligent).
1277 Note that the name of this method is something of a misnomer; it
1279 should really be called something like
1280 "invoke_actions_unless_already_invoked()" or something, but for
1281 better or worse (perhaps better!) we were still thinking in
1282 "make"-like dependency terms when we created this method.
1283 See also dispatch(). The main distinction between the two is that
1285 "depends_on()" is meant to call an action from inside another
1286 action, whereas "dispatch()" is meant to set the very top action in
1287 motion.
1288 dir_contains($first_dir, $second_dir)
1290 [version 0.28]
1291 Returns true if the first directory logically contains the second
1293 directory. This is just a convenience function because
1294 "File::Spec" doesn't really provide an easy way to figure this out
1295 (but "Path::Class" does...).
1296 dispatch($action, %args)
1298 [version 0.03]
1299 Invokes the build action $action. Optionally, a list of options
1301 and their values can be passed in. This is equivalent to invoking
1302 an action at the command line, passing in a list of options.
1303 Custom options that have not been registered must be passed in as a
1305 hash reference in a key named "args":
1306 $build->dispatch('foo', verbose => 1, args => { my_option => 'value' });
1308 This method is intended to be used to programmatically invoke build
1310 actions, e.g. by applications controlling Module::Build-based
1311 builds rather than by subclasses.
1312 See also depends_on(). The main distinction between the two is
1314 that "depends_on()" is meant to call an action from inside another
1315 action, whereas "dispatch()" is meant to set the very top action in
1316 motion.
1317 dist_dir()
1319 [version 0.28]
1320 Returns the name of the directory that will be created during the
1322 "dist" action. The name is derived from the "dist_name" and
1323 "dist_version" properties.
1324 dist_name()
1326 [version 0.21]
1327 Returns the name of the current distribution, as passed to the
1329 "new()" method in a "dist_name" or modified "module_name"
1330 parameter.
1331 dist_version()
1333 [version 0.21]
1334 Returns the version of the current distribution, as determined by
1336 the "new()" method from a "dist_version", "dist_version_from", or
1337 "module_name" parameter.
1338 do_system($cmd, @args)
1340 [version 0.21]
1341 This is a fairly simple wrapper around Perl's "system()" built-in
1343 command. Given a command and an array of optional arguments, this
1344 method will print the command to "STDOUT", and then execute it
1345 using Perl's "system()". It returns true or false to indicate
1346 success or failure (the opposite of how "system()" works, but more
1347 intuitive).
1348 Note that if you supply a single argument to "do_system()", it
1350 will/may be processed by the system's shell, and any special
1351 characters will do their special things. If you supply multiple
1352 arguments, no shell will get involved and the command will be
1353 executed directly.
1354 extra_compiler_flags()
1356 extra_compiler_flags(@flags)
1357 [version 0.25]
1358 Set or retrieve the extra compiler flags. Returns an arrayref of
1360 flags.
1361 extra_linker_flags()
1363 extra_linker_flags(@flags)
1364 [version 0.25]
1365 Set or retrieve the extra linker flags. Returns an arrayref of
1367 flags.
1368 feature($name)
1370 feature($name => $value)
1371 [version 0.26]
1372 With a single argument, returns true if the given feature is set.
1374 With two arguments, sets the given feature to the given boolean
1375 value. In this context, a "feature" is any optional functionality
1376 of an installed module. For instance, if you write a module that
1377 could optionally support a MySQL or PostgreSQL backend, you might
1378 create features called "mysql_support" and "postgres_support", and
1379 set them to true/false depending on whether the user has the proper
1380 databases installed and configured.
1381 Features set in this way using the Module::Build object will be
1383 available for querying during the build/test process and after
1384 installation via the generated "...::ConfigData" module, as
1385 "...::ConfigData->feature($name)".
1386 The "feature()" and "config_data()" methods represent
1388 Module::Build's main support for configuration of installed
1389 modules. See also "SAVING CONFIGURATION INFORMATION" in
1390 Module::Build::Authoring.
1391 fix_shebang_line(@files)
1393 [version 0.??]
1394 Modify any "shebang" line in the specified files to use the path to
1396 the perl executable being used for the current build. Files are
1397 modified in-place. The existing shebang line must have a command
1398 that contains ""perl""; arguments to the command do not count. In
1399 particular, this means that the use of "#!/usr/bin/env perl" will
1400 not be changed.
1401 For an explanation of shebang lines, see
1403 <http://en.wikipedia.org/wiki/Shebang_%28Unix%29>.
1404 have_c_compiler()
1406 [version 0.21]
1407 Returns true if the current system seems to have a working C
1409 compiler. We currently determine this by attempting to compile a
1410 simple C source file and reporting whether the attempt was
1411 successful.
1412 install_base_relpaths()
1414 install_base_relpaths($type)
1415 install_base_relpaths($type => $path)
1416 [version 0.28]
1417 Set or retrieve the relative paths that are appended to
1419 "install_base" for any installable element. This is useful if you
1420 want to set the relative install path for custom build elements.
1421 With no argument, it returns a reference to a hash containing all
1423 elements and their respective values. This hash should not be
1424 modified directly; use the multiple argument below form to change
1425 values.
1426 The single argument form returns the value associated with the
1428 element $type.
1429 The multiple argument form allows you to set the paths for element
1431 types. $value must be a relative path using Unix-like paths. (A
1432 series of directories separated by slashes, e.g. "foo/bar".) The
1433 return value is a localized path based on $value.
1434 Assigning the value "undef" to an element causes it to be removed.
1436 install_destination($type)
1438 [version 0.28]
1439 Returns the directory in which items of type $type (e.g. "lib",
1441 "arch", "bin", or anything else returned by the "install_types()"
1442 method) will be installed during the "install" action. Any
1443 settings for "install_path", "install_base", and "prefix" are taken
1444 into account when determining the return value.
1445 install_path()
1447 install_path($type)
1448 install_path($type => $path)
1449 [version 0.28]
1450 Set or retrieve paths for specific installable elements. This is
1452 useful when you want to examine any explicit install paths
1453 specified by the user on the command line, or if you want to set
1454 the install path for a specific installable element based on
1455 another attribute like "install_base()".
1456 With no argument, it returns a reference to a hash containing all
1458 elements and their respective values. This hash should not be
1459 modified directly; use the multiple argument below form to change
1460 values.
1461 The single argument form returns the value associated with the
1463 element $type.
1464 The multiple argument form allows you to set the paths for element
1466 types. The supplied $path should be an absolute path to install
1467 elements of $type. The return value is $path.
1468 Assigning the value "undef" to an element causes it to be removed.
1470 install_types()
1472 [version 0.28]
1473 Returns a list of installable types that this build knows about.
1475 These types each correspond to the name of a directory in blib/,
1476 and the list usually includes items such as "lib", "arch", "bin",
1477 "script", "libdoc", "bindoc", and if HTML documentation is to be
1478 built, "libhtml" and "binhtml". Other user-defined types may also
1479 exist.
1480 invoked_action()
1482 [version 0.28]
1483 This is the name of the original action invoked by the user. This
1485 value is set when the user invokes Build.PL, the Build script, or
1486 programmatically through the dispatch() method. It does not change
1487 as sub-actions are executed as dependencies are evaluated.
1488 To get the name of the currently executing dependency, see
1490 "current_action()" above.
1491 notes()
1493 notes($key)
1494 notes($key => $value)
1495 [version 0.20]
1496 The "notes()" value allows you to store your own persistent
1498 information about the build, and to share that information among
1499 different entities involved in the build. See the example in the
1500 "current()" method.
1501 The "notes()" method is essentially a glorified hash access. With
1503 no arguments, "notes()" returns the entire hash of notes. With one
1504 argument, "notes($key)" returns the value associated with the given
1505 key. With two arguments, "notes($key, $value)" sets the value
1506 associated with the given key to $value and returns the new value.
1507 The lifetime of the "notes" data is for "a build" - that is, the
1509 "notes" hash is created when "perl Build.PL" is run (or when the
1510 "new()" method is run, if the Module::Build Perl API is being used
1511 instead of called from a shell), and lasts until "perl Build.PL" is
1512 run again or the "clean" action is run.
1513 orig_dir()
1515 [version 0.28]
1516 Returns a string containing the working directory that was in
1518 effect before the Build script chdir()-ed into the "base_dir".
1519 This might be useful for writing wrapper tools that might need to
1520 chdir() back out.
1521 os_type()
1523 [version 0.04]
1524 If you're subclassing Module::Build and some code needs to alter
1526 its behavior based on the current platform, you may only need to
1527 know whether you're running on Windows, Unix, MacOS, VMS, etc., and
1528 not the fine-grained value of Perl's $^O variable. The "os_type()"
1529 method will return a string like "Windows", "Unix", "MacOS", "VMS",
1530 or whatever is appropriate. If you're running on an unknown
1531 platform, it will return "undef" - there shouldn't be many unknown
1532 platforms though.
1533 is_vmsish()
1535 is_windowsish()
1536 is_unixish()
1537 Convenience functions that return a boolean value indicating
1538 whether this platform behaves respectively like VMS, Windows, or
1539 Unix. For arbitrary reasons other platforms don't get their own
1540 such functions, at least not yet.
1541 prefix_relpaths()
1543 prefix_relpaths($installdirs)
1544 prefix_relpaths($installdirs, $type)
1545 prefix_relpaths($installdirs, $type => $path)
1546 [version 0.28]
1547 Set or retrieve the relative paths that are appended to "prefix"
1549 for any installable element. This is useful if you want to set the
1550 relative install path for custom build elements.
1551 With no argument, it returns a reference to a hash containing all
1553 elements and their respective values as defined by the current
1554 "installdirs" setting.
1555 With a single argument, it returns a reference to a hash containing
1557 all elements and their respective values as defined by
1558 $installdirs.
1559 The hash returned by the above calls should not be modified
1561 directly; use the three-argument below form to change values.
1562 The two argument form returns the value associated with the element
1564 $type.
1565 The multiple argument form allows you to set the paths for element
1567 types. $value must be a relative path using Unix-like paths. (A
1568 series of directories separated by slashes, e.g. "foo/bar".) The
1569 return value is a localized path based on $value.
1570 Assigning the value "undef" to an element causes it to be removed.
1572 get_metadata()
1574 [version 0.36]
1575 This method returns a hash reference of metadata that can be used
1577 to create a YAML datastream. It is provided for authors to override
1578 or customize the fields of META.yml. E.g.
1579 package My::Builder;
1581 use base 'Module::Build';
1582 sub get_metadata {
1584 my $self, @args = @_;
1585 my $data = $self->SUPER::get_metadata(@args);
1586 $data->{custom_field} = 'foo';
1587 return $data;
1588 }
1589 Valid arguments include:
1591 · "fatal" -- indicates whether missing required metadata fields
1593 should be a fatal error or not. For META creation, it
1594 generally should, but for MYMETA creation for end-users, it
1595 should not be fatal.
1596 · "auto" -- indicates whether any necessary configure_requires
1598 should be automatically added. This is used in META creation.
1599 This method is a wrapper around the old prepare_metadata API now
1601 that we no longer use YAML::Node to hold metadata.
1602 prepare_metadata() [deprecated]
1604 [version 0.36]
1605 [Deprecated] As of 0.36, authors should use "get_metadata" instead.
1607 This method is preserved for backwards compatibility only.
1608 It takes three positional arguments: a hashref (to which metadata
1610 will be added), an optional arrayref (to which metadata keys will
1611 be added in order if the arrayref exists), and a hashref of
1612 arguments (as provided to get_metadata). The latter argument is
1613 new as of 0.36. Earlier versions are always fatal on errors.
1614 Prior to version 0.36, this method took a YAML::Node as an argument
1616 to hold assembled metadata.
1617 prereq_failures()
1619 [version 0.11]
1620 Returns a data structure containing information about any failed
1622 prerequisites (of any of the types described above), or "undef" if
1623 all prerequisites are met.
1624 The data structure returned is a hash reference. The top level
1626 keys are the type of prerequisite failed, one of "requires",
1627 "build_requires", "conflicts", or "recommends". The associated
1628 values are hash references whose keys are the names of required (or
1629 conflicting) modules. The associated values of those are hash
1630 references indicating some information about the failure. For
1631 example:
1632 {
1634 have => '0.42',
1635 need => '0.59',
1636 message => 'Version 0.42 is installed, but we need version 0.59',
1637 }
1638 or
1640 {
1642 have => '<none>',
1643 need => '0.59',
1644 message => 'Prerequisite Foo isn't installed',
1645 }
1646 This hash has the same structure as the hash returned by the
1648 "check_installed_status()" method, except that in the case of
1649 "conflicts" dependencies we change the "need" key to "conflicts"
1650 and construct a proper message.
1651 Examples:
1653 # Check a required dependency on Foo::Bar
1655 if ( $build->prereq_failures->{requires}{Foo::Bar} ) { ...
1656 # Check whether there were any failures
1658 if ( $build->prereq_failures ) { ...
1659 # Show messages for all failures
1661 my $failures = $build->prereq_failures;
1662 while (my ($type, $list) = each %$failures) {
1663 while (my ($name, $hash) = each %$list) {
1664 print "Failure for $name: $hash->{message}\n";
1665 }
1666 }
1667 prereq_data()
1669 [version 0.32]
1670 Returns a reference to a hash describing all prerequisites. The
1672 keys of the hash will be the various prerequisite types
1673 ('requires', 'build_requires', 'test_requires',
1674 'configure_requires', 'recommends', or 'conflicts') and the values
1675 will be references to hashes of module names and version numbers.
1676 Only prerequisites types that are defined will be included. The
1677 "prereq_data" action is just a thin wrapper around the
1678 "prereq_data()" method and dumps the hash as a string that can be
1679 loaded using "eval()".
1680 prereq_report()
1682 [version 0.28]
1683 Returns a human-readable (table-form) string showing all
1685 prerequisites, the versions required, and the versions actually
1686 installed. This can be useful for reviewing the configuration of
1687 your system prior to a build, or when compiling data to send for a
1688 bug report. The "prereq_report" action is just a thin wrapper
1689 around the "prereq_report()" method.
1690 prompt($message, $default)
1692 [version 0.12]
1693 Asks the user a question and returns their response as a string.
1695 The first argument specifies the message to display to the user
1696 (for example, "Where do you keep your money?"). The second
1697 argument, which is optional, specifies a default answer (for
1698 example, "wallet"). The user will be asked the question once.
1699 If "prompt()" detects that it is not running interactively and
1701 there is nothing on STDIN or if the PERL_MM_USE_DEFAULT environment
1702 variable is set to true, the $default will be used without
1703 prompting.
1704 To prevent automated processes from blocking, the user must either
1706 set PERL_MM_USE_DEFAULT or attach something to STDIN (this can be a
1707 pipe/file containing a scripted set of answers or /dev/null.)
1708 If no $default is provided an empty string will be used instead.
1710 In non-interactive mode, the absence of $default is an error
1711 (though explicitly passing "undef()" as the default is valid as of
1712 0.27.)
1713 This method may be called as a class or object method.
1715 recommends()
1717 [version 0.21]
1718 Returns a hash reference indicating the "recommends" prerequisites
1720 that were passed to the "new()" method.
1721 requires()
1723 [version 0.21]
1724 Returns a hash reference indicating the "requires" prerequisites
1726 that were passed to the "new()" method.
1727 rscan_dir($dir, $pattern)
1729 [version 0.28]
1730 Uses "File::Find" to traverse the directory $dir, returning a
1732 reference to an array of entries matching $pattern. $pattern may
1733 either be a regular expression (using "qr//" or just a plain
1734 string), or a reference to a subroutine that will return true for
1735 wanted entries. If $pattern is not given, all entries will be
1736 returned.
1737 Examples:
1739 # All the *.pm files in lib/
1741 $m->rscan_dir('lib', qr/\.pm$/)
1742 # All the files in blib/ that aren't *.html files
1744 $m->rscan_dir('blib', sub {-f $_ and not /\.html$/});
1745 # All the files in t/
1747 $m->rscan_dir('t');
1748 runtime_params()
1750 runtime_params($key)
1751 [version 0.28]
1752 The "runtime_params()" method stores the values passed on the
1754 command line for valid properties (that is, any command line
1755 options for which "valid_property()" returns a true value). The
1756 value on the command line may override the default value for a
1757 property, as well as any value specified in a call to "new()".
1758 This allows you to programmatically tell if "perl Build.PL" or any
1759 execution of "./Build" had command line options specified that
1760 override valid properties.
1761 The "runtime_params()" method is essentially a glorified read-only
1763 hash. With no arguments, "runtime_params()" returns the entire
1764 hash of properties specified on the command line. With one
1765 argument, "runtime_params($key)" returns the value associated with
1766 the given key.
1767 The lifetime of the "runtime_params" data is for "a build" - that
1769 is, the "runtime_params" hash is created when "perl Build.PL" is
1770 run (or when the "new()" method is called, if the Module::Build
1771 Perl API is being used instead of called from a shell), and lasts
1772 until "perl Build.PL" is run again or the "clean" action is run.
1773 script_files()
1775 [version 0.18]
1776 Returns a hash reference whose keys are the perl script files to be
1778 installed, if any. This corresponds to the "script_files"
1779 parameter to the "new()" method. With an optional argument, this
1780 parameter may be set dynamically.
1781 For backward compatibility, the "scripts()" method does exactly the
1783 same thing as "script_files()". "scripts()" is deprecated, but it
1784 will stay around for several versions to give people time to
1785 transition.
1786 up_to_date($source_file, $derived_file)
1788 up_to_date(\@source_files, \@derived_files)
1789 [version 0.20]
1790 This method can be used to compare a set of source files to a set
1792 of derived files. If any of the source files are newer than any of
1793 the derived files, it returns false. Additionally, if any of the
1794 derived files do not exist, it returns false. Otherwise it returns
1795 true.
1796 The arguments may be either a scalar or an array reference of file
1798 names.
1799 y_n($message, $default)
1801 [version 0.12]
1802 Asks the user a yes/no question using "prompt()" and returns true
1804 or false accordingly. The user will be asked the question
1805 repeatedly until they give an answer that looks like "yes" or "no".
1806 The first argument specifies the message to display to the user
1808 (for example, "Shall I invest your money for you?"), and the second
1809 argument specifies the default answer (for example, "y").
1810 Note that the default is specified as a string like "y" or "n", and
1812 the return value is a Perl boolean value like 1 or 0. I thought
1813 about this for a while and this seemed like the most useful way to
1814 do it.
1815 This method may be called as a class or object method.
1817 Autogenerated Accessors
1819 In addition to the aforementioned methods, there are also some get/set
1820 accessor methods for the following properties:
1821 PL_files()
1823 allow_mb_mismatch()
1824 allow_pureperl()
1825 auto_configure_requires()
1826 autosplit()
1827 base_dir()
1828 bindoc_dirs()
1829 blib()
1830 build_bat()
1831 build_class()
1832 build_elements()
1833 build_requires()
1834 build_script()
1835 bundle_inc()
1836 bundle_inc_preload()
1837 c_source()
1838 config_dir()
1839 configure_requires()
1840 conflicts()
1841 cover()
1842 cpan_client()
1843 create_license()
1844 create_makefile_pl()
1845 create_packlist()
1846 create_readme()
1847 debug()
1848 debugger()
1849 destdir()
1850 dynamic_config()
1851 extra_manify_args()
1852 get_options()
1853 html_css()
1854 include_dirs()
1855 install_base()
1856 installdirs()
1857 libdoc_dirs()
1858 license()
1859 magic_number()
1860 mb_version()
1861 meta_add()
1862 meta_merge()
1863 metafile()
1864 metafile2()
1865 module_name()
1866 mymetafile()
1867 mymetafile2()
1868 needs_compiler()
1869 orig_dir()
1870 perl()
1871 pm_files()
1872 pod_files()
1873 pollute()
1874 prefix()
1875 prereq_action_types()
1876 program_name()
1877 pureperl_only()
1878 quiet()
1879 recommends()
1880 recurse_into()
1881 recursive_test_files()
1882 requires()
1883 scripts()
1884 sign()
1885 tap_harness_args()
1886 test_file_exts()
1887 test_requires()
1888 use_rcfile()
1889 use_tap_harness()
1890 verbose()
1891 xs_files()
1892
1894 If you would like to add other useful metadata, "Module::Build"
1895 supports this with the "meta_add" and "meta_merge" arguments to
1896 "new()". The authoritative list of supported metadata can be found at
1897 CPAN::Meta::Spec but for convenience - here are a few of the more
1898 useful ones:
1899 keywords
1901 For describing the distribution using keyword (or "tags") in order
1902 to make CPAN.org indexing and search more efficient and useful.
1903 resources
1905 A list of additional resources available for users of the
1906 distribution. This can include links to a homepage on the web, a
1907 bug tracker, the repository location, and even a subscription page
1908 for the distribution mailing list.
1909
1911 Ken Williams <kwilliams@cpan.org>
1912
1914 Copyright (c) 2001-2006 Ken Williams. All rights reserved.
1915 This library is free software; you can redistribute it and/or modify it
1917 under the same terms as Perl itself.
1918
1920 perl(1), Module::Build(3), Module::Build::Authoring(3),
1921 Module::Build::Cookbook(3), ExtUtils::MakeMaker(3)
1922 META.yml Specification: CPAN::Meta::Spec
1924perl v5.32.0 2020-07-28 Module::Build::API(3)