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