.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Module::Build::API 3"
.TH Module::Build::API 3 "2015-10-14" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Module::Build::API \- API Reference for Module Authors
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
I list here some of the most important methods in \f(CW\*(C`Module::Build\*(C'\fR.
Normally you won't need to deal with these methods unless you want to
subclass \f(CW\*(C`Module::Build\*(C'\fR. 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.
.SS "\s-1CONSTRUCTORS\s0"
.IX Subsection "CONSTRUCTORS"
.IP "\fIcurrent()\fR" 4
.IX Item "current()"
[version 0.20]
.Sp
This method returns a reasonable facsimile of the currently-executing
\&\f(CW\*(C`Module::Build\*(C'\fR object representing the current build. You can use
this object to query its \*(L"\fInotes()\fR\*(R" 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 \f(CW\*(C`perl Build.PL\*(C'\fR, then use their answer
during a regression test:
.Sp
.Vb 3
\& # 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(\*(Aqcolor\*(Aq);
\& ...
.Ve
.Sp
The way the \f(CW\*(C`current()\*(C'\fR method is currently implemented, there may be
slight differences between the \f(CW$build\fR object in Build.PL and the
one in \f(CW\*(C`t/colortest.t\*(C'\fR. It is our goal to minimize these differences
in future releases of Module::Build, so please report any anomalies
you find.
.Sp
One important caveat: in its current implementation, \f(CW\*(C`current()\*(C'\fR will
\&\fB\s-1NOT\s0\fR work correctly if you have changed out of the directory that
\&\f(CW\*(C`Module::Build\*(C'\fR was invoked from.
.IP "\fInew()\fR" 4
.IX Item "new()"
[version 0.03]
.Sp
Creates a new Module::Build object. Arguments to the \fInew()\fR method are
listed below. Most arguments are optional, but you must provide
either the \*(L"module_name\*(R" argument, or \*(L"dist_name\*(R" and one of
\&\*(L"dist_version\*(R" or \*(L"dist_version_from\*(R". In other words, you must
provide enough information to determine both a distribution name and
version.
.RS 4
.IP "add_to_cleanup" 4
.IX Item "add_to_cleanup"
[version 0.19]
.Sp
An array reference of files to be cleaned up when the \f(CW\*(C`clean\*(C'\fR action
is performed. See also the \fIadd_to_cleanup()\fR
method.
.IP "allow_pureperl" 4
.IX Item "allow_pureperl"
[version 0.4005]
.Sp
A bool indicating the module is still functional without its xs parts.
When an \s-1XS\s0 module is build with \-\-pureperl_only, it will otherwise fail.
.IP "auto_configure_requires" 4
.IX Item "auto_configure_requires"
[version 0.34]
.Sp
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.
.IP "auto_features" 4
.IX Item "auto_features"
[version 0.26]
.Sp
This parameter supports the setting of features (see
\&\*(L"feature($name)\*(R") automatically based on a set of prerequisites. For
instance, for a module that could optionally use either MySQL or
PostgreSQL databases, you might use \f(CW\*(C`auto_features\*(C'\fR like this:
.Sp
.Vb 10
\& my $build = Module::Build\->new
\& (
\& ...other stuff here...
\& auto_features => {
\& pg_support => {
\& description => "Interface with Postgres databases",
\& requires => { \*(AqDBD::Pg\*(Aq => 23.3,
\& \*(AqDateTime::Format::Pg\*(Aq => 0 },
\& },
\& mysql_support => {
\& description => "Interface with MySQL databases",
\& requires => { \*(AqDBD::mysql\*(Aq => 17.9,
\& \*(AqDateTime::Format::MySQL\*(Aq => 0 },
\& },
\& }
\& );
.Ve
.Sp
For each feature named, the required prerequisites will be checked, and
if there are no failures, the feature will be enabled (set to \f(CW1\fR).
Otherwise the failures will be displayed to the user and the feature
will be disabled (set to \f(CW0\fR).
.Sp
See the documentation for \*(L"requires\*(R" for the details of how
requirements can be specified.
.IP "autosplit" 4
.IX Item "autosplit"
[version 0.04]
.Sp
An optional \f(CW\*(C`autosplit\*(C'\fR argument specifies a file which should be run
through the \fIAutoSplit::autosplit()\fR function.
If multiple files should be split, the argument may be given as an
array of the files to split.
.Sp
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.
.IP "build_class" 4
.IX Item "build_class"
[version 0.28]
.Sp
The Module::Build class or subclass to use in the build script.
Defaults to \*(L"Module::Build\*(R" or the class name passed to or created by
a call to \*(L"\fIsubclass()\fR\*(R". 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 \f(CW\*(C`perl Build.PL\*(C'\fR is executed, but you've listed in
\&\*(L"build_requires\*(R" so that they should be available when \f(CW\*(C`./Build\*(C'\fR is
executed.
.IP "build_requires" 4
.IX Item "build_requires"
[version 0.07]
.Sp
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.
.Sp
See the documentation for \*(L"\s-1PREREQUISITES\s0\*(R" in Module::Build::Authoring
for the details of how requirements can be specified.
.IP "configure_requires" 4
.IX Item "configure_requires"
[version 0.30]
.Sp
Modules listed in this section must be installed \fIbefore\fR configuring
this distribution (i.e. before running the \fIBuild.PL\fR script).
This might be a specific minimum version of \f(CW\*(C`Module::Build\*(C'\fR or any
other module the \fIBuild.PL\fR needs in order to do its stuff. Clients
like \f(CW\*(C`CPAN.pm\*(C'\fR or \f(CW\*(C`CPANPLUS\*(C'\fR will be expected to pick
\&\f(CW\*(C`configure_requires\*(C'\fR out of the \fI\s-1META\s0.yml\fR file and install these
items before running the \f(CW\*(C`Build.PL\*(C'\fR.
.Sp
Module::Build may automatically add itself to configure_requires.
See \*(L"auto_configure_requires\*(R" for details.
.Sp
See the documentation for \*(L"\s-1PREREQUISITES\s0\*(R" in Module::Build::Authoring
for the details of how requirements can be specified.
.IP "test_requires" 4
.IX Item "test_requires"
[version 0.4004]
.Sp
Modules listed in this section must be installed before testing the distribution.
.Sp
See the documentation for \*(L"\s-1PREREQUISITES\s0\*(R" in Module::Build::Authoring
for the details of how requirements can be specified.
.IP "create_packlist" 4
.IX Item "create_packlist"
[version 0.28]
.Sp
If true, this parameter tells Module::Build to create a \fI.packlist\fR
file during the \f(CW\*(C`install\*(C'\fR action, just like \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR does.
The file is created in a subdirectory of the \f(CW\*(C`arch\*(C'\fR installation
location. It is used by some other tools (\s-1CPAN\s0, \s-1CPANPLUS\s0, etc.) for
determining what files are part of an install.
.Sp
The default value is true. This parameter was introduced in
Module::Build version 0.2609; previously no packlists were ever
created by Module::Build.
.IP "c_source" 4
.IX Item "c_source"
[version 0.04]
.Sp
An optional \f(CW\*(C`c_source\*(C'\fR argument specifies a directory which contains
C source files that the rest of the build may depend on. Any \f(CW\*(C`.c\*(C'\fR
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 \s-1XS\s0 files.
.Sp
[version 0.3604]
.Sp
A list of directories can be supplied using an anonymous array
reference of strings.
.IP "conflicts" 4
.IX Item "conflicts"
[version 0.07]
.Sp
Modules listed in this section conflict in some serious way with the
given module. \f(CW\*(C`Module::Build\*(C'\fR (or some higher-level tool) will
refuse to install the given module if the given module/version is also
installed.
.Sp
See the documentation for \*(L"\s-1PREREQUISITES\s0\*(R" in Module::Build::Authoring
for the details of how requirements can be specified.
.IP "create_license" 4
.IX Item "create_license"
[version 0.31]
.Sp
This parameter tells Module::Build to automatically create a
\&\fI\s-1LICENSE\s0\fR file at the top level of your distribution, containing the
full text of the author's chosen license. This requires
\&\f(CW\*(C`Software::License\*(C'\fR on the author's machine, and further requires
that the \f(CW\*(C`license\*(C'\fR parameter specifies a license that it knows about.
.IP "create_makefile_pl" 4
.IX Item "create_makefile_pl"
[version 0.19]
.Sp
This parameter lets you use \f(CW\*(C`Module::Build::Compat\*(C'\fR during the
\&\f(CW\*(C`distdir\*(C'\fR (or \f(CW\*(C`dist\*(C'\fR) action to automatically create a Makefile.PL
for compatibility with \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR. The parameter's value
should be one of the styles named in the Module::Build::Compat
documentation.
.IP "create_readme" 4
.IX Item "create_readme"
[version 0.22]
.Sp
This parameter tells Module::Build to automatically create a \fI\s-1README\s0\fR
file at the top level of your distribution. Currently it will simply
use \f(CW\*(C`Pod::Text\*(C'\fR (or \f(CW\*(C`Pod::Readme\*(C'\fR if it's installed) on the file
indicated by \f(CW\*(C`dist_version_from\*(C'\fR and put the result in the \fI\s-1README\s0\fR
file. This is by no means the only recommended style for writing a
\&\fI\s-1README\s0\fR, but it seems to be one common one used on the \s-1CPAN\s0.
.Sp
If you generate a \fI\s-1README\s0\fR in this way, it's probably a good idea to
create a separate \fI\s-1INSTALL\s0\fR file if that information isn't in the
generated \fI\s-1README\s0\fR.
.IP "dist_abstract" 4
.IX Item "dist_abstract"
[version 0.20]
.Sp
This should be a short description of the distribution. This is used when
generating metadata for \fI\s-1META\s0.yml\fR and \s-1PPD\s0 files. If it is not given
then \f(CW\*(C`Module::Build\*(C'\fR looks in the \s-1POD\s0 of the module from which it gets
the distribution's version. If it finds a \s-1POD\s0 section marked \*(L"=head1
\&\s-1NAME\s0\*(R", then it looks for the first line matching \f(CW\*(C`\es+\-\es+(.+)\*(C'\fR,
and uses the captured text as the abstract.
.IP "dist_author" 4
.IX Item "dist_author"
[version 0.20]
.Sp
This should be something like \*(L"John Doe