view release on metacpan or  search on metacpan

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

such cases, use the C<get_options> parameter to pass in a hash
reference of argument specifications, and the list of arguments to
F<Build.PL> or F<Build> will be processed according to those
specifications before they're passed on to C<Module::Build>'s own
argument processing.

The supported option specification hash keys are:


=over 4

=item type

The type of option.  The types are those supported by Getopt::Long; consult
its documentation for a complete list.  Typical types are C<=s> for strings,
C<+> for additive options, and C<!> for negatable options.  If the
type is not specified, it will be considered a boolean, i.e. no
argument is taken and a value of 1 will be assigned when the option is
encountered.

=item store

A reference to a scalar in which to store the value passed to the option.
If not specified, the value will be stored under the option name in the
hash returned by the C<args()> method.

=item default

A default value for the option.  If no default value is specified and no option
is passed, then the option key will not exist in the hash returned by
C<args()>.

=back


You can combine references to your own variables or subroutines with
unreferenced specifications, for which the result will also be stored in the
hash returned by C<args()>.  For example:

  my $loud = 0;
  my $build = Module::Build->new
    (
     module_name => 'Foo::Bar',
     get_options => {
                     Loud =>     { store => \$loud },
                     Dbd  =>     { type  => '=s'   },
                     Quantity => { type  => '+'    },
                    }
    );

  print STDERR "HEY, ARE YOU LISTENING??\n" if $loud;
  print "We'll use the ", $build->args('Dbd'), " DBI driver\n";
  print "Are you sure you want that many?\n"
    if $build->args('Quantity') > 2;

The arguments for such a specification can be called like so:

  perl Build.PL --Loud --Dbd=DBD::pg --Quantity --Quantity --Quantity

B<WARNING:> Any option specifications that conflict with Module::Build's own
options (defined by its properties) will throw an exception.  Use capitalized
option names to avoid unintended conflicts with future Module::Build options.

Consult the Getopt::Long documentation for details on its usage.

=item include_dirs

[version 0.24]

Specifies any additional directories in which to search for C header
files.  May be given as a string indicating a single directory, or as
a list reference indicating multiple directories.

=item install_path

[version 0.19]

You can set paths for individual installable elements by using the
C<install_path> parameter:

  my $build = Module::Build->new
    (
     ...other stuff here...
     install_path => {
                      lib  => '/foo/lib',
                      arch => '/foo/lib/arch',
                     }
    );

=item installdirs

[version 0.19]

Determines where files are installed within the normal perl hierarchy
as determined by F<Config.pm>.  Valid values are: C<core>, C<site>,
C<vendor>.  The default is C<site>.  See
L<Module::Build/"INSTALL PATHS">

=item license

[version 0.07]

Specifies the licensing terms of your distribution.

As of Module::Build version 0.36_14, you may use a L<Software::License>
subclass name (e.g. 'Apache_2_0') instead of one of the keys below.

The legacy list of valid license values include:

=over 4

=item apache

The distribution is licensed under the Apache License, Version 2.0
(L<http://apache.org/licenses/LICENSE-2.0>).

=item apache_1_1

The distribution is licensed under the Apache Software License, Version 1.1
(L<http://apache.org/licenses/LICENSE-1.1>).

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

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.