view release on metacpan or  search on metacpan

local/lib/perl5/Module/Build/API.pod  view on Meta::CPAN

=head1 NAME

Module::Build::API - API Reference for Module Authors

=for :stopwords apache bsd distdir distsign gpl installdirs lgpl mit mozilla packlists

=head1 DESCRIPTION

I list here some of the most important methods in C<Module::Build>.
Normally you won't need to deal with these methods unless you want to
subclass C<Module::Build>.  But since one of the reasons I created
this module in the first place was so that subclassing is possible
(and easy), I will certainly write more docs as the interface
stabilizes.


=head2 CONSTRUCTORS

=over 4

=item current()

[version 0.20]

This method returns a reasonable facsimile of the currently-executing
C<Module::Build> object representing the current build.  You can use
this object to query its L</notes()> method, inquire about installed
modules, and so on.  This is a great way to share information between
different parts of your build process.  For instance, you can ask
the user a question during C<perl Build.PL>, then use their answer
during a regression test:

  # In Build.PL:
  my $color = $build->prompt("What is your favorite color?");
  $build->notes(color => $color);

  # In t/colortest.t:
  use Module::Build;
  my $build = Module::Build->current;
  my $color = $build->notes('color');
  ...

The way the C<current()> method is currently implemented, there may be
slight differences between the C<$build> object in Build.PL and the
one in C<t/colortest.t>.  It is our goal to minimize these differences
in future releases of Module::Build, so please report any anomalies
you find.

One important caveat: in its current implementation, C<current()> will
B<NOT> work correctly if you have changed out of the directory that
C<Module::Build> was invoked from.

=item new()

[version 0.03]

Creates a new Module::Build object.  Arguments to the new() method are
listed below.  Most arguments are optional, but you must provide
either the L</module_name> argument, or L</dist_name> and one of
L</dist_version> or L</dist_version_from>.  In other words, you must
provide enough information to determine both a distribution name and
version.


=over 4

=item add_to_cleanup

[version 0.19]

An array reference of files to be cleaned up when the C<clean> action
is performed. See also the L<add_to_cleanup()|/"add_to_cleanup(@files)">
method.

=item allow_pureperl

[version 0.4005]

A bool indicating the module is still functional without its xs parts.
When an XS module is build with --pureperl_only, it will otherwise fail.

=item auto_configure_requires

[version 0.34]

This parameter determines whether Module::Build will add itself
automatically to configure_requires (and build_requires) if Module::Build
is not already there.  The required version will be the last 'major' release,
as defined by the decimal version truncated to two decimal places (e.g. 0.34,
instead of 0.3402).  The default value is true.

=item auto_features

[version 0.26]

local/lib/perl5/Module/Build/API.pod  view on Meta::CPAN

references indicating some information about the failure.  For example:

  {
   have => '0.42',
   need => '0.59',
   message => 'Version 0.42 is installed, but we need version 0.59',
  }

or

  {
   have => '<none>',
   need => '0.59',
   message => 'Prerequisite Foo isn't installed',
  }

This hash has the same structure as the hash returned by the
C<check_installed_status()> method, except that in the case of
"conflicts" dependencies we change the "need" key to "conflicts" and
construct a proper message.

Examples:

  # Check a required dependency on Foo::Bar
  if ( $build->prereq_failures->{requires}{Foo::Bar} ) { ...

  # Check whether there were any failures
  if ( $build->prereq_failures ) { ...

  # Show messages for all failures
  my $failures = $build->prereq_failures;
  while (my ($type, $list) = each %$failures) {
    while (my ($name, $hash) = each %$list) {
      print "Failure for $name: $hash->{message}\n";
    }
  }

=item prereq_data()

[version 0.32]

Returns a reference to a hash describing all prerequisites.  The keys of the
hash will be the various prerequisite types ('requires', 'build_requires',
'test_requires', 'configure_requires', 'recommends', or 'conflicts') and the values will be
references to hashes of module names and version numbers.  Only prerequisites
types that are defined will be included.  The C<prereq_data> action is just a
thin wrapper around the C<prereq_data()> method and dumps the hash as a string
that can be loaded using C<eval()>.

=item prereq_report()

[version 0.28]

Returns a human-readable (table-form) string showing all
prerequisites, the versions required, and the versions actually
installed.  This can be useful for reviewing the configuration of your
system prior to a build, or when compiling data to send for a bug
report.  The C<prereq_report> action is just a thin wrapper around the
C<prereq_report()> method.

=item prompt($message, $default)

[version 0.12]

Asks the user a question and returns their response as a string.  The
first argument specifies the message to display to the user (for
example, C<"Where do you keep your money?">).  The second argument,
which is optional, specifies a default answer (for example,
C<"wallet">).  The user will be asked the question once.

If C<prompt()> detects that it is not running interactively and there
is nothing on STDIN or if the PERL_MM_USE_DEFAULT environment variable
is set to true, the $default will be used without prompting.

To prevent automated processes from blocking, the user must either set
PERL_MM_USE_DEFAULT or attach something to STDIN (this can be a
pipe/file containing a scripted set of answers or /dev/null.)

If no $default is provided an empty string will be used instead.  In
non-interactive mode, the absence of $default is an error (though
explicitly passing C<undef()> as the default is valid as of 0.27.)

This method may be called as a class or object method.

=item recommends()

[version 0.21]

Returns a hash reference indicating the C<recommends> prerequisites
that were passed to the C<new()> method.

=item requires()

[version 0.21]

Returns a hash reference indicating the C<requires> prerequisites that
were passed to the C<new()> method.

=item rscan_dir($dir, $pattern)

[version 0.28]

Uses C<File::Find> to traverse the directory C<$dir>, returning a
reference to an array of entries matching C<$pattern>.  C<$pattern>
may either be a regular expression (using C<qr//> or just a plain
string), or a reference to a subroutine that will return true for
wanted entries.  If C<$pattern> is not given, all entries will be
returned.

Examples:

 # All the *.pm files in lib/
 $m->rscan_dir('lib', qr/\.pm$/)

 # All the files in blib/ that aren't *.html files
 $m->rscan_dir('blib', sub {-f $_ and not /\.html$/});

 # All the files in t/
 $m->rscan_dir('t');

=item runtime_params()

=item runtime_params($key)

[version 0.28]

The C<runtime_params()> method stores the values passed on the command line
for valid properties (that is, any command line options for which
C<valid_property()> returns a true value).  The value on the command line may
override the default value for a property, as well as any value specified in a
call to C<new()>.  This allows you to programmatically tell if C<perl Build.PL>
or any execution of C<./Build> had command line options specified that
override valid properties.

The C<runtime_params()> method is essentially a glorified read-only hash.  With
no arguments, C<runtime_params()> returns the entire hash of properties
specified on the command line.  With one argument, C<runtime_params($key)>
returns the value associated with the given key.

The lifetime of the C<runtime_params> data is for "a build" - that is, the
C<runtime_params> hash is created when C<perl Build.PL> is run (or when the
C<new()> method is called, if the Module::Build Perl API is being used instead
of called from a shell), and lasts until C<perl Build.PL> is run again or the
C<clean> action is run.

=item script_files()

[version 0.18]

Returns a hash reference whose keys are the perl script files to be
installed, if any.  This corresponds to the C<script_files> parameter to the
C<new()> method.  With an optional argument, this parameter may be set
dynamically.

For backward compatibility, the C<scripts()> method does exactly the
same thing as C<script_files()>.  C<scripts()> is deprecated, but it
will stay around for several versions to give people time to
transition.

=item up_to_date($source_file, $derived_file)

=item up_to_date(\@source_files, \@derived_files)

[version 0.20]

This method can be used to compare a set of source files to a set of
derived files.  If any of the source files are newer than any of the
derived files, it returns false.  Additionally, if any of the derived
files do not exist, it returns false.  Otherwise it returns true.

The arguments may be either a scalar or an array reference of file
names.

=item y_n($message, $default)

[version 0.12]

Asks the user a yes/no question using C<prompt()> and returns true or
false accordingly.  The user will be asked the question repeatedly
until they give an answer that looks like "yes" or "no".

The first argument specifies the message to display to the user (for
example, C<"Shall I invest your money for you?">), and the second
argument specifies the default answer (for example, C<"y">).

Note that the default is specified as a string like C<"y"> or C<"n">,
and the return value is a Perl boolean value like 1 or 0.  I thought
about this for a while and this seemed like the most useful way to do
it.

This method may be called as a class or object method.

=back


=head2 Autogenerated Accessors

In addition to the aforementioned methods, there are also some get/set
accessor methods for the following properties:

=over 4

=item PL_files()

=item allow_mb_mismatch()

=item allow_pureperl()

=item auto_configure_requires()

=item autosplit()

=item base_dir()

=item bindoc_dirs()

=item blib()

=item build_bat()

=item build_class()

=item build_elements()

=item build_requires()

=item build_script()

=item bundle_inc()

=item bundle_inc_preload()

=item c_source()

=item config_dir()

=item configure_requires()