[Summary view] [Print] [Text view]

   1  =head1 NAME
   2  
   3  Module::Build::API - API Reference for Module Authors
   4  
   5  
   6  =head1 DESCRIPTION
   7  
   8  I list here some of the most important methods in C<Module::Build>.
   9  Normally you won't need to deal with these methods unless you want to
  10  subclass C<Module::Build>.  But since one of the reasons I created
  11  this module in the first place was so that subclassing is possible
  12  (and easy), I will certainly write more docs as the interface
  13  stabilizes.
  14  
  15  
  16  =head2 CONSTRUCTORS
  17  
  18  =over 4
  19  
  20  =item current()
  21  
  22  [version 0.20]
  23  
  24  This method returns a reasonable facsimile of the currently-executing
  25  C<Module::Build> object representing the current build.  You can use
  26  this object to query its L</notes()> method, inquire about installed
  27  modules, and so on.  This is a great way to share information between
  28  different parts of your build process.  For instance, you can ask
  29  the user a question during C<perl Build.PL>, then use their answer
  30  during a regression test:
  31  
  32    # In Build.PL:
  33    my $color = $build->prompt("What is your favorite color?");
  34    $build->notes(color => $color);
  35  
  36    # In t/colortest.t:
  37    use Module::Build;
  38    my $build = Module::Build->current;
  39    my $color = $build->notes('color');
  40    ...
  41  
  42  The way the C<current()> method is currently implemented, there may be
  43  slight differences between the C<$build> object in Build.PL and the
  44  one in C<t/colortest.t>.  It is our goal to minimize these differences
  45  in future releases of Module::Build, so please report any anomalies
  46  you find.
  47  
  48  One important caveat: in its current implementation, C<current()> will
  49  B<NOT> work correctly if you have changed out of the directory that
  50  C<Module::Build> was invoked from.
  51  
  52  =item new()
  53  
  54  [version 0.03]
  55  
  56  Creates a new Module::Build object.  Arguments to the new() method are
  57  listed below.  Most arguments are optional, but you must provide
  58  either the L</module_name> argument, or L</dist_name> and one of
  59  L</dist_version> or L</dist_version_from>.  In other words, you must
  60  provide enough information to determine both a distribution name and
  61  version.
  62  
  63  
  64  =over 4
  65  
  66  =item add_to_cleanup
  67  
  68  [version 0.19]
  69  
  70  An array reference of files to be cleaned up when the C<clean> action
  71  is performed. See also the L<add_to_cleanup()|/"add_to_cleanup(@files)">
  72  method.
  73  
  74  =item auto_features
  75  
  76  [version 0.26]
  77  
  78  This parameter supports the setting of features (see
  79  L</feature($name)>) automatically based on a set of prerequisites.  For
  80  instance, for a module that could optionally use either MySQL or
  81  PostgreSQL databases, you might use C<auto_features> like this:
  82  
  83    my $build = Module::Build->new
  84      (
  85       ...other stuff here...
  86       auto_features => {
  87         pg_support    => {
  88                           description => "Interface with Postgres databases",
  89                           requires    => { 'DBD::Pg' => 23.3,
  90                                            'DateTime::Format::Pg' => 0 },
  91                          },
  92         mysql_support => {
  93                           description => "Interface with MySQL databases",
  94                           requires    => { 'DBD::mysql' => 17.9,
  95                                            'DateTime::Format::MySQL' => 0 },
  96                          },
  97       }
  98      );
  99  
 100  For each feature named, the required prerequisites will be checked, and
 101  if there are no failures, the feature will be enabled (set to C<1>).
 102  Otherwise the failures will be displayed to the user and the feature
 103  will be disabled (set to C<0>).
 104  
 105  See the documentation for L</requires> for the details of how
 106  requirements can be specified.
 107  
 108  =item autosplit
 109  
 110  [version 0.04]
 111  
 112  An optional C<autosplit> argument specifies a file which should be run
 113  through the L<AutoSplit::autosplit()|AutoSplit/autosplit> function.
 114  If multiple files should be split, the argument may be given as an
 115  array of the files to split.
 116  
 117  In general I don't consider autosplitting a great idea, because it's
 118  not always clear that autosplitting achieves its intended performance
 119  benefits.  It may even harm performance in environments like mod_perl,
 120  where as much as possible of a module's code should be loaded during
 121  startup.
 122  
 123  =item build_class
 124  
 125  [version 0.28]
 126  
 127  The Module::Build class or subclass to use in the build script.
 128  Defaults to "Module::Build" or the class name passed to or created by
 129  a call to L</subclass()>.  This property is useful if you're
 130  writing a custom Module::Build subclass and have a bootstrapping
 131  problem--that is, your subclass requires modules that may not be
 132  installed when C<perl Build.PL> is executed, but you've listed in
 133  L</build_requires> so that they should be available when C<./Build> is
 134  executed.
 135  
 136  =item build_requires
 137  
 138  [version 0.07]
 139  
 140  Modules listed in this section are necessary to build and install the
 141  given module, but are not necessary for regular usage of it.  This is
 142  actually an important distinction - it allows for tighter control over
 143  the body of installed modules, and facilitates correct dependency
 144  checking on binary/packaged distributions of the module.
 145  
 146  See the documentation for L<Module::Build::Authoring/"PREREQUISITES">
 147  for the details of how requirements can be specified.
 148  
 149  =item create_packlist
 150  
 151  [version 0.28]
 152  
 153  If true, this parameter tells Module::Build to create a F<.packlist>
 154  file during the C<install> action, just like ExtUtils::MakeMaker does.
 155  The file is created in a subdirectory of the C<arch> installation
 156  location.  It is used by some other tools (CPAN, CPANPLUS, etc.) for
 157  determining what files are part of an install.
 158  
 159  The default value is true.  This parameter was introduced in
 160  Module::Build version 0.2609; previously no packlists were ever
 161  created by Module::Build.
 162  
 163  =item c_source
 164  
 165  [version 0.04]
 166  
 167  An optional C<c_source> argument specifies a directory which contains
 168  C source files that the rest of the build may depend on.  Any C<.c>
 169  files in the directory will be compiled to object files.  The
 170  directory will be added to the search path during the compilation and
 171  linking phases of any C or XS files.
 172  
 173  =item conflicts
 174  
 175  [version 0.07]
 176  
 177  Modules listed in this section conflict in some serious way with the
 178  given module.  C<Module::Build> (or some higher-level tool) will
 179  refuse to install the given module if the given module/version is also
 180  installed.
 181  
 182  See the documentation for L<Module::Build::Authoring/"PREREQUISITES">
 183  for the details of how requirements can be specified.
 184  
 185  =item create_makefile_pl
 186  
 187  [version 0.19]
 188  
 189  This parameter lets you use Module::Build::Compat during the
 190  C<distdir> (or C<dist>) action to automatically create a Makefile.PL
 191  for compatibility with ExtUtils::MakeMaker.  The parameter's value
 192  should be one of the styles named in the L<Module::Build::Compat>
 193  documentation.
 194  
 195  =item create_readme
 196  
 197  [version 0.22]
 198  
 199  This parameter tells Module::Build to automatically create a F<README>
 200  file at the top level of your distribution.  Currently it will simply
 201  use C<Pod::Text> (or C<Pod::Readme> if it's installed) on the file
 202  indicated by C<dist_version_from> and put the result in the F<README>
 203  file.  This is by no means the only recommended style for writing a
 204  README, but it seems to be one common one used on the CPAN.
 205  
 206  If you generate a F<README> in this way, it's probably a good idea to
 207  create a separate F<INSTALL> file if that information isn't in the
 208  generated F<README>.
 209  
 210  =item dist_abstract
 211  
 212  [version 0.20]
 213  
 214  This should be a short description of the distribution.  This is used
 215  when generating metadata for F<META.yml> and PPD files.  If it is not
 216  given then C<Module::Build> looks in the POD of the module from which
 217  it gets the distribution's version.  It looks for the first line
 218  matching C<$package\s-\s(.+)>, and uses the captured text as the
 219  abstract.
 220  
 221  =item dist_author
 222  
 223  [version 0.20]
 224  
 225  This should be something like "John Doe <jdoe@example.com>", or if
 226  there are multiple authors, an anonymous array of strings may be
 227  specified.  This is used when generating metadata for F<META.yml> and
 228  PPD files.  If this is not specified, then C<Module::Build> looks at
 229  the module from which it gets the distribution's version.  If it finds
 230  a POD section marked "=head1 AUTHOR", then it uses the contents of
 231  this section.
 232  
 233  =item dist_name
 234  
 235  [version 0.11]
 236  
 237  Specifies the name for this distribution.  Most authors won't need to
 238  set this directly, they can use C<module_name> to set C<dist_name> to
 239  a reasonable default.  However, some agglomerative distributions like
 240  C<libwww-perl> or C<bioperl> have names that don't correspond directly
 241  to a module name, so C<dist_name> can be set independently.
 242  
 243  =item dist_version
 244  
 245  [version 0.11]
 246  
 247  Specifies a version number for the distribution.  See L</module_name>
 248  or L</dist_version_from> for ways to have this set automatically from a
 249  C<$VERSION> variable in a module.  One way or another, a version
 250  number needs to be set.
 251  
 252  =item dist_version_from
 253  
 254  [version 0.11]
 255  
 256  Specifies a file to look for the distribution version in.  Most
 257  authors won't need to set this directly, they can use L</module_name>
 258  to set it to a reasonable default.
 259  
 260  The version is extracted from the specified file according to the same
 261  rules as L<ExtUtils::MakeMaker> and C<CPAN.pm>.  It involves finding
 262  the first line that matches the regular expression
 263  
 264     /([\$*])(([\w\:\']*)\bVERSION)\b.*\=/
 265  
 266  eval()-ing that line, then checking the value of the C<$VERSION>
 267  variable.  Quite ugly, really, but all the modules on CPAN depend on
 268  this process, so there's no real opportunity to change to something
 269  better.
 270  
 271  =item dynamic_config
 272  
 273  [version 0.07]
 274  
 275  A boolean flag indicating whether the F<Build.PL> file must be
 276  executed, or whether this module can be built, tested and installed
 277  solely from consulting its metadata file.  The main reason to set this
 278  to a true value is that your module performs some dynamic
 279  configuration as part of its build/install process.  If the flag is
 280  omitted, the F<META.yml> spec says that installation tools should
 281  treat it as 1 (true), because this is a safer way to behave.
 282  
 283  Currently C<Module::Build> doesn't actually do anything with this flag
 284  - it's up to higher-level tools like C<CPAN.pm> to do something useful
 285  with it.  It can potentially bring lots of security, packaging, and
 286  convenience improvements.
 287  
 288  =item extra_compiler_flags
 289  
 290  =item extra_linker_flags
 291  
 292  [version 0.19]
 293  
 294  These parameters can contain array references (or strings, in which
 295  case they will be split into arrays) to pass through to the compiler
 296  and linker phases when compiling/linking C code.  For example, to tell
 297  the compiler that your code is C++, you might do:
 298  
 299    my $build = Module::Build->new
 300      (
 301       module_name          => 'Foo::Bar',
 302       extra_compiler_flags => ['-x', 'c++'],
 303      );
 304  
 305  To link your XS code against glib you might write something like:
 306  
 307    my $build = Module::Build->new
 308      (
 309       module_name          => 'Foo::Bar',
 310       dynamic_config       => 1,
 311       extra_compiler_flags => scalar `glib-config --cflags`,
 312       extra_linker_flags   => scalar `glib-config --libs`,
 313      );
 314  
 315  =item get_options
 316  
 317  [version 0.26]
 318  
 319  You can pass arbitrary command line options to F<Build.PL> or
 320  F<Build>, and they will be stored in the Module::Build object and can
 321  be accessed via the L</args()> method.  However, sometimes you want
 322  more flexibility out of your argument processing than this allows.  In
 323  such cases, use the C<get_options> parameter to pass in a hash
 324  reference of argument specifications, and the list of arguments to
 325  F<Build.PL> or F<Build> will be processed according to those
 326  specifications before they're passed on to C<Module::Build>'s own
 327  argument processing.
 328  
 329  The supported option specification hash keys are:
 330  
 331  
 332  =over 4
 333  
 334  =item type
 335  
 336  The type of option.  The types are those supported by Getopt::Long; consult
 337  its documentation for a complete list.  Typical types are C<=s> for strings,
 338  C<+> for additive options, and C<!> for negatable options.  If the
 339  type is not specified, it will be considered a boolean, i.e. no
 340  argument is taken and a value of 1 will be assigned when the option is
 341  encountered.
 342  
 343  =item store
 344  
 345  A reference to a scalar in which to store the value passed to the option.
 346  If not specified, the value will be stored under the option name in the
 347  hash returned by the C<args()> method.
 348  
 349  =item default
 350  
 351  A default value for the option.  If no default value is specified and no option
 352  is passed, then the option key will not exist in the hash returned by
 353  C<args()>.
 354  
 355  =back
 356  
 357  
 358  You can combine references to your own variables or subroutines with
 359  unreferenced specifications, for which the result will also be stored in the
 360  hash returned by C<args()>.  For example:
 361  
 362    my $loud = 0;
 363    my $build = Module::Build->new
 364      (
 365       module_name => 'Foo::Bar',
 366       get_options => {
 367                       loud =>     { store => \$loud },
 368                       dbd  =>     { type  => '=s'   },
 369                       quantity => { type  => '+'    },
 370                      }
 371      );
 372  
 373    print STDERR "HEY, ARE YOU LISTENING??\n" if $loud;
 374    print "We'll use the ", $build->args('dbd'), " DBI driver\n";
 375    print "Are you sure you want that many?\n"
 376      if $build->args('quantity') > 2;
 377  
 378  The arguments for such a specification can be called like so:
 379  
 380    perl Build.PL --loud --dbd=DBD::pg --quantity --quantity --quantity
 381  
 382  B<WARNING:> Any option specifications that conflict with Module::Build's own
 383  options (defined by its properties) will throw an exception.
 384  
 385  Consult the Getopt::Long documentation for details on its usage.
 386  
 387  =item include_dirs
 388  
 389  [version 0.24]
 390  
 391  Specifies any additional directories in which to search for C header
 392  files.  May be given as a string indicating a single directory, or as
 393  a list reference indicating multiple directories.
 394  
 395  =item install_path
 396  
 397  [version 0.19]
 398  
 399  You can set paths for individual installable elements by using the
 400  C<install_path> parameter:
 401  
 402    my $build = Module::Build->new
 403      (
 404       ...other stuff here...
 405       install_path => {
 406                        lib  => '/foo/lib',
 407                        arch => '/foo/lib/arch',
 408                       }
 409      );
 410  
 411  =item installdirs
 412  
 413  [version 0.19]
 414  
 415  Determines where files are installed within the normal perl hierarchy
 416  as determined by F<Config.pm>.  Valid values are: C<core>, C<site>,
 417  C<vendor>.  The default is C<site>.  See
 418  L<Module::Build/"INSTALL PATHS">
 419  
 420  =item license
 421  
 422  [version 0.07]
 423  
 424  Specifies the licensing terms of your distribution.  Valid options include:
 425  
 426  
 427  =over 4
 428  
 429  =item apache
 430  
 431  The distribution is licensed under the Apache Software License
 432  (L<http://opensource.org/licenses/apachepl.php>).
 433  
 434  =item artistic
 435  
 436  The distribution is licensed under the Artistic License, as specified
 437  by the F<Artistic> file in the standard Perl distribution.
 438  
 439  =item artistic_2
 440  
 441  The distribution is licensed under the Artistic 2.0 License
 442  (L<http://opensource.org/licenses/artistic-license-2.0.php>.)
 443  
 444  =item bsd
 445  
 446  The distribution is licensed under the BSD License
 447  (L<http://www.opensource.org/licenses/bsd-license.php>).
 448  
 449  =item gpl
 450  
 451  The distribution is licensed under the terms of the GNU General
 452  Public License (L<http://www.opensource.org/licenses/gpl-license.php>).
 453  
 454  =item lgpl
 455  
 456  The distribution is licensed under the terms of the GNU Lesser
 457  General Public License
 458  (L<http://www.opensource.org/licenses/lgpl-license.php>).
 459  
 460  =item mit
 461  
 462  The distribution is licensed under the MIT License
 463  (L<http://opensource.org/licenses/mit-license.php>).
 464  
 465  =item mozilla
 466  
 467  The distribution is licensed under the Mozilla Public
 468  License.  (L<http://opensource.org/licenses/mozilla1.0.php> or
 469  L<http://opensource.org/licenses/mozilla1.1.php>)
 470  
 471  =item open_source
 472  
 473  The distribution is licensed under some other Open Source
 474  Initiative-approved license listed at
 475  L<http://www.opensource.org/licenses/>.
 476  
 477  =item perl
 478  
 479  The distribution may be copied and redistributed under the same terms
 480  as Perl itself (this is by far the most common licensing option for
 481  modules on CPAN).  This is a dual license, in which the user may
 482  choose between either the GPL or the Artistic license.
 483  
 484  =item restrictive
 485  
 486  The distribution may not be redistributed without special permission
 487  from the author and/or copyright holder.
 488  
 489  =item unrestricted
 490  
 491  The distribution is licensed under a license that is B<not> approved
 492  by www.opensource.org but that allows distribution without
 493  restrictions.
 494  
 495  =back
 496  
 497  
 498  Note that you must still include the terms of your license in your
 499  documentation - this field only lets automated tools figure out your
 500  licensing restrictions.  Humans still need something to read.  If you
 501  choose to provide this field, you should make sure that you keep it in
 502  sync with your written documentation if you ever change your licensing
 503  terms.
 504  
 505  It is a fatal error to use a license other than the ones mentioned
 506  above.  This is not because I wish to impose licensing terms on you -
 507  please let me know if you would like another license option to be
 508  added to the list.  You may also use a license type of C<unknown> if
 509  you don't wish to specify your terms (but this is usually not a good
 510  idea for you to do!).
 511  
 512  I just started out with a small set of licenses to keep things simple,
 513  figuring I'd let people with actual working knowledge in this area
 514  tell me what to do.  So if that's you, drop me a line.
 515  
 516  =item meta_add
 517  
 518  [version 0.28]
 519  
 520  A hash of key/value pairs that should be added to the F<META.yml> file
 521  during the C<distmeta> action.  Any existing entries with the same
 522  names will be overridden.
 523  
 524  See the L</"MODULE METADATA"> section for details.
 525  
 526  =item meta_merge
 527  
 528  [version 0.28]
 529  
 530  A hash of key/value pairs that should be merged into the F<META.yml>
 531  file during the C<distmeta> action.  Any existing entries with the
 532  same names will be overridden.
 533  
 534  The only difference between C<meta_add> and C<meta_merge> is their
 535  behavior on hash-valued and array-valued entries: C<meta_add> will
 536  completely blow away the existing hash or array value, but
 537  C<meta_merge> will merge the supplied data into the existing hash or
 538  array value.
 539  
 540  See the L</"MODULE METADATA"> section for details.
 541  
 542  =item module_name
 543  
 544  [version 0.03]
 545  
 546  The C<module_name> is a shortcut for setting default values of
 547  C<dist_name> and C<dist_version_from>, reflecting the fact that the
 548  majority of CPAN distributions are centered around one "main" module.
 549  For instance, if you set C<module_name> to C<Foo::Bar>, then
 550  C<dist_name> will default to C<Foo-Bar> and C<dist_version_from> will
 551  default to C<lib/Foo/Bar.pm>.  C<dist_version_from> will in turn be
 552  used to set C<dist_version>.
 553  
 554  Setting C<module_name> won't override a C<dist_*> parameter you
 555  specify explicitly.
 556  
 557  =item PL_files
 558  
 559  [version 0.06]
 560  
 561  An optional parameter specifying a set of C<.PL> files in your
 562  distribution.  These will be run as Perl scripts prior to processing
 563  the rest of the files in your distribution.  They are usually used as
 564  templates for creating other files dynamically, so that a file like
 565  C<lib/Foo/Bar.pm.PL> might create the file C<lib/Foo/Bar.pm>.
 566  
 567  The files are specified with the C<.PL> files as hash keys, and the
 568  file(s) they generate as hash values, like so:
 569  
 570    my $build = Module::Build->new
 571      (
 572       module_name => 'Foo::Bar',
 573       ...
 574       PL_files => { 'lib/Foo/Bar.pm.PL' => 'lib/Foo/Bar.pm' },
 575      );
 576  
 577  Note that the path specifications are I<always> given in Unix-like
 578  format, not in the style of the local system.
 579  
 580  If your C<.PL> scripts don't create any files, or if they create files
 581  with unexpected names, or even if they create multiple files, you can
 582  indicate that so that Module::Build can properly handle these created
 583  files:
 584  
 585    PL_files => {
 586                 'lib/Foo/Bar.pm.PL' => 'lib/Foo/Bar.pm',
 587                 'lib/something.PL'  => ['/lib/something', '/lib/else'],
 588                 'lib/funny.PL'      => [],
 589                }
 590  
 591  =item pm_files
 592  
 593  [version 0.19]
 594  
 595  An optional parameter specifying the set of C<.pm> files in this
 596  distribution, specified as a hash reference whose keys are the files'
 597  locations in the distributions, and whose values are their logical
 598  locations based on their package name, i.e. where they would be found
 599  in a "normal" Module::Build-style distribution.  This parameter is
 600  mainly intended to support alternative layouts of files.
 601  
 602  For instance, if you have an old-style MakeMaker distribution for a
 603  module called C<Foo::Bar> and a F<Bar.pm> file at the top level of the
 604  distribution, you could specify your layout in your C<Build.PL> like
 605  this:
 606  
 607    my $build = Module::Build->new
 608      (
 609       module_name => 'Foo::Bar',
 610       ...
 611       pm_files => { 'Bar.pm' => 'lib/Foo/Bar.pm' },
 612      );
 613  
 614  Note that the values should include C<lib/>, because this is where
 615  they would be found in a "normal" Module::Build-style distribution.
 616  
 617  Note also that the path specifications are I<always> given in
 618  Unix-like format, not in the style of the local system.
 619  
 620  =item pod_files
 621  
 622  [version 0.19]
 623  
 624  Just like C<pm_files>, but used for specifying the set of C<.pod>
 625  files in your distribution.
 626  
 627  =item recommends
 628  
 629  [version 0.08]
 630  
 631  This is just like the L</requires> argument, except that modules listed
 632  in this section aren't essential, just a good idea.  We'll just print
 633  a friendly warning if one of these modules aren't found, but we'll
 634  continue running.
 635  
 636  If a module is recommended but not required, all tests should still
 637  pass if the module isn't installed.  This may mean that some tests
 638  may be skipped if recommended dependencies aren't present.
 639  
 640  Automated tools like CPAN.pm should inform the user when recommended
 641  modules aren't installed, and it should offer to install them if it
 642  wants to be helpful.
 643  
 644  See the documentation for L<Module::Build::Authoring/"PREREQUISITES">
 645  for the details of how requirements can be specified.
 646  
 647  =item recursive_test_files
 648  
 649  [version 0.28]
 650  
 651  Normally, C<Module::Build> does not search subdirectories when looking
 652  for tests to run. When this options is set it will search recursively
 653  in all subdirectories of the standard 't' test directory.
 654  
 655  =item requires
 656  
 657  [version 0.07]
 658  
 659  An optional C<requires> argument specifies any module prerequisites
 660  that the current module depends on.
 661  
 662  One note: currently C<Module::Build> doesn't actually I<require> the
 663  user to have dependencies installed, it just strongly urges.  In the
 664  future we may require it.  There's also a L</recommends> section for
 665  things that aren't absolutely required.
 666  
 667  Automated tools like CPAN.pm should refuse to install a module if one
 668  of its dependencies isn't satisfied, unless a "force" command is given
 669  by the user.  If the tools are helpful, they should also offer to
 670  install the dependencies.
 671  
 672  A synonym for C<requires> is C<prereq>, to help succour people
 673  transitioning from C<ExtUtils::MakeMaker>.  The C<requires> term is
 674  preferred, but the C<prereq> term will remain valid in future
 675  distributions.
 676  
 677  See the documentation for L<Module::Build::Authoring/"PREREQUISITES">
 678  for the details of how requirements can be specified.
 679  
 680  =item script_files
 681  
 682  [version 0.18]
 683  
 684  An optional parameter specifying a set of files that should be
 685  installed as executable Perl scripts when the module is installed.
 686  May be given as an array reference of the files, or as a hash
 687  reference whose keys are the files (and whose values will currently be
 688  ignored).
 689  
 690  The default is to install no script files - in other words, there is
 691  no default location where Module::Build will look for script files to
 692  install.
 693  
 694  For backward compatibility, you may use the parameter C<scripts>
 695  instead of C<script_files>.  Please consider this usage deprecated,
 696  though it will continue to exist for several version releases.
 697  
 698  =item sign
 699  
 700  [version 0.16]
 701  
 702  If a true value is specified for this parameter, L<Module::Signature>
 703  will be used (via the 'distsign' action) to create a SIGNATURE file
 704  for your distribution during the 'distdir' action, and to add the
 705  SIGNATURE file to the MANIFEST (therefore, don't add it yourself).
 706  
 707  The default value is false.  In the future, the default may change to
 708  true if you have C<Module::Signature> installed on your system.
 709  
 710  =item test_files
 711  
 712  [version 0.23]
 713  
 714  An optional parameter specifying a set of files that should be used as
 715  C<Test::Harness>-style regression tests to be run during the C<test>
 716  action.  May be given as an array reference of the files, or as a hash
 717  reference whose keys are the files (and whose values will currently be
 718  ignored).  If the argument is given as a single string (not in an
 719  array reference), that string will be treated as a C<glob()> pattern
 720  specifying the files to use.
 721  
 722  The default is to look for a F<test.pl> script in the top-level
 723  directory of the distribution, and any files matching the glob pattern
 724  C<*.t> in the F<t/> subdirectory.  If the C<recursive_test_files>
 725  property is true, then the C<t/> directory will be scanned recursively
 726  for C<*.t> files.
 727  
 728  
 729  =item xs_files
 730  
 731  [version 0.19]
 732  
 733  Just like C<pm_files>, but used for specifying the set of C<.xs>
 734  files in your distribution.
 735  
 736  =back
 737  
 738  
 739  =item new_from_context(%args)
 740  
 741  [version 0.28]
 742  
 743  When called from a directory containing a F<Build.PL> script and a
 744  F<META.yml> file (in other words, the base directory of a
 745  distribution), this method will run the F<Build.PL> and return the
 746  resulting C<Module::Build> object to the caller.  Any key-value
 747  arguments given to C<new_from_context()> are essentially like
 748  command line arguments given to the F<Build.PL> script, so for example
 749  you could pass C<< verbose => 1 >> to this method to turn on
 750  verbosity.
 751  
 752  =item resume()
 753  
 754  [version 0.03]
 755  
 756  You'll probably never call this method directly, it's only called from
 757  the auto-generated C<Build> script.  The C<new()> method is only
 758  called once, when the user runs C<perl Build.PL>.  Thereafter, when
 759  the user runs C<Build test> or another action, the C<Module::Build>
 760  object is created using the C<resume()> method to re-instantiate with
 761  the settings given earlier to C<new()>.
 762  
 763  =item subclass()
 764  
 765  [version 0.06]
 766  
 767  This creates a new C<Module::Build> subclass on the fly, as described
 768  in the L<Module::Build::Authoring/"SUBCLASSING"> section.  The caller
 769  must provide either a C<class> or C<code> parameter, or both.  The
 770  C<class> parameter indicates the name to use for the new subclass, and
 771  defaults to C<MyModuleBuilder>.  The C<code> parameter specifies Perl
 772  code to use as the body of the subclass.
 773  
 774  =back
 775  
 776  
 777  =head2 METHODS
 778  
 779  =over 4
 780  
 781  =item add_build_element($type)
 782  
 783  [version 0.26]
 784  
 785  Adds a new type of entry to the build process.  Accepts a single
 786  string specifying its type-name.  There must also be a method defined
 787  to process things of that type, e.g. if you add a build element called
 788  C<'foo'>, then you must also define a method called
 789  C<process_foo_files()>.
 790  
 791  See also
 792  L<Module::Build::Cookbook/"Adding new file types to the build process">.
 793  
 794  =item add_to_cleanup(@files)
 795  
 796  [version 0.03]
 797  
 798  You may call C<< $self->add_to_cleanup(@patterns) >> to tell
 799  C<Module::Build> that certain files should be removed when the user
 800  performs the C<Build clean> action.  The arguments to the method are
 801  patterns suitable for passing to Perl's C<glob()> function, specified
 802  in either Unix format or the current machine's native format.  It's
 803  usually convenient to use Unix format when you hard-code the filenames
 804  (e.g. in F<Build.PL>) and the native format when the names are
 805  programmatically generated (e.g. in a testing script).
 806  
 807  I decided to provide a dynamic method of the C<$build> object, rather
 808  than just use a static list of files named in the F<Build.PL>, because
 809  these static lists can get difficult to manage.  I usually prefer to
 810  keep the responsibility for registering temporary files close to the
 811  code that creates them.
 812  
 813  =item args()
 814  
 815  [version 0.26]
 816  
 817    my $args_href = $build->args;
 818    my %args = $build->args;
 819    my $arg_value = $build->args($key);
 820    $build->args($key, $value);
 821  
 822  This method is the preferred interface for retrieving the arguments passed via
 823  command line options to F<Build.PL> or F<Build>, minus the Module-Build
 824  specific options.
 825  
 826  When called in in a scalar context with no arguments, this method returns a
 827  reference to the hash storing all of the arguments; in an array context, it
 828  returns the hash itself.  When passed a single argument, it returns the value
 829  stored in the args hash for that option key.  When called with two arguments,
 830  the second argument is assigned to the args hash under the key passed as the
 831  first argument.
 832  
 833  =item autosplit_file($from, $to)
 834  
 835  [version 0.28]
 836  
 837  Invokes the L<AutoSplit> module on the C<$from> file, sending the
 838  output to the C<lib/auto> directory inside C<$to>.  C<$to> is
 839  typically the C<blib/> directory.
 840  
 841  =item base_dir()
 842  
 843  [version 0.14]
 844  
 845  Returns a string containing the root-level directory of this build,
 846  i.e. where the C<Build.PL> script and the C<lib> directory can be
 847  found.  This is usually the same as the current working directory,
 848  because the C<Build> script will C<chdir()> into this directory as
 849  soon as it begins execution.
 850  
 851  =item build_requires()
 852  
 853  [version 0.21]
 854  
 855  Returns a hash reference indicating the C<build_requires>
 856  prerequisites that were passed to the C<new()> method.
 857  
 858  =item check_installed_status($module, $version)
 859  
 860  [version 0.11]
 861  
 862  This method returns a hash reference indicating whether a version
 863  dependency on a certain module is satisfied.  The C<$module> argument
 864  is given as a string like C<"Data::Dumper"> or C<"perl">, and the
 865  C<$version> argument can take any of the forms described in L</requires>
 866  above.  This allows very fine-grained version checking.
 867  
 868  The returned hash reference has the following structure:
 869  
 870    {
 871     ok => $whether_the_dependency_is_satisfied,
 872     have => $version_already_installed,
 873     need => $version_requested, # Same as incoming $version argument
 874     message => $informative_error_message,
 875    }
 876  
 877  If no version of C<$module> is currently installed, the C<have> value
 878  will be the string C<< "<none>" >>.  Otherwise the C<have> value will
 879  simply be the version of the installed module.  Note that this means
 880  that if C<$module> is installed but doesn't define a version number,
 881  the C<have> value will be C<undef> - this is why we don't use C<undef>
 882  for the case when C<$module> isn't installed at all.
 883  
 884  This method may be called either as an object method
 885  (C<< $build->check_installed_status($module, $version) >>)
 886  or as a class method
 887  (C<< Module::Build->check_installed_status($module, $version) >>).
 888  
 889  =item check_installed_version($module, $version)
 890  
 891  [version 0.05]
 892  
 893  Like L<check_installed_status()|/"check_installed_status($module, $version)">,
 894  but simply returns true or false depending on whether module
 895  C<$module> satisfies the dependency C<$version>.
 896  
 897  If the check succeeds, the return value is the actual version of
 898  C<$module> installed on the system.  This allows you to do the
 899  following:
 900  
 901    my $installed = $build->check_installed_version('DBI', '1.15');
 902    if ($installed) {
 903      print "Congratulations, version $installed of DBI is installed.\n";
 904    } else {
 905      die "Sorry, you must install DBI.\n";
 906    }
 907  
 908  If the check fails, we return false and set C<$@> to an informative
 909  error message.
 910  
 911  If C<$version> is any non-true value (notably zero) and any version of
 912  C<$module> is installed, we return true.  In this case, if C<$module>
 913  doesn't define a version, or if its version is zero, we return the
 914  special value "0 but true", which is numerically zero, but logically
 915  true.
 916  
 917  In general you might prefer to use C<check_installed_status> if you
 918  need detailed information, or this method if you just need a yes/no
 919  answer.
 920  
 921  =item compare_versions($v1, $op, $v2)
 922  
 923  [version 0.28]
 924  
 925  Compares two module versions C<$v1> and C<$v2> using the operator
 926  C<$op>, which should be one of Perl's numeric operators like C<!=> or
 927  C<< >= >> or the like.  We do at least a halfway-decent job of
 928  handling versions that aren't strictly numeric, like C<0.27_02>, but
 929  exotic stuff will likely cause problems.
 930  
 931  In the future, the guts of this method might be replaced with a call
 932  out to C<version.pm>.
 933  
 934  =item config($key)
 935  
 936  =item config($key, $value)
 937  
 938  =item config() [deprecated]
 939  
 940  [version 0.22]
 941  
 942  With a single argument C<$key>, returns the value associated with that
 943  key in the C<Config.pm> hash, including any changes the author or user
 944  has specified.
 945  
 946  With C<$key> and C<$value> arguments, sets the value for future
 947  callers of C<config($key)>.
 948  
 949  With no arguments, returns a hash reference containing all such
 950  key-value pairs.  This usage is deprecated, though, because it's a
 951  resource hog and violates encapsulation.
 952  
 953  =item config_data($name)
 954  
 955  =item config_data($name => $value)
 956  
 957  [version 0.26]
 958  
 959  With a single argument, returns the value of the configuration
 960  variable C<$name>.  With two arguments, sets the given configuration
 961  variable to the given value.  The value may be any Perl scalar that's
 962  serializable with C<Data::Dumper>.  For instance, if you write a
 963  module that can use a MySQL or PostgreSQL back-end, you might create
 964  configuration variables called C<mysql_connect> and
 965  C<postgres_connect>, and set each to an array of connection parameters
 966  for C<< DBI->connect() >>.
 967  
 968  Configuration values set in this way using the Module::Build object
 969  will be available for querying during the build/test process and after
 970  installation via the generated C<...::ConfigData> module, as
 971  C<< ...::ConfigData->config($name) >>.
 972  
 973  The L<feature()|/"feature($name)"> and C<config_data()> methods represent
 974  Module::Build's main support for configuration of installed modules.
 975  See also L<Module::Build::Authoring/"SAVING CONFIGURATION INFORMATION">.
 976  
 977  =item conflicts()
 978  
 979  [version 0.21]
 980  
 981  Returns a hash reference indicating the C<conflicts> prerequisites
 982  that were passed to the C<new()> method.
 983  
 984  =item contains_pod($file)
 985  
 986  [version 0.20]
 987  
 988  [Deprecated] Please see L<Module::Build::ModuleInfo> instead.
 989  
 990  Returns true if the given file appears to contain POD documentation.
 991  Currently this checks whether the file has a line beginning with
 992  '=pod', '=head', or '=item', but the exact semantics may change in the
 993  future.
 994  
 995  =item copy_if_modified(%parameters)
 996  
 997  [version 0.19]
 998  
 999  Takes the file in the C<from> parameter and copies it to the file in
1000  the C<to> parameter, or the directory in the C<to_dir> parameter, if
1001  the file has changed since it was last copied (or if it doesn't exist
1002  in the new location).  By default the entire directory structure of
1003  C<from> will be copied into C<to_dir>; an optional C<flatten>
1004  parameter will copy into C<to_dir> without doing so.
1005  
1006  Returns the path to the destination file, or C<undef> if nothing
1007  needed to be copied.
1008  
1009  Any directories that need to be created in order to perform the
1010  copying will be automatically created.
1011  
1012  The destination file is set to read-only. If the source file has the
1013  executable bit set, then the destination file will be made executable.
1014  
1015  =item create_build_script()
1016  
1017  [version 0.05]
1018  
1019  Creates an executable script called C<Build> in the current directory
1020  that will be used to execute further user actions.  This script is
1021  roughly analogous (in function, not in form) to the Makefile created
1022  by C<ExtUtils::MakeMaker>.  This method also creates some temporary
1023  data in a directory called C<_build/>.  Both of these will be removed
1024  when the C<realclean> action is performed.
1025  
1026  Among the files created in C<_build/> is a F<_build/prereqs> file
1027  containing the set of prerequisites for this distribution, as a hash
1028  of hashes.  This file may be C<eval()>-ed to obtain the authoritative
1029  set of prereqs, which might be different from the contents of
1030  F<META.yml> (because F<Build.PL> might have set them dynamically).
1031  But fancy developers take heed: do not put any fancy custom runtime
1032  code in the F<_build/prereqs> file, leave it as a static declaration
1033  containing only strings and numbers.  Similarly, do not alter the
1034  structure of the internal C<< $self->{properties}{requires} >> (etc.)
1035  data members, because that's where this data comes from.
1036  
1037  =item current_action()
1038  
1039  [version 0.28]
1040  
1041  Returns the name of the currently-running action, such as "build" or
1042  "test".  This action is not necessarily the action that was originally
1043  invoked by the user.  For example, if the user invoked the "test"
1044  action, current_action() would initially return "test".  However,
1045  action "test" depends on action "code", so current_action() will
1046  return "code" while that dependency is being executed.  Once that
1047  action has completed, current_action() will again return "test".
1048  
1049  If you need to know the name of the original action invoked by the
1050  user, see L</invoked_action()> below.
1051  
1052  =item depends_on(@actions)
1053  
1054  [version 0.28]
1055  
1056  Invokes the named action or list of actions in sequence.  Using this
1057  method is preferred to calling the action explicitly because it
1058  performs some internal record-keeping, and it ensures that the same
1059  action is not invoked multiple times (note: in future versions of
1060  Module::Build it's conceivable that this run-only-once mechanism will
1061  be changed to something more intelligent).
1062  
1063  Note that the name of this method is something of a misnomer; it
1064  should really be called something like
1065  C<invoke_actions_unless_already_invoked()> or something, but for
1066  better or worse (perhaps better!) we were still thinking in
1067  C<make>-like dependency terms when we created this method.
1068  
1069  See also L<dispatch()|/"dispatch($action, %args)">.  The main
1070  distinction between the two is that C<depends_on()> is meant to call
1071  an action from inside another action, whereas C<dispatch()> is meant
1072  to set the very top action in motion.
1073  
1074  =item dir_contains($first_dir, $second_dir)
1075  
1076  [version 0.28]
1077  
1078  Returns true if the first directory logically contains the second
1079  directory.  This is just a convenience function because C<File::Spec>
1080  doesn't really provide an easy way to figure this out (but
1081  C<Path::Class> does...).
1082  
1083  =item dispatch($action, %args)
1084  
1085  [version 0.03]
1086  
1087  Invokes the build action C<$action>.  Optionally, a list of options
1088  and their values can be passed in.  This is equivalent to invoking an
1089  action at the command line, passing in a list of options.
1090  
1091  Custom options that have not been registered must be passed in as a
1092  hash reference in a key named "args":
1093  
1094    $build->dispatch('foo', verbose => 1, args => { my_option => 'value' });
1095  
1096  This method is intended to be used to programmatically invoke build
1097  actions, e.g. by applications controlling Module::Build-based builds
1098  rather than by subclasses.
1099  
1100  See also L<depends_on()|/"depends_on(@actions)">.  The main
1101  distinction between the two is that C<depends_on()> is meant to call
1102  an action from inside another action, whereas C<dispatch()> is meant
1103  to set the very top action in motion.
1104  
1105  =item dist_dir()
1106  
1107  [version 0.28]
1108  
1109  Returns the name of the directory that will be created during the
1110  C<dist> action.  The name is derived from the C<dist_name> and
1111  C<dist_version> properties.
1112  
1113  =item dist_name()
1114  
1115  [version 0.21]
1116  
1117  Returns the name of the current distribution, as passed to the
1118  C<new()> method in a C<dist_name> or modified C<module_name>
1119  parameter.
1120  
1121  =item dist_version()
1122  
1123  [version 0.21]
1124  
1125  Returns the version of the current distribution, as determined by the
1126  C<new()> method from a C<dist_version>, C<dist_version_from>, or
1127  C<module_name> parameter.
1128  
1129  =item do_system($cmd, @args)
1130  
1131  [version 0.21]
1132  
1133  This is a fairly simple wrapper around Perl's C<system()> built-in
1134  command.  Given a command and an array of optional arguments, this
1135  method will print the command to C<STDOUT>, and then execute it using
1136  Perl's C<system()>.  It returns true or false to indicate success or
1137  failure (the opposite of how C<system()> works, but more intuitive).
1138  
1139  Note that if you supply a single argument to C<do_system()>, it
1140  will/may be processed by the systems's shell, and any special
1141  characters will do their special things.  If you supply multiple
1142  arguments, no shell will get involved and the command will be executed
1143  directly.
1144  
1145  =item feature($name)
1146  
1147  =item feature($name => $value)
1148  
1149  [version 0.26]
1150  
1151  With a single argument, returns true if the given feature is set.
1152  With two arguments, sets the given feature to the given boolean value.
1153  In this context, a "feature" is any optional functionality of an
1154  installed module.  For instance, if you write a module that could
1155  optionally support a MySQL or PostgreSQL backend, you might create
1156  features called C<mysql_support> and C<postgres_support>, and set them
1157  to true/false depending on whether the user has the proper databases
1158  installed and configured.
1159  
1160  Features set in this way using the Module::Build object will be
1161  available for querying during the build/test process and after
1162  installation via the generated C<...::ConfigData> module, as
1163  C<< ...::ConfigData->feature($name) >>.
1164  
1165  The C<feature()> and C<config_data()> methods represent
1166  Module::Build's main support for configuration of installed modules.
1167  See also L<Module::Build::Authoring/"SAVING CONFIGURATION INFORMATION">.
1168  
1169  =item have_c_compiler()
1170  
1171  [version 0.21]
1172  
1173  Returns true if the current system seems to have a working C compiler.
1174  We currently determine this by attempting to compile a simple C source
1175  file and reporting whether the attempt was successful.
1176  
1177  =item install_base_relpaths()
1178  
1179  =item install_base_relpaths($type)
1180  
1181  =item install_base_relpaths($type => $path)
1182  
1183  [version 0.28]
1184  
1185  Set or retrieve the relative paths that are appended to
1186  C<install_base> for any installable element. This is useful if you
1187  want to set the relative install path for custom build elements.
1188  
1189  With no argument, it returns a reference to a hash containing all
1190  elements and their respective values. This hash should not be modified
1191  directly; use the multi-argument below form to change values.
1192  
1193  The single argument form returns the value associated with the
1194  element C<$type>.
1195  
1196  The multi-argument form allows you to set the paths for element types.
1197  C<$value> must be a relative path using unix-like paths.  (A series of
1198  directories seperated by slashes.  Eg 'foo/bar'.)  The return value is a
1199  localized path based on C<$value>.
1200  
1201  Assigning the value C<undef> to an element causes it to be removed.
1202  
1203  =item install_destination($type)
1204  
1205  [version 0.28]
1206  
1207  Returns the directory in which items of type C<$type> (e.g. C<lib>,
1208  C<arch>, C<bin>, or anything else returned by the L</install_types()>
1209  method) will be installed during the C<install> action.  Any settings
1210  for C<install_path>, C<install_base>, and C<prefix> are taken into
1211  account when determining the return value.
1212  
1213  =item install_path()
1214  
1215  =item install_path($type)
1216  
1217  =item install_path($type => $path)
1218  
1219  [version 0.28]
1220  
1221  Set or retrieve paths for specific installable elements. This is
1222  useful when you want to examine any explicit install paths specified
1223  by the user on the command line, or if you want to set the install
1224  path for a specific installable element based on another attribute
1225  like C<install_base()>.
1226  
1227  With no argument, it returns a reference to a hash containing all
1228  elements and their respective values. This hash should not be modified
1229  directly; use the multi-argument below form to change values.
1230  
1231  The single argument form returns the value associated with the
1232  element C<$type>.
1233  
1234  The multi-argument form allows you to set the paths for element types.
1235  The supplied C<$path> should be an absolute path to install elements
1236  of C<$type>.  The return value is C<$path>.
1237  
1238  Assigning the value C<undef> to an element causes it to be removed.
1239  
1240  =item install_types()
1241  
1242  [version 0.28]
1243  
1244  Returns a list of installable types that this build knows about.
1245  These types each correspond to the name of a directory in F<blib/>,
1246  and the list usually includes items such as C<lib>, C<arch>, C<bin>,
1247  C<script>, C<libdoc>, C<bindoc>, and if HTML documentation is to be
1248  built, C<libhtml> and C<binhtml>.  Other user-defined types may also
1249  exist.
1250  
1251  =item invoked_action()
1252  
1253  [version 0.28]
1254  
1255  This is the name of the original action invoked by the user.  This
1256  value is set when the user invokes F<Build.PL>, the F<Build> script,
1257  or programatically through the L<dispatch()|/"dispatch($action, %args)">
1258  method.  It does not change as sub-actions are executed as
1259  dependencies are evaluated.
1260  
1261  To get the name of the currently executing dependency, see
1262  L</current_action()> above.
1263  
1264  =item notes()
1265  
1266  =item notes($key)
1267  
1268  =item notes($key => $value)
1269  
1270  [version 0.20]
1271  
1272  The C<notes()> value allows you to store your own persistent
1273  information about the build, and to share that information among
1274  different entities involved in the build.  See the example in the
1275  C<current()> method.
1276  
1277  The C<notes()> method is essentally a glorified hash access.  With no
1278  arguments, C<notes()> returns the entire hash of notes.  With one argument,
1279  C<notes($key)> returns the value associated with the given key.  With two
1280  arguments, C<notes($key, $value)> sets the value associated with the given key
1281  to C<$value> and returns the new value.
1282  
1283  The lifetime of the C<notes> data is for "a build" - that is, the
1284  C<notes> hash is created when C<perl Build.PL> is run (or when the
1285  C<new()> method is run, if the Module::Build Perl API is being used
1286  instead of called from a shell), and lasts until C<perl Build.PL> is
1287  run again or the C<clean> action is run.
1288  
1289  =item orig_dir()
1290  
1291  [version 0.28]
1292  
1293  Returns a string containing the working directory that was in effect
1294  before the F<Build> script chdir()-ed into the C<base_dir>.  This
1295  might be useful for writing wrapper tools that might need to chdir()
1296  back out.
1297  
1298  =item os_type()
1299  
1300  [version 0.04]
1301  
1302  If you're subclassing Module::Build and some code needs to alter its
1303  behavior based on the current platform, you may only need to know
1304  whether you're running on Windows, Unix, MacOS, VMS, etc., and not the
1305  fine-grained value of Perl's C<$^O> variable.  The C<os_type()> method
1306  will return a string like C<Windows>, C<Unix>, C<MacOS>, C<VMS>, or
1307  whatever is appropriate.  If you're running on an unknown platform, it
1308  will return C<undef> - there shouldn't be many unknown platforms
1309  though.
1310  
1311  =item is_vmsish()
1312  
1313  =item is_windowsish()
1314  
1315  =item is_unixish()
1316  
1317  Convenience functions that return a boolean value indicating whether
1318  this platform behaves respectively like VMS, Windows, or Unix.  For
1319  arbitrary reasons other platforms don't get their own such functions,
1320  at least not yet.
1321  
1322  
1323  =item prefix_relpaths()
1324  
1325  =item prefix_relpaths($installdirs)
1326  
1327  =item prefix_relpaths($installdirs, $type)
1328  
1329  =item prefix_relpaths($installdirs, $type => $path)
1330  
1331  [version 0.28]
1332  
1333  Set or retrieve the relative paths that are appended to C<prefix> for
1334  any installable element.  This is useful if you want to set the
1335  relative install path for custom build elements.
1336  
1337  With no argument, it returns a reference to a hash containing all
1338  elements and their respective values as defined by the current
1339  C<installdirs> setting.
1340  
1341  With a single argument, it returns a reference to a hash containing
1342  all elements and their respective values as defined by
1343  C<$installdirs>.
1344  
1345  The hash returned by the above calls should not be modified directly;
1346  use the three-argument below form to change values.
1347  
1348  The two argument form returns the value associated with the
1349  element C<$type>.
1350  
1351  The multi-argument form allows you to set the paths for element types.
1352  C<$value> must be a relative path using unix-like paths.  (A series of
1353  directories seperated by slashes.  Eg 'foo/bar'.)  The return value is a
1354  localized path based on C<$value>.
1355  
1356  Assigning the value C<undef> to an element causes it to be removed.
1357  
1358  =item prepare_metadata()
1359  
1360  [version 0.28]
1361  
1362  This method is provided for authors to override to customize the
1363  fields of F<META.yml>.  It is passed a YAML::Node node object which can
1364  be modified as desired and then returned.  E.g.
1365  
1366    package My::Builder;
1367    use base 'Module::Build';
1368  
1369    sub prepare_metadata {
1370      my $self = shift;
1371      my $node = $self->SUPER::prepare_metadata( shift );
1372      $node->{custom_field} = 'foo';
1373      return $node;
1374    }
1375  
1376  =item prereq_failures()
1377  
1378  [version 0.11]
1379  
1380  Returns a data structure containing information about any failed
1381  prerequisites (of any of the types described above), or C<undef> if
1382  all prerequisites are met.
1383  
1384  The data structure returned is a hash reference.  The top level keys
1385  are the type of prerequisite failed, one of "requires",
1386  "build_requires", "conflicts", or "recommends".  The associated values
1387  are hash references whose keys are the names of required (or
1388  conflicting) modules.  The associated values of those are hash
1389  references indicating some information about the failure.  For example:
1390  
1391    {
1392     have => '0.42',
1393     need => '0.59',
1394     message => 'Version 0.42 is installed, but we need version 0.59',
1395    }
1396  
1397  or
1398  
1399    {
1400     have => '<none>',
1401     need => '0.59',
1402     message => 'Prerequisite Foo isn't installed',
1403    }
1404  
1405  This hash has the same structure as the hash returned by the
1406  C<check_installed_status()> method, except that in the case of
1407  "conflicts" dependencies we change the "need" key to "conflicts" and
1408  construct a proper message.
1409  
1410  Examples:
1411  
1412    # Check a required dependency on Foo::Bar
1413    if ( $build->prereq_failures->{requires}{Foo::Bar} ) { ...
1414  
1415    # Check whether there were any failures
1416    if ( $build->prereq_failures ) { ...
1417  
1418    # Show messages for all failures
1419    my $failures = $build->prereq_failures;
1420    while (my ($type, $list) = each %$failures) {
1421      while (my ($name, $hash) = each %$list) {
1422        print "Failure for $name: $hash->{message}\n";
1423      }
1424    }
1425  
1426  =item prereq_report()
1427  
1428  [version 0.28]
1429  
1430  Returns a human-readable (table-form) string showing all
1431  prerequisites, the versions required, and the versions actually
1432  installed.  This can be useful for reviewing the configuration of your
1433  system prior to a build, or when compiling data to send for a bug
1434  report.  The C<prereq_report> action is just a thin wrapper around the
1435  C<prereq_report()> method.
1436  
1437  =item prompt($message, $default)
1438  
1439  [version 0.12]
1440  
1441  Asks the user a question and returns their response as a string.  The
1442  first argument specifies the message to display to the user (for
1443  example, C<"Where do you keep your money?">).  The second argument,
1444  which is optional, specifies a default answer (for example,
1445  C<"wallet">).  The user will be asked the question once.
1446  
1447  If C<prompt()> detects that it is not running interactively and there
1448  is nothing on STDIN or if the PERL_MM_USE_DEFAULT environment variable
1449  is set to true, the $default will be used without prompting.
1450  
1451  To prevent automated processes from blocking, the user must either set
1452  PERL_MM_USE_DEFAULT or attach something to STDIN (this can be a
1453  pipe/file containing a scripted set of answers or /dev/null.)
1454  
1455  If no $default is provided an empty string will be used instead.  In
1456  non-interactive mode, the absence of $default is an error (though
1457  explicitly passing C<undef()> as the default is valid as of 0.27.)
1458  
1459  This method may be called as a class or object method.
1460  
1461  =item recommends()
1462  
1463  [version 0.21]
1464  
1465  Returns a hash reference indicating the C<recommends> prerequisites
1466  that were passed to the C<new()> method.
1467  
1468  =item requires()
1469  
1470  [version 0.21]
1471  
1472  Returns a hash reference indicating the C<requires> prerequisites that
1473  were passed to the C<new()> method.
1474  
1475  =item rscan_dir($dir, $pattern)
1476  
1477  [version 0.28]
1478  
1479  Uses C<File::Find> to traverse the directory C<$dir>, returning a
1480  reference to an array of entries matching C<$pattern>.  C<$pattern>
1481  may either be a regular expression (using C<qr//> or just a plain
1482  string), or a reference to a subroutine that will return true for
1483  wanted entries.  If C<$pattern> is not given, all entries will be
1484  returned.
1485  
1486  Examples:
1487  
1488   # All the *.pm files in lib/
1489   $m->rscan_dir('lib', qr/\.pm$/)
1490  
1491   # All the files in blib/ that aren't *.html files
1492   $m->rscan_dir('blib', sub {-f $_ and not /\.html$/});
1493  
1494   # All the files in t/
1495   $m->rscan_dir('t');
1496  
1497  =item runtime_params()
1498  
1499  =item runtime_params($key)
1500  
1501  [version 0.28]
1502  
1503  The C<runtime_params()> method stores the values passed on the command line
1504  for valid properties (that is, any command line options for which
1505  C<valid_property()> returns a true value).  The value on the command line may
1506  override the default value for a property, as well as any value specified in a
1507  call to C<new()>.  This allows you to programmatically tell if C<perl Build.PL>
1508  or any execution of C<./Build> had command line options specified that
1509  override valid properties.
1510  
1511  The C<runtime_params()> method is essentally a glorified read-only hash.  With
1512  no arguments, C<runtime_params()> returns the entire hash of properties
1513  specified on the command line.  With one argument, C<runtime_params($key)>
1514  returns the value associated with the given key.
1515  
1516  The lifetime of the C<runtime_params> data is for "a build" - that is, the
1517  C<runtime_params> hash is created when C<perl Build.PL> is run (or when the
1518  C<new()> method is called, if the Module::Build Perl API is being used instead
1519  of called from a shell), and lasts until C<perl Build.PL> is run again or the
1520  C<clean> action is run.
1521  
1522  =item script_files()
1523  
1524  [version 0.18]
1525  
1526  Returns a hash reference whose keys are the perl script files to be
1527  installed, if any.  This corresponds to the C<script_files> parameter to the
1528  C<new()> method.  With an optional argument, this parameter may be set
1529  dynamically.
1530  
1531  For backward compatibility, the C<scripts()> method does exactly the
1532  same thing as C<script_files()>.  C<scripts()> is deprecated, but it
1533  will stay around for several versions to give people time to
1534  transition.
1535  
1536  =item up_to_date($source_file, $derived_file)
1537  
1538  =item up_to_date(\@source_files, \@derived_files)
1539  
1540  [version 0.20]
1541  
1542  This method can be used to compare a set of source files to a set of
1543  derived files.  If any of the source files are newer than any of the
1544  derived files, it returns false.  Additionally, if any of the derived
1545  files do not exist, it returns false.  Otherwise it returns true.
1546  
1547  The arguments may be either a scalar or an array reference of file
1548  names.
1549  
1550  =item y_n($message, $default)
1551  
1552  [version 0.12]
1553  
1554  Asks the user a yes/no question using C<prompt()> and returns true or
1555  false accordingly.  The user will be asked the question repeatedly
1556  until they give an answer that looks like "yes" or "no".
1557  
1558  The first argument specifies the message to display to the user (for
1559  example, C<"Shall I invest your money for you?">), and the second
1560  argument specifies the default answer (for example, C<"y">).
1561  
1562  Note that the default is specified as a string like C<"y"> or C<"n">,
1563  and the return value is a Perl boolean value like 1 or 0.  I thought
1564  about this for a while and this seemed like the most useful way to do
1565  it.
1566  
1567  This method may be called as a class or object method.
1568  
1569  =back
1570  
1571  
1572  =head2 Autogenerated Accessors
1573  
1574  In addition to the aforementioned methods, there are also some get/set
1575  accessor methods for the following properties:
1576  
1577  =over 4
1578  
1579  =item PL_files()
1580  
1581  =item allow_mb_mismatch()
1582  
1583  =item autosplit()
1584  
1585  =item base_dir()
1586  
1587  =item bindoc_dirs()
1588  
1589  =item blib()
1590  
1591  =item build_bat()
1592  
1593  =item build_class()
1594  
1595  =item build_elements()
1596  
1597  =item build_requires()
1598  
1599  =item build_script()
1600  
1601  =item c_source()
1602  
1603  =item config_dir()
1604  
1605  =item configure_requires()
1606  
1607  =item conflicts()
1608  
1609  =item create_makefile_pl()
1610  
1611  =item create_packlist()
1612  
1613  =item create_readme()
1614  
1615  =item debugger()
1616  
1617  =item destdir()
1618  
1619  =item get_options()
1620  
1621  =item html_css()
1622  
1623  =item include_dirs()
1624  
1625  =item install_base()
1626  
1627  =item install_sets()
1628  
1629  =item installdirs()
1630  
1631  =item libdoc_dirs()
1632  
1633  =item license()
1634  
1635  =item magic_number()
1636  
1637  =item mb_version()
1638  
1639  =item meta_add()
1640  
1641  =item meta_merge()
1642  
1643  =item metafile()
1644  
1645  =item module_name()
1646  
1647  =item orig_dir()
1648  
1649  =item original_prefix()
1650  
1651  =item perl()
1652  
1653  =item pm_files()
1654  
1655  =item pod_files()
1656  
1657  =item pollute()
1658  
1659  =item prefix()
1660  
1661  =item prereq_action_types()
1662  
1663  =item quiet()
1664  
1665  =item recommends()
1666  
1667  =item recurse_into()
1668  
1669  =item recursive_test_files()
1670  
1671  =item requires()
1672  
1673  =item scripts()
1674  
1675  =item use_rcfile()
1676  
1677  =item verbose()
1678  
1679  =item xs_files()
1680  
1681  =back
1682  
1683  
1684  =head1 MODULE METADATA
1685  
1686  If you would like to add other useful metadata, C<Module::Build>
1687  supports this with the C<meta_add> and C<meta_merge> arguments to
1688  L</new>. The authoritative list of supported metadata can be found at
1689  L<http://module-build.sourceforge.net/META-spec-current.html>, but for
1690  convenience - here are a few of the more useful ones:
1691  
1692  =over 4
1693  
1694  =item keywords
1695  
1696  For describing the distribution using keyword (or "tags") in order to
1697  make CPAN.org indexing and search more efficient and useful.
1698  
1699  See L<http://module-build.sourceforge.net/META-spec-current.html#keywords>.
1700  
1701  =item resources
1702  
1703  A list of additional resources available for users of the
1704  distribution. This can include links to a homepage on the web, a
1705  bugtracker, the repository location, a even subscription page for the
1706  distribution mailing list.
1707  
1708  See L<http://module-build.sourceforge.net/META-spec-current.html#resources>.
1709  
1710  =back
1711  
1712  
1713  =head1 AUTHOR
1714  
1715  Ken Williams <kwilliams@cpan.org>
1716  
1717  
1718  =head1 COPYRIGHT
1719  
1720  Copyright (c) 2001-2006 Ken Williams.  All rights reserved.
1721  
1722  This library is free software; you can redistribute it and/or
1723  modify it under the same terms as Perl itself.
1724  
1725  
1726  =head1 SEE ALSO
1727  
1728  perl(1), L<Module::Build>(3), L<Module::Build::Authoring>(3),
1729  L<Module::Build::Cookbook>(3), L<ExtUtils::MakeMaker>(3), L<YAML>(3)
1730  
1731  F<META.yml> Specification:
1732  L<http://module-build.sourceforge.net/META-spec-current.html>
1733  
1734  =cut