Acme-Sort-Sleep

 view release on metacpan or  search on metacpan

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

    (
     module_name => 'Foo::Bar',
     ...
     pm_files => { 'Bar.pm' => 'lib/Foo/Bar.pm' },
    );

Note that the values should include C<lib/>, because this is where
they would be found in a "normal" Module::Build-style distribution.

Note also that the path specifications are I<always> given in
Unix-like format, not in the style of the local system.

=item pod_files

[version 0.19]

Just like C<pm_files>, but used for specifying the set of C<.pod>
files in your distribution.

=item recommends

[version 0.08]

This is just like the L</requires> argument, except that modules listed
in this section aren't essential, just a good idea.  We'll just print
a friendly warning if one of these modules aren't found, but we'll
continue running.

If a module is recommended but not required, all tests should still
pass if the module isn't installed.  This may mean that some tests
may be skipped if recommended dependencies aren't present.

Automated tools like CPAN.pm should inform the user when recommended
modules aren't installed, and it should offer to install them if it
wants to be helpful.

See the documentation for L<Module::Build::Authoring/"PREREQUISITES">
for the details of how requirements can be specified.

=item recursive_test_files

[version 0.28]

Normally, C<Module::Build> does not search subdirectories when looking
for tests to run. When this options is set it will search recursively
in all subdirectories of the standard 't' test directory.

=item release_status

[version 0.37]

The CPAN Meta Spec version 2 adds C<release_status> to allow authors
to specify how a distribution should be indexed.  Consistent with the
spec, this parameter can only have one three values: 'stable',
'testing' or 'unstable'.

Unless explicitly set by the author, C<release_status> will default
to 'stable' unless C<dist_version> contains an underscore, in which
case it will default to 'testing'.

It is an error to specify a C<release_status> of 'stable' when
C<dist_version> contains an underscore character.

=item requires

[version 0.07]

An optional C<requires> argument specifies any module prerequisites
that the current module depends on.

One note: currently C<Module::Build> doesn't actually I<require> the
user to have dependencies installed, it just strongly urges.  In the
future we may require it.  There's also a L</recommends> section for
things that aren't absolutely required.

Automated tools like CPAN.pm should refuse to install a module if one
of its dependencies isn't satisfied, unless a "force" command is given
by the user.  If the tools are helpful, they should also offer to
install the dependencies.

A synonym for C<requires> is C<prereq>, to help succour people
transitioning from C<ExtUtils::MakeMaker>.  The C<requires> term is
preferred, but the C<prereq> term will remain valid in future
distributions.

See the documentation for L<Module::Build::Authoring/"PREREQUISITES">
for the details of how requirements can be specified.

=item script_files

[version 0.18]

An optional parameter specifying a set of files that should be
installed as executable Perl scripts when the module is installed.
May be given as an array reference of the files, as a hash reference
whose keys are the files (and whose values will currently be ignored),
as a string giving the name of a directory in which to find scripts,
or as a string giving the name of a single script file.

The default is to install any scripts found in a F<bin> directory at
the top level of the distribution, minus any keys of L<PL_files>.

For backward compatibility, you may use the parameter C<scripts>
instead of C<script_files>.  Please consider this usage deprecated,
though it will continue to exist for several version releases.

=item share_dir

[version 0.36]

An optional parameter specifying directories of static data files to
be installed as read-only files for use with L<File::ShareDir>.  The
C<share_dir> property supports both distribution-level and
module-level share files.

The simplest use of C<share_dir> is to set it to a directory name or an
arrayref of directory names containing files to be installed in the
distribution-level share directory.

  share_dir => 'share'

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

therefore be sure to add TAP::Harness as a requirement for your module in
L</build_requires>. Implicitly set to a true value if C<tap_harness_args> is
specified.

=item xs_files

[version 0.19]

Just like C<pm_files>, but used for specifying the set of C<.xs>
files in your distribution.

=back


=item new_from_context(%args)

[version 0.28]

When called from a directory containing a F<Build.PL> script (in other words,
the base directory of a distribution), this method will run the F<Build.PL> and
call C<resume()> to return the resulting C<Module::Build> object to the caller.
Any key-value arguments given to C<new_from_context()> are essentially like
command line arguments given to the F<Build.PL> script, so for example you
could pass C<< verbose => 1 >> to this method to turn on verbosity.

=item resume()

[version 0.03]

You'll probably never call this method directly, it's only called from the
auto-generated C<Build> script (and the C<new_from_context> method).  The
C<new()> method is only called once, when the user runs C<perl Build.PL>.
Thereafter, when the user runs C<Build test> or another action, the
C<Module::Build> object is created using the C<resume()> method to
re-instantiate with the settings given earlier to C<new()>.

=item subclass()

[version 0.06]

This creates a new C<Module::Build> subclass on the fly, as described
in the L<Module::Build::Authoring/"SUBCLASSING"> section.  The caller
must provide either a C<class> or C<code> parameter, or both.  The
C<class> parameter indicates the name to use for the new subclass, and
defaults to C<MyModuleBuilder>.  The C<code> parameter specifies Perl
code to use as the body of the subclass.

=item add_property

[version 0.31]

  package 'My::Build';
  use base 'Module::Build';
  __PACKAGE__->add_property( 'pedantic' );
  __PACKAGE__->add_property( answer => 42 );
  __PACKAGE__->add_property(
     'epoch',
      default => sub { time },
      check   => sub {
          return 1 if /^\d+$/;
          shift->property_error( "'$_' is not an epoch time" );
          return 0;
      },
  );

Adds a property to a Module::Build class. Properties are those attributes of a
Module::Build object which can be passed to the constructor and which have
accessors to get and set them. All of the core properties, such as
C<module_name> and C<license>, are defined using this class method.

The first argument to C<add_property()> is always the name of the property.
The second argument can be either a default value for the property, or a list
of key/value pairs. The supported keys are:

=over

=item C<default>

The default value. May optionally be specified as a code reference, in which
case the return value from the execution of the code reference will be used.
If you need the default to be a code reference, just use a code reference to
return it, e.g.:

      default => sub { sub { ... } },

=item C<check>

A code reference that checks that a value specified for the property is valid.
During the execution of the code reference, the new value will be included in
the C<$_> variable. If the value is correct, the C<check> code reference
should return true. If the value is not correct, it sends an error message to
C<property_error()> and returns false.

=back

When this method is called, a new property will be installed in the
Module::Build class, and an accessor will be built to allow the property to be
get or set on the build object.

  print $build->pedantic, $/;
  $build->pedantic(0);

If the default value is a hash reference, this generates a special-case
accessor method, wherein individual key/value pairs may be set or fetched:

  print "stuff{foo} is: ", $build->stuff( 'foo' ), $/;
  $build->stuff( foo => 'bar' );
  print $build->stuff( 'foo' ), $/; # Outputs "bar"

Of course, you can still set the entire hash reference at once, as well:

  $build->stuff( { foo => 'bar', baz => 'yo' } );

In either case, if a C<check> has been specified for the property, it will be
applied to the entire hash. So the check code reference should look something
like:

      check => sub {
            return 1 if defined $_ && exists $_->{foo};
            shift->property_error(qq{Property "stuff" needs "foo"});
            return 0;
      },

=item property_error

[version 0.31]

=back


=head2 METHODS

=over 4

=item add_build_element($type)

[version 0.26]

Adds a new type of entry to the build process.  Accepts a single
string specifying its type-name.  There must also be a method defined
to process things of that type, e.g. if you add a build element called
C<'foo'>, then you must also define a method called
C<process_foo_files()>.

See also
L<Module::Build::Cookbook/"Adding new file types to the build process">.

=item add_to_cleanup(@files)

[version 0.03]

You may call C<< $self->add_to_cleanup(@patterns) >> to tell
C<Module::Build> that certain files should be removed when the user
performs the C<Build clean> action.  The arguments to the method are
patterns suitable for passing to Perl's C<glob()> function, specified
in either Unix format or the current machine's native format.  It's
usually convenient to use Unix format when you hard-code the filenames
(e.g. in F<Build.PL>) and the native format when the names are
programmatically generated (e.g. in a testing script).

I decided to provide a dynamic method of the C<$build> object, rather
than just use a static list of files named in the F<Build.PL>, because
these static lists can get difficult to manage.  I usually prefer to
keep the responsibility for registering temporary files close to the
code that creates them.

=item args()

[version 0.26]

  my $args_href = $build->args;
  my %args = $build->args;
  my $arg_value = $build->args($key);
  $build->args($key, $value);

This method is the preferred interface for retrieving the arguments passed via
command line options to F<Build.PL> or F<Build>, minus the Module-Build
specific options.

When called in a scalar context with no arguments, this method returns a
reference to the hash storing all of the arguments; in an array context, it
returns the hash itself.  When passed a single argument, it returns the value
stored in the args hash for that option key.  When called with two arguments,
the second argument is assigned to the args hash under the key passed as the
first argument.

=item autosplit_file($from, $to)

[version 0.28]

Invokes the L<AutoSplit> module on the C<$from> file, sending the
output to the C<lib/auto> directory inside C<$to>.  C<$to> is
typically the C<blib/> directory.

=item base_dir()

[version 0.14]

Returns a string containing the root-level directory of this build,
i.e. where the C<Build.PL> script and the C<lib> directory can be
found.  This is usually the same as the current working directory,
because the C<Build> script will C<chdir()> into this directory as
soon as it begins execution.

=item build_requires()

[version 0.21]

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

=item can_action( $action )

Returns a reference to the method that defines C<$action>, or false
otherwise. This is handy for actions defined (or maybe not!) in subclasses.

[version 0.32_xx]

=item cbuilder()

[version 0.2809]

Returns the internal ExtUtils::CBuilder object that can be used for
compiling & linking C code.  If no such object is available (e.g. if
the system has no compiler installed) an exception will be thrown.

=item check_installed_status($module, $version)

[version 0.11]

This method returns a hash reference indicating whether a version
dependency on a certain module is satisfied.  The C<$module> argument
is given as a string like C<"Data::Dumper"> or C<"perl">, and the
C<$version> argument can take any of the forms described in L</requires>
above.  This allows very fine-grained version checking.

The returned hash reference has the following structure:

  {
   ok => $whether_the_dependency_is_satisfied,
   have => $version_already_installed,
   need => $version_requested, # Same as incoming $version argument
   message => $informative_error_message,
  }

If no version of C<$module> is currently installed, the C<have> value
will be the string C<< "<none>" >>.  Otherwise the C<have> value will
simply be the version of the installed module.  Note that this means
that if C<$module> is installed but doesn't define a version number,
the C<have> value will be C<undef> - this is why we don't use C<undef>
for the case when C<$module> isn't installed at all.

This method may be called either as an object method
(C<< $build->check_installed_status($module, $version) >>)
or as a class method
(C<< Module::Build->check_installed_status($module, $version) >>).

=item check_installed_version($module, $version)

[version 0.05]

Like L<check_installed_status()|/"check_installed_status($module, $version)">,
but simply returns true or false depending on whether module
C<$module> satisfies the dependency C<$version>.

If the check succeeds, the return value is the actual version of
C<$module> installed on the system.  This allows you to do the
following:

  my $installed = $build->check_installed_version('DBI', '1.15');
  if ($installed) {
    print "Congratulations, version $installed of DBI is installed.\n";
  } else {
    die "Sorry, you must install DBI.\n";
  }

If the check fails, we return false and set C<$@> to an informative
error message.

If C<$version> is any non-true value (notably zero) and any version of
C<$module> is installed, we return true.  In this case, if C<$module>
doesn't define a version, or if its version is zero, we return the
special value "0 but true", which is numerically zero, but logically
true.

In general you might prefer to use C<check_installed_status> if you
need detailed information, or this method if you just need a yes/no
answer.

=item compare_versions($v1, $op, $v2)

[version 0.28]

Compares two module versions C<$v1> and C<$v2> using the operator
C<$op>, which should be one of Perl's numeric operators like C<!=> or
C<< >= >> or the like.  We do at least a halfway-decent job of
handling versions that aren't strictly numeric, like C<0.27_02>, but
exotic stuff will likely cause problems.

In the future, the guts of this method might be replaced with a call
out to C<version.pm>.

=item config($key)

=item config($key, $value)

=item config() [deprecated]

[version 0.22]

With a single argument C<$key>, returns the value associated with that
key in the C<Config.pm> hash, including any changes the author or user
has specified.

With C<$key> and C<$value> arguments, sets the value for future
callers of C<config($key)>.

With no arguments, returns a hash reference containing all such
key-value pairs.  This usage is deprecated, though, because it's a
resource hog and violates encapsulation.

=item config_data($name)

=item config_data($name => $value)

[version 0.26]

With a single argument, returns the value of the configuration
variable C<$name>.  With two arguments, sets the given configuration
variable to the given value.  The value may be any Perl scalar that's
serializable with C<Data::Dumper>.  For instance, if you write a
module that can use a MySQL or PostgreSQL back-end, you might create
configuration variables called C<mysql_connect> and
C<postgres_connect>, and set each to an array of connection parameters
for C<< DBI->connect() >>.

Configuration values set in this way using the Module::Build object
will be available for querying during the build/test process and after

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

=item prefix_relpaths()

=item prefix_relpaths($installdirs)

=item prefix_relpaths($installdirs, $type)

=item prefix_relpaths($installdirs, $type => $path)

[version 0.28]

Set or retrieve the relative paths that are appended to C<prefix> for
any installable element.  This is useful if you want to set the
relative install path for custom build elements.

With no argument, it returns a reference to a hash containing all
elements and their respective values as defined by the current
C<installdirs> setting.

With a single argument, it returns a reference to a hash containing
all elements and their respective values as defined by
C<$installdirs>.

The hash returned by the above calls should not be modified directly;
use the three-argument below form to change values.

The two argument form returns the value associated with the
element C<$type>.

The multiple argument form allows you to set the paths for element types.
C<$value> must be a relative path using Unix-like paths.  (A series of
directories separated by slashes, e.g. C<foo/bar>.)  The return value is a
localized path based on C<$value>.

Assigning the value C<undef> to an element causes it to be removed.

=item get_metadata()

[version 0.36]

This method returns a hash reference of metadata that can be used to create a
YAML datastream. It is provided for authors to override or customize the fields
of F<META.yml>.   E.g.

  package My::Builder;
  use base 'Module::Build';

  sub get_metadata {
    my $self, @args = @_;
    my $data = $self->SUPER::get_metadata(@args);
    $data->{custom_field} = 'foo';
    return $data;
  }

Valid arguments include:

=over

=item *

C<fatal> -- indicates whether missing required
metadata fields should be a fatal error or not.  For META creation, it
generally should, but for MYMETA creation for end-users, it should not be
fatal.

=item *

C<auto> -- indicates whether any necessary configure_requires should be
automatically added.  This is used in META creation.

=back

This method is a wrapper around the old prepare_metadata API now that we
no longer use YAML::Node to hold metadata.

=item prepare_metadata() [deprecated]

[version 0.36]

[Deprecated] As of 0.36, authors should use C<get_metadata> instead.  This
method is preserved for backwards compatibility only.

It takes three positional arguments: a hashref (to which metadata will be
added), an optional arrayref (to which metadata keys will be added in order if
the arrayref exists), and a hashref of arguments (as provided to get_metadata).
The latter argument is new as of 0.36.  Earlier versions are always fatal on
errors.

Prior to version 0.36, this method took a YAML::Node as an argument to hold
assembled metadata.

=item prereq_failures()

[version 0.11]

Returns a data structure containing information about any failed
prerequisites (of any of the types described above), or C<undef> if
all prerequisites are met.

The data structure returned is a hash reference.  The top level keys
are the type of prerequisite failed, one of "requires",
"build_requires", "conflicts", or "recommends".  The associated values
are hash references whose keys are the names of required (or
conflicting) modules.  The associated values of those are hash
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