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 be
38 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() will
44 NOT work correctly if you have changed out of the directory that
45 "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 files
863 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 runs
904 "perl Build.PL". Thereafter, when the user runs "Build test" or
905 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, specified
1015 in either Unix format or the current machine's native format. It's
1016 usually convenient to use Unix format when you hard-code the
1017 filenames (e.g. in Build.PL) and the native format when the names
1018 are programmatically generated (e.g. in a testing script).
1019 I decided to provide a dynamic method of the $build object, rather
1021 than just use a static list of files named in the Build.PL, because
1022 these static lists can get difficult to manage. I usually prefer
1023 to keep the responsibility for registering temporary files close to
1024 the code that creates them.
1025 args()
1027 [version 0.26]
1028 my $args_href = $build->args;
1030 my %args = $build->args;
1031 my $arg_value = $build->args($key);
1032 $build->args($key, $value);
1033 This method is the preferred interface for retrieving the arguments
1035 passed via command line options to Build.PL or Build, minus the
1036 Module-Build specific options.
1037 When called in a scalar context with no arguments, this method
1039 returns a reference to the hash storing all of the arguments; in an
1040 array context, it returns the hash itself. When passed a single
1041 argument, it returns the value stored in the args hash for that
1042 option key. When called with two arguments, the second argument is
1043 assigned to the args hash under the key passed as the first
1044 argument.
1045 autosplit_file($from, $to)
1047 [version 0.28]
1048 Invokes the AutoSplit module on the $from file, sending the output
1050 to the "lib/auto" directory inside $to. $to is typically the
1051 "blib/" directory.
1052 base_dir()
1054 [version 0.14]
1055 Returns a string containing the root-level directory of this build,
1057 i.e. where the "Build.PL" script and the "lib" directory can be
1058 found. This is usually the same as the current working directory,
1059 because the "Build" script will chdir() into this directory as soon
1060 as it begins execution.
1061 build_requires()
1063 [version 0.21]
1064 Returns a hash reference indicating the "build_requires"
1066 prerequisites that were passed to the new() method.
1067 can_action( $action )
1069 Returns a reference to the method that defines $action, or false
1070 otherwise. This is handy for actions defined (or maybe not!) in
1071 subclasses.
1072 [version 0.32_xx]
1074 cbuilder()
1076 [version 0.2809]
1077 Returns the internal ExtUtils::CBuilder object that can be used for
1079 compiling & linking C code. If no such object is available (e.g.
1080 if the system has no compiler installed) an exception will be
1081 thrown.
1082 check_installed_status($module, $version)
1084 [version 0.11]
1085 This method returns a hash reference indicating whether a version
1087 dependency on a certain module is satisfied. The $module argument
1088 is given as a string like "Data::Dumper" or "perl", and the
1089 $version argument can take any of the forms described in "requires"
1090 above. This allows very fine-grained version checking.
1091 The returned hash reference has the following structure:
1093 {
1095 ok => $whether_the_dependency_is_satisfied,
1096 have => $version_already_installed,
1097 need => $version_requested, # Same as incoming $version argument
1098 message => $informative_error_message,
1099 }
1100 If no version of $module is currently installed, the "have" value
1102 will be the string "<none>". Otherwise the "have" value will
1103 simply be the version of the installed module. Note that this
1104 means that if $module is installed but doesn't define a version
1105 number, the "have" value will be "undef" - this is why we don't use
1106 "undef" for the case when $module isn't installed at all.
1107 This method may be called either as an object method
1109 ("$build->check_installed_status($module, $version)") or as a class
1110 method ("Module::Build->check_installed_status($module,
1111 $version)").
1112 check_installed_version($module, $version)
1114 [version 0.05]
1115 Like check_installed_status(), but simply returns true or false
1117 depending on whether module $module satisfies the dependency
1118 $version.
1119 If the check succeeds, the return value is the actual version of
1121 $module installed on the system. This allows you to do the
1122 following:
1123 my $installed = $build->check_installed_version('DBI', '1.15');
1125 if ($installed) {
1126 print "Congratulations, version $installed of DBI is installed.\n";
1127 } else {
1128 die "Sorry, you must install DBI.\n";
1129 }
1130 If the check fails, we return false and set $@ to an informative
1132 error message.
1133 If $version is any non-true value (notably zero) and any version of
1135 $module is installed, we return true. In this case, if $module
1136 doesn't define a version, or if its version is zero, we return the
1137 special value "0 but true", which is numerically zero, but
1138 logically true.
1139 In general you might prefer to use "check_installed_status" if you
1141 need detailed information, or this method if you just need a yes/no
1142 answer.
1143 compare_versions($v1, $op, $v2)
1145 [version 0.28]
1146 Compares two module versions $v1 and $v2 using the operator $op,
1148 which should be one of Perl's numeric operators like "!=" or ">="
1149 or the like. We do at least a halfway-decent job of handling
1150 versions that aren't strictly numeric, like "0.27_02", but exotic
1151 stuff will likely cause problems.
1152 In the future, the guts of this method might be replaced with a
1154 call out to "version.pm".
1155 config($key)
1157 config($key, $value)
1158 config() [deprecated]
1159 [version 0.22]
1160 With a single argument $key, returns the value associated with that
1162 key in the "Config.pm" hash, including any changes the author or
1163 user has specified.
1164 With $key and $value arguments, sets the value for future callers
1166 of config($key).
1167 With no arguments, returns a hash reference containing all such
1169 key-value pairs. This usage is deprecated, though, because it's a
1170 resource hog and violates encapsulation.
1171 config_data($name)
1173 config_data($name => $value)
1174 [version 0.26]
1175 With a single argument, returns the value of the configuration
1177 variable $name. With two arguments, sets the given configuration
1178 variable to the given value. The value may be any Perl scalar
1179 that's serializable with "Data::Dumper". For instance, if you
1180 write a module that can use a MySQL or PostgreSQL back-end, you
1181 might create configuration variables called "mysql_connect" and
1182 "postgres_connect", and set each to an array of connection
1183 parameters for "DBI->connect()".
1184 Configuration values set in this way using the Module::Build object
1186 will be available for querying during the build/test process and
1187 after installation via the generated "...::ConfigData" module, as
1188 "...::ConfigData->config($name)".
1189 The feature() and config_data() methods represent Module::Build's
1191 main support for configuration of installed modules. See also
1192 "SAVING CONFIGURATION INFORMATION" in Module::Build::Authoring.
1193 conflicts()
1195 [version 0.21]
1196 Returns a hash reference indicating the "conflicts" prerequisites
1198 that were passed to the new() method.
1199 contains_pod($file) [deprecated]
1201 [version 0.20]
1202 [Deprecated] Please see Module::Metadata instead.
1204 Returns true if the given file appears to contain POD
1206 documentation. Currently this checks whether the file has a line
1207 beginning with '=pod', '=head', or '=item', but the exact semantics
1208 may change in the future.
1209 copy_if_modified(%parameters)
1211 [version 0.19]
1212 Takes the file in the "from" parameter and copies it to the file in
1214 the "to" parameter, or the directory in the "to_dir" parameter, if
1215 the file has changed since it was last copied (or if it doesn't
1216 exist in the new location). By default the entire directory
1217 structure of "from" will be copied into "to_dir"; an optional
1218 "flatten" parameter will copy into "to_dir" without doing so.
1219 Returns the path to the destination file, or "undef" if nothing
1221 needed to be copied.
1222 Any directories that need to be created in order to perform the
1224 copying will be automatically created.
1225 The destination file is set to read-only. If the source file has
1227 the executable bit set, then the destination file will be made
1228 executable.
1229 create_build_script()
1231 [version 0.05]
1232 Creates an executable script called "Build" in the current
1234 directory that will be used to execute further user actions. This
1235 script is roughly analogous (in function, not in form) to the
1236 Makefile created by "ExtUtils::MakeMaker". This method also
1237 creates some temporary data in a directory called "_build/". Both
1238 of these will be removed when the "realclean" action is performed.
1239 Among the files created in "_build/" is a _build/prereqs file
1241 containing the set of prerequisites for this distribution, as a
1242 hash of hashes. This file may be eval()-ed to obtain the
1243 authoritative set of prerequisites, which might be different from
1244 the contents of META.yml (because Build.PL might have set them
1245 dynamically). But fancy developers take heed: do not put any fancy
1246 custom runtime code in the _build/prereqs file, leave it as a
1247 static declaration containing only strings and numbers. Similarly,
1248 do not alter the structure of the internal
1249 "$self->{properties}{requires}" (etc.) data members, because
1250 that's where this data comes from.
1251 current_action()
1253 [version 0.28]
1254 Returns the name of the currently-running action, such as "build"
1256 or "test". This action is not necessarily the action that was
1257 originally invoked by the user. For example, if the user invoked
1258 the "test" action, current_action() would initially return "test".
1259 However, action "test" depends on action "code", so
1260 current_action() will return "code" while that dependency is being
1261 executed. Once that action has completed, current_action() will
1262 again return "test".
1263 If you need to know the name of the original action invoked by the
1265 user, see "invoked_action()" below.
1266 depends_on(@actions)
1268 [version 0.28]
1269 Invokes the named action or list of actions in sequence. Using
1271 this method is preferred to calling the action explicitly because
1272 it performs some internal record-keeping, and it ensures that the
1273 same action is not invoked multiple times (note: in future versions
1274 of Module::Build it's conceivable that this run-only-once mechanism
1275 will be changed to something more intelligent).
1276 Note that the name of this method is something of a misnomer; it
1278 should really be called something like
1279 invoke_actions_unless_already_invoked() or something, but for
1280 better or worse (perhaps better!) we were still thinking in
1281 "make"-like dependency terms when we created this method.
1282 See also dispatch(). The main distinction between the two is that
1284 depends_on() is meant to call an action from inside another action,
1285 whereas dispatch() is meant to set the very top action in 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" parameter.
1328 dist_version()
1330 [version 0.21]
1331 Returns the version of the current distribution, as determined by
1333 the new() method from a "dist_version", "dist_version_from", or
1334 "module_name" parameter.
1335 do_system($cmd, @args)
1337 [version 0.21]
1338 This is a fairly simple wrapper around Perl's system() built-in
1340 command. Given a command and an array of optional arguments, this
1341 method will print the command to "STDOUT", and then execute it
1342 using Perl's system(). It returns true or false to indicate
1343 success or failure (the opposite of how system() works, but more
1344 intuitive).
1345 Note that if you supply a single argument to do_system(), it
1347 will/may be processed by the system's shell, and any special
1348 characters will do their special things. If you supply multiple
1349 arguments, no shell will get involved and the command will be
1350 executed directly.
1351 extra_compiler_flags()
1353 extra_compiler_flags(@flags)
1354 [version 0.25]
1355 Set or retrieve the extra compiler flags. Returns an arrayref of
1357 flags.
1358 extra_linker_flags()
1360 extra_linker_flags(@flags)
1361 [version 0.25]
1362 Set or retrieve the extra linker flags. Returns an arrayref of
1364 flags.
1365 feature($name)
1367 feature($name => $value)
1368 [version 0.26]
1369 With a single argument, returns true if the given feature is set.
1371 With two arguments, sets the given feature to the given boolean
1372 value. In this context, a "feature" is any optional functionality
1373 of an installed module. For instance, if you write a module that
1374 could optionally support a MySQL or PostgreSQL backend, you might
1375 create features called "mysql_support" and "postgres_support", and
1376 set them to true/false depending on whether the user has the proper
1377 databases installed and configured.
1378 Features set in this way using the Module::Build object will be
1380 available for querying during the build/test process and after
1381 installation via the generated "...::ConfigData" module, as
1382 "...::ConfigData->feature($name)".
1383 The feature() and config_data() methods represent Module::Build's
1385 main support for configuration of installed modules. See also
1386 "SAVING CONFIGURATION INFORMATION" in Module::Build::Authoring.
1387 fix_shebang_line(@files)
1389 [version 0.??]
1390 Modify any "shebang" line in the specified files to use the path to
1392 the perl executable being used for the current build. Files are
1393 modified in-place. The existing shebang line must have a command
1394 that contains ""perl""; arguments to the command do not count. In
1395 particular, this means that the use of "#!/usr/bin/env perl" will
1396 not be changed.
1397 For an explanation of shebang lines, see
1399 <http://en.wikipedia.org/wiki/Shebang_%28Unix%29>.
1400 have_c_compiler()
1402 [version 0.21]
1403 Returns true if the current system seems to have a working C
1405 compiler. We currently determine this by attempting to compile a
1406 simple C source file and reporting whether the attempt was
1407 successful.
1408 install_base_relpaths()
1410 install_base_relpaths($type)
1411 install_base_relpaths($type => $path)
1412 [version 0.28]
1413 Set or retrieve the relative paths that are appended to
1415 "install_base" for any installable element. This is useful if you
1416 want to set the relative install path for custom build elements.
1417 With no argument, it returns a reference to a hash containing all
1419 elements and their respective values. This hash should not be
1420 modified directly; use the multiple argument below form to change
1421 values.
1422 The single argument form returns the value associated with the
1424 element $type.
1425 The multiple argument form allows you to set the paths for element
1427 types. $value must be a relative path using Unix-like paths. (A
1428 series of directories separated by slashes, e.g. "foo/bar".) The
1429 return value is a localized path based on $value.
1430 Assigning the value "undef" to an element causes it to be removed.
1432 install_destination($type)
1434 [version 0.28]
1435 Returns the directory in which items of type $type (e.g. "lib",
1437 "arch", "bin", or anything else returned by the "install_types()"
1438 method) will be installed during the "install" action. Any
1439 settings for "install_path", "install_base", and "prefix" are taken
1440 into account when determining the return value.
1441 install_path()
1443 install_path($type)
1444 install_path($type => $path)
1445 [version 0.28]
1446 Set or retrieve paths for specific installable elements. This is
1448 useful when you want to examine any explicit install paths
1449 specified by the user on the command line, or if you want to set
1450 the install path for a specific installable element based on
1451 another attribute like install_base().
1452 With no argument, it returns a reference to a hash containing all
1454 elements and their respective values. This hash should not be
1455 modified directly; use the multiple argument below form to change
1456 values.
1457 The single argument form returns the value associated with the
1459 element $type.
1460 The multiple argument form allows you to set the paths for element
1462 types. The supplied $path should be an absolute path to install
1463 elements of $type. The return value is $path.
1464 Assigning the value "undef" to an element causes it to be removed.
1466 install_types()
1468 [version 0.28]
1469 Returns a list of installable types that this build knows about.
1471 These types each correspond to the name of a directory in blib/,
1472 and the list usually includes items such as "lib", "arch", "bin",
1473 "script", "libdoc", "bindoc", and if HTML documentation is to be
1474 built, "libhtml" and "binhtml". Other user-defined types may also
1475 exist.
1476 invoked_action()
1478 [version 0.28]
1479 This is the name of the original action invoked by the user. This
1481 value is set when the user invokes Build.PL, the Build script, or
1482 programmatically through the dispatch() method. It does not change
1483 as sub-actions are executed as dependencies are evaluated.
1484 To get the name of the currently executing dependency, see
1486 "current_action()" above.
1487 notes()
1489 notes($key)
1490 notes($key => $value)
1491 [version 0.20]
1492 The notes() value allows you to store your own persistent
1494 information about the build, and to share that information among
1495 different entities involved in the build. See the example in the
1496 current() method.
1497 The notes() method is essentially a glorified hash access. With no
1499 arguments, notes() returns the entire hash of notes. With one
1500 argument, notes($key) returns the value associated with the given
1501 key. With two arguments, "notes($key, $value)" sets the value
1502 associated with the given key to $value and returns the new value.
1503 The lifetime of the "notes" data is for "a build" - that is, the
1505 "notes" hash is created when "perl Build.PL" is run (or when the
1506 new() method is run, if the Module::Build Perl API is being used
1507 instead of called from a shell), and lasts until "perl Build.PL" is
1508 run again or the "clean" action is run.
1509 orig_dir()
1511 [version 0.28]
1512 Returns a string containing the working directory that was in
1514 effect before the Build script chdir()-ed into the "base_dir".
1515 This might be useful for writing wrapper tools that might need to
1516 chdir() back out.
1517 os_type()
1519 [version 0.04]
1520 If you're subclassing Module::Build and some code needs to alter
1522 its behavior based on the current platform, you may only need to
1523 know whether you're running on Windows, Unix, MacOS, VMS, etc., and
1524 not the fine-grained value of Perl's $^O variable. The os_type()
1525 method will return a string like "Windows", "Unix", "MacOS", "VMS",
1526 or whatever is appropriate. If you're running on an unknown
1527 platform, it will return "undef" - there shouldn't be many unknown
1528 platforms though.
1529 is_vmsish()
1531 is_windowsish()
1532 is_unixish()
1533 Convenience functions that return a boolean value indicating
1534 whether this platform behaves respectively like VMS, Windows, or
1535 Unix. For arbitrary reasons other platforms don't get their own
1536 such functions, at least not yet.
1537 prefix_relpaths()
1539 prefix_relpaths($installdirs)
1540 prefix_relpaths($installdirs, $type)
1541 prefix_relpaths($installdirs, $type => $path)
1542 [version 0.28]
1543 Set or retrieve the relative paths that are appended to "prefix"
1545 for any installable element. This is useful if you want to set the
1546 relative install path for custom build elements.
1547 With no argument, it returns a reference to a hash containing all
1549 elements and their respective values as defined by the current
1550 "installdirs" setting.
1551 With a single argument, it returns a reference to a hash containing
1553 all elements and their respective values as defined by
1554 $installdirs.
1555 The hash returned by the above calls should not be modified
1557 directly; use the three-argument below form to change values.
1558 The two argument form returns the value associated with the element
1560 $type.
1561 The multiple argument form allows you to set the paths for element
1563 types. $value must be a relative path using Unix-like paths. (A
1564 series of directories separated by slashes, e.g. "foo/bar".) The
1565 return value is a localized path based on $value.
1566 Assigning the value "undef" to an element causes it to be removed.
1568 get_metadata()
1570 [version 0.36]
1571 This method returns a hash reference of metadata that can be used
1573 to create a YAML datastream. It is provided for authors to override
1574 or customize the fields of META.yml. E.g.
1575 package My::Builder;
1577 use base 'Module::Build';
1578 sub get_metadata {
1580 my $self, @args = @_;
1581 my $data = $self->SUPER::get_metadata(@args);
1582 $data->{custom_field} = 'foo';
1583 return $data;
1584 }
1585 Valid arguments include:
1587 • "fatal" -- indicates whether missing required metadata fields
1589 should be a fatal error or not. For META creation, it
1590 generally should, but for MYMETA creation for end-users, it
1591 should not be fatal.
1592 • "auto" -- indicates whether any necessary configure_requires
1594 should be automatically added. This is used in META creation.
1595 This method is a wrapper around the old prepare_metadata API now
1597 that we no longer use YAML::Node to hold metadata.
1598 prepare_metadata() [deprecated]
1600 [version 0.36]
1601 [Deprecated] As of 0.36, authors should use "get_metadata" instead.
1603 This method is preserved for backwards compatibility only.
1604 It takes three positional arguments: a hashref (to which metadata
1606 will be added), an optional arrayref (to which metadata keys will
1607 be added in order if the arrayref exists), and a hashref of
1608 arguments (as provided to get_metadata). The latter argument is
1609 new as of 0.36. Earlier versions are always fatal on errors.
1610 Prior to version 0.36, this method took a YAML::Node as an argument
1612 to hold assembled metadata.
1613 prereq_failures()
1615 [version 0.11]
1616 Returns a data structure containing information about any failed
1618 prerequisites (of any of the types described above), or "undef" if
1619 all prerequisites are met.
1620 The data structure returned is a hash reference. The top level
1622 keys are the type of prerequisite failed, one of "requires",
1623 "build_requires", "conflicts", or "recommends". The associated
1624 values are hash references whose keys are the names of required (or
1625 conflicting) modules. The associated values of those are hash
1626 references indicating some information about the failure. For
1627 example:
1628 {
1630 have => '0.42',
1631 need => '0.59',
1632 message => 'Version 0.42 is installed, but we need version 0.59',
1633 }
1634 or
1636 {
1638 have => '<none>',
1639 need => '0.59',
1640 message => 'Prerequisite Foo isn't installed',
1641 }
1642 This hash has the same structure as the hash returned by the
1644 check_installed_status() method, except that in the case of
1645 "conflicts" dependencies we change the "need" key to "conflicts"
1646 and construct a proper message.
1647 Examples:
1649 # Check a required dependency on Foo::Bar
1651 if ( $build->prereq_failures->{requires}{Foo::Bar} ) { ...
1652 # Check whether there were any failures
1654 if ( $build->prereq_failures ) { ...
1655 # Show messages for all failures
1657 my $failures = $build->prereq_failures;
1658 while (my ($type, $list) = each %$failures) {
1659 while (my ($name, $hash) = each %$list) {
1660 print "Failure for $name: $hash->{message}\n";
1661 }
1662 }
1663 prereq_data()
1665 [version 0.32]
1666 Returns a reference to a hash describing all prerequisites. The
1668 keys of the hash will be the various prerequisite types
1669 ('requires', 'build_requires', 'test_requires',
1670 'configure_requires', 'recommends', or 'conflicts') and the values
1671 will be references to hashes of module names and version numbers.
1672 Only prerequisites types that are defined will be included. The
1673 "prereq_data" action is just a thin wrapper around the
1674 prereq_data() method and dumps the hash as a string that can be
1675 loaded using eval().
1676 prereq_report()
1678 [version 0.28]
1679 Returns a human-readable (table-form) string showing all
1681 prerequisites, the versions required, and the versions actually
1682 installed. This can be useful for reviewing the configuration of
1683 your system prior to a build, or when compiling data to send for a
1684 bug report. The "prereq_report" action is just a thin wrapper
1685 around the prereq_report() method.
1686 prompt($message, $default)
1688 [version 0.12]
1689 Asks the user a question and returns their response as a string.
1691 The first argument specifies the message to display to the user
1692 (for example, "Where do you keep your money?"). The second
1693 argument, which is optional, specifies a default answer (for
1694 example, "wallet"). The user will be asked the question once.
1695 If prompt() detects that it is not running interactively and there
1697 is nothing on STDIN or if the PERL_MM_USE_DEFAULT environment
1698 variable is set to true, the $default will be used without
1699 prompting.
1700 To prevent automated processes from blocking, the user must either
1702 set PERL_MM_USE_DEFAULT or attach something to STDIN (this can be a
1703 pipe/file containing a scripted set of answers or /dev/null.)
1704 If no $default is provided an empty string will be used instead.
1706 In non-interactive mode, the absence of $default is an error
1707 (though explicitly passing undef() as the default is valid as of
1708 0.27.)
1709 This method may be called as a class or object method.
1711 recommends()
1713 [version 0.21]
1714 Returns a hash reference indicating the "recommends" prerequisites
1716 that were passed to the new() method.
1717 requires()
1719 [version 0.21]
1720 Returns a hash reference indicating the "requires" prerequisites
1722 that were passed to the new() method.
1723 rscan_dir($dir, $pattern)
1725 [version 0.28]
1726 Uses "File::Find" to traverse the directory $dir, returning a
1728 reference to an array of entries matching $pattern. $pattern may
1729 either be a regular expression (using "qr//" or just a plain
1730 string), or a reference to a subroutine that will return true for
1731 wanted entries. If $pattern is not given, all entries will be
1732 returned.
1733 Examples:
1735 # All the *.pm files in lib/
1737 $m->rscan_dir('lib', qr/\.pm$/)
1738 # All the files in blib/ that aren't *.html files
1740 $m->rscan_dir('blib', sub {-f $_ and not /\.html$/});
1741 # All the files in t/
1743 $m->rscan_dir('t');
1744 runtime_params()
1746 runtime_params($key)
1747 [version 0.28]
1748 The runtime_params() method stores the values passed on the command
1750 line for valid properties (that is, any command line options for
1751 which valid_property() returns a true value). The value on the
1752 command line may override the default value for a property, as well
1753 as any value specified in a call to new(). This allows you to
1754 programmatically tell if "perl Build.PL" or any execution of
1755 "./Build" had command line options specified that override valid
1756 properties.
1757 The runtime_params() method is essentially a glorified read-only
1759 hash. With no arguments, runtime_params() returns the entire hash
1760 of properties specified on the command line. With one argument,
1761 runtime_params($key) returns the value associated with the given
1762 key.
1763 The lifetime of the "runtime_params" data is for "a build" - that
1765 is, the "runtime_params" hash is created when "perl Build.PL" is
1766 run (or when the new() method is called, if the Module::Build Perl
1767 API is being used instead of called from a shell), and lasts until
1768 "perl Build.PL" is run again or the "clean" action is run.
1769 script_files()
1771 [version 0.18]
1772 Returns a hash reference whose keys are the perl script files to be
1774 installed, if any. This corresponds to the "script_files"
1775 parameter to the new() method. With an optional argument, this
1776 parameter may be set dynamically.
1777 For backward compatibility, the scripts() method does exactly the
1779 same thing as script_files(). scripts() is deprecated, but it will
1780 stay around for several versions to give people time to transition.
1781 up_to_date($source_file, $derived_file)
1783 up_to_date(\@source_files, \@derived_files)
1784 [version 0.20]
1785 This method can be used to compare a set of source files to a set
1787 of derived files. If any of the source files are newer than any of
1788 the derived files, it returns false. Additionally, if any of the
1789 derived files do not exist, it returns false. Otherwise it returns
1790 true.
1791 The arguments may be either a scalar or an array reference of file
1793 names.
1794 y_n($message, $default)
1796 [version 0.12]
1797 Asks the user a yes/no question using prompt() and returns true or
1799 false accordingly. The user will be asked the question repeatedly
1800 until they give an answer that looks like "yes" or "no".
1801 The first argument specifies the message to display to the user
1803 (for example, "Shall I invest your money for you?"), and the second
1804 argument specifies the default answer (for example, "y").
1805 Note that the default is specified as a string like "y" or "n", and
1807 the return value is a Perl boolean value like 1 or 0. I thought
1808 about this for a while and this seemed like the most useful way to
1809 do it.
1810 This method may be called as a class or object method.
1812 Autogenerated Accessors
1814 In addition to the aforementioned methods, there are also some get/set
1815 accessor methods for the following properties:
1816 PL_files()
1818 allow_mb_mismatch()
1819 allow_pureperl()
1820 auto_configure_requires()
1821 autosplit()
1822 base_dir()
1823 bindoc_dirs()
1824 blib()
1825 build_bat()
1826 build_class()
1827 build_elements()
1828 build_requires()
1829 build_script()
1830 bundle_inc()
1831 bundle_inc_preload()
1832 c_source()
1833 config_dir()
1834 configure_requires()
1835 conflicts()
1836 cover()
1837 cpan_client()
1838 create_license()
1839 create_makefile_pl()
1840 create_packlist()
1841 create_readme()
1842 debug()
1843 debugger()
1844 destdir()
1845 dynamic_config()
1846 extra_manify_args()
1847 get_options()
1848 html_css()
1849 include_dirs()
1850 install_base()
1851 installdirs()
1852 libdoc_dirs()
1853 license()
1854 magic_number()
1855 mb_version()
1856 meta_add()
1857 meta_merge()
1858 metafile()
1859 metafile2()
1860 module_name()
1861 mymetafile()
1862 mymetafile2()
1863 needs_compiler()
1864 orig_dir()
1865 perl()
1866 pm_files()
1867 pod_files()
1868 pollute()
1869 prefix()
1870 prereq_action_types()
1871 program_name()
1872 pureperl_only()
1873 quiet()
1874 recommends()
1875 recurse_into()
1876 recursive_test_files()
1877 requires()
1878 scripts()
1879 sign()
1880 tap_harness_args()
1881 test_file_exts()
1882 test_requires()
1883 use_rcfile()
1884 use_tap_harness()
1885 verbose()
1886 xs_files()
1887
1889 If you would like to add other useful metadata, "Module::Build"
1890 supports this with the "meta_add" and "meta_merge" arguments to
1891 "new()". The authoritative list of supported metadata can be found at
1892 CPAN::Meta::Spec but for convenience - here are a few of the more
1893 useful ones:
1894 keywords
1896 For describing the distribution using keyword (or "tags") in order
1897 to make CPAN.org indexing and search more efficient and useful.
1898 resources
1900 A list of additional resources available for users of the
1901 distribution. This can include links to a homepage on the web, a
1902 bug tracker, the repository location, and even a subscription page
1903 for the distribution mailing list.
1904
1906 Ken Williams <kwilliams@cpan.org>
1907
1909 Copyright (c) 2001-2006 Ken Williams. All rights reserved.
1910 This library is free software; you can redistribute it and/or modify it
1912 under the same terms as Perl itself.
1913
1915 perl(1), Module::Build(3), Module::Build::Authoring(3),
1916 Module::Build::Cookbook(3), ExtUtils::MakeMaker(3)
1917 META.yml Specification: CPAN::Meta::Spec
1919perl v5.36.0 2023-01-20 Module::Build::API(3)