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


NAME

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

Back to Top


DESCRIPTION

I list here some of the most important methods in Module::Build. Normally you won't need to deal with these methods unless you want to subclass 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.

CONSTRUCTORS

current()

[version 0.20]

This method returns a reasonable facsimile of the currently-executing Module::Build object representing the current build. You can use this object to query its 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 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 current() method is currently implemented, there may be slight differences between the $build object in Build.PL and the one in 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, current() will NOT work correctly if you have changed out of the directory that Module::Build was invoked from.

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 module_name argument, or dist_name and one of dist_version or dist_version_from. In other words, you must provide enough information to determine both a distribution name and version.

add_to_cleanup

[version 0.19]

An array reference of files to be cleaned up when the clean action is performed. See also the add_to_cleanup() method.

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.

auto_features

[version 0.26]

This parameter supports the setting of features (see feature($name)) automatically based on a set of prerequisites. For instance, for a module that could optionally use either MySQL or PostgreSQL databases, you might use auto_features like this:

  my $build = Module::Build->new
    (
     ...other stuff here...
     auto_features => {
       pg_support    => {
                         description => "Interface with Postgres databases",
                         requires    => { 'DBD::Pg' => 23.3,
                                          'DateTime::Format::Pg' => 0 },
                        },
       mysql_support => {
                         description => "Interface with MySQL databases",
                         requires    => { 'DBD::mysql' => 17.9,
                                          'DateTime::Format::MySQL' => 0 },
                        },
     }
    );

For each feature named, the required prerequisites will be checked, and if there are no failures, the feature will be enabled (set to 1). Otherwise the failures will be displayed to the user and the feature will be disabled (set to 0).

See the documentation for requires for the details of how requirements can be specified.

autosplit

[version 0.04]

An optional autosplit argument specifies a file which should be run through the AutoSplit::autosplit() function. If multiple files should be split, the argument may be given as an array of the files to split.

In general I don't consider autosplitting a great idea, because it's not always clear that autosplitting achieves its intended performance benefits. It may even harm performance in environments like mod_perl, where as much as possible of a module's code should be loaded during startup.

build_class

[version 0.28]

The Module::Build class or subclass to use in the build script. Defaults to "Module::Build" or the class name passed to or created by a call to subclass(). This property is useful if you're writing a custom Module::Build subclass and have a bootstrapping problem--that is, your subclass requires modules that may not be installed when perl Build.PL is executed, but you've listed in build_requires so that they should be available when ./Build is executed.

build_requires

[version 0.07]

Modules listed in this section are necessary to build and install the given module, but are not necessary for regular usage of it. This is actually an important distinction - it allows for tighter control over the body of installed modules, and facilitates correct dependency checking on binary/packaged distributions of the module.

See the documentation for PREREQUISITES in the Module::Build::Authoring manpage for the details of how requirements can be specified.

create_packlist

[version 0.28]

If true, this parameter tells Module::Build to create a .packlist file during the install action, just like ExtUtils::MakeMaker does. The file is created in a subdirectory of the arch installation location. It is used by some other tools (CPAN, CPANPLUS, etc.) for determining what files are part of an install.

The default value is true. This parameter was introduced in Module::Build version 0.2609; previously no packlists were ever created by Module::Build.

c_source

[version 0.04]

An optional c_source argument specifies a directory which contains C source files that the rest of the build may depend on. Any .c files in the directory will be compiled to object files. The directory will be added to the search path during the compilation and linking phases of any C or XS files.

[version 0.3604]

A list of directories can be supplied using an anonymous array reference of strings.

conflicts

[version 0.07]

Modules listed in this section conflict in some serious way with the given module. Module::Build (or some higher-level tool) will refuse to install the given module if the given module/version is also installed.

See the documentation for PREREQUISITES in the Module::Build::Authoring manpage for the details of how requirements can be specified.

create_license

[version 0.31]

This parameter tells Module::Build to automatically create a LICENSE file at the top level of your distribution, containing the full text of the author's chosen license. This requires Software::License on the author's machine, and further requires that the license parameter specifies a license that it knows about.

create_makefile_pl

[version 0.19]

This parameter lets you use Module::Build::Compat during the distdir (or dist) action to automatically create a Makefile.PL for compatibility with ExtUtils::MakeMaker. The parameter's value should be one of the styles named in the the Module::Build::Compat manpage documentation.

create_readme

[version 0.22]

This parameter tells Module::Build to automatically create a README file at the top level of your distribution. Currently it will simply use Pod::Text (or Pod::Readme if it's installed) on the file indicated by dist_version_from and put the result in the README file. This is by no means the only recommended style for writing a README, but it seems to be one common one used on the CPAN.

If you generate a README in this way, it's probably a good idea to create a separate INSTALL file if that information isn't in the generated README.

dist_abstract

[version 0.20]

This should be a short description of the distribution. This is used when generating metadata for META.yml and PPD files. If it is not given then Module::Build looks in the POD of the module from which it gets the distribution's version. If it finds a POD section marked "=head1 NAME", then it looks for the first line matching \s+-\s+(.+), and uses the captured text as the abstract.

dist_author

[version 0.20]

This should be something like "John Doe <jdoe@example.com>", or if there are multiple authors, an anonymous array of strings may be specified. This is used when generating metadata for META.yml and PPD files. If this is not specified, then Module::Build looks at the module from which it gets the distribution's version. If it finds a POD section marked "=head1 AUTHOR", then it uses the contents of this section.

dist_name

[version 0.11]

Specifies the name for this distribution. Most authors won't need to set this directly, they can use module_name to set dist_name to a reasonable default. However, some agglomerative distributions like libwww-perl or bioperl have names that don't correspond directly to a module name, so dist_name can be set independently.

dist_version

[version 0.11]

Specifies a version number for the distribution. See module_name or dist_version_from for ways to have this set automatically from a $VERSION variable in a module. One way or another, a version number needs to be set.

dist_version_from

[version 0.11]

Specifies a file to look for the distribution version in. Most authors won't need to set this directly, they can use module_name to set it to a reasonable default.

The version is extracted from the specified file according to the same rules as the ExtUtils::MakeMaker manpage and CPAN.pm. It involves finding the first line that matches the regular expression

   /([\$*])(([\w\:\']*)\bVERSION)\b.*\=/

eval()-ing that line, then checking the value of the $VERSION variable. Quite ugly, really, but all the modules on CPAN depend on this process, so there's no real opportunity to change to something better.

If the target file of dist_version_from contains more than one package declaration, the version returned will be the one matching the configured module_name.

dynamic_config

[version 0.07]

A boolean flag indicating whether the Build.PL file must be executed, or whether this module can be built, tested and installed solely from consulting its metadata file. The main reason to set this to a true value is that your module performs some dynamic configuration as part of its build/install process. If the flag is omitted, the META.yml spec says that installation tools should treat it as 1 (true), because this is a safer way to behave.

Currently Module::Build doesn't actually do anything with this flag - it's up to higher-level tools like CPAN.pm to do something useful with it. It can potentially bring lots of security, packaging, and convenience improvements.

extra_compiler_flags
extra_linker_flags

[version 0.19]

These parameters can contain array references (or strings, in which case they will be split into arrays) to pass through to the compiler and linker phases when compiling/linking C code. For example, to tell the compiler that your code is C++, you might do:

  my $build = Module::Build->new
    (
     module_name          => 'Foo::Bar',
     extra_compiler_flags => ['-x', 'c++'],
    );

To link your XS code against glib you might write something like:

  my $build = Module::Build->new
    (
     module_name          => 'Foo::Bar',
     dynamic_config       => 1,
     extra_compiler_flags => scalar `glib-config --cflags`,
     extra_linker_flags   => scalar `glib-config --libs`,
    );
get_options

[version 0.26]

You can pass arbitrary command line options to Build.PL or Build, and they will be stored in the Module::Build object and can be accessed via the args() method. However, sometimes you want more flexibility out of your argument processing than this allows. In such cases, use the get_options parameter to pass in a hash reference of argument specifications, and the list of arguments to Build.PL or Build will be processed according to those specifications before they're passed on to Module::Build's own argument processing.

The supported option specification hash keys are:

type

The type of option. The types are those supported by Getopt::Long; consult its documentation for a complete list. Typical types are =s for strings, + for additive options, and ! 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.

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 args() method.

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 args().

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 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

WARNING: Any op\