Alien-ROOT

 view release on metacpan or  search on metacpan

inc/inc_Module-Build/Module/Build/API.pod  view on Meta::CPAN

for the details of how requirements can be specified.

=item create_packlist

[version 0.28]

If true, this parameter tells Module::Build to create a F<.packlist>
file during the C<install> action, just like C<ExtUtils::MakeMaker> does.
The file is created in a subdirectory of the C<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.

=item c_source

[version 0.04]

An optional C<c_source> argument specifies a directory which contains
C source files that the rest of the build may depend on.  Any C<.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.

=item conflicts

[version 0.07]

Modules listed in this section conflict in some serious way with the
given module.  C<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 L<Module::Build::Authoring/"PREREQUISITES">
for the details of how requirements can be specified.

=item create_license

[version 0.31]

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

=item create_makefile_pl

[version 0.19]

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

=item create_readme

[version 0.22]

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

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

=item dist_abstract

[version 0.20]

This should be a short description of the distribution.  This is used when
generating metadata for F<META.yml> and PPD files.  If it is not given
then C<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 C<\s+-\s+(.+)>,
and uses the captured text as the abstract.

=item 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 F<META.yml> and
PPD files.  If this is not specified, then C<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.

=item dist_name

[version 0.11]

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

=item dist_suffix

[version 0.37]

Specifies an optional suffix to include after the version number
in the distribution directory (and tarball) name.  The only suffix
currently recognized by PAUSE is 'TRIAL', which indicates that the
distribution should not be indexed.  For example:

  Foo-Bar-1.23-TRIAL.tar.gz

This will automatically do the "right thing" depending on C<dist_version> and
C<release_status>.  When C<dist_version> does not have an underscore and
C<release_status> is not 'stable', then C<dist_suffix> will default to 'TRIAL'.
Otherwise it will default to the empty string, disabling the suffix.  

In general, authors should only set this if they B<must> override the default
behavior for some particular purpose.

=item dist_version

inc/inc_Module-Build/Module/Build/API.pod  view on Meta::CPAN

file during the C<distmeta> action.  Any existing entries with the
same names will be overridden.

The only difference between C<meta_add> and C<meta_merge> is their
behavior on hash-valued and array-valued entries: C<meta_add> will
completely blow away the existing hash or array value, but
C<meta_merge> will merge the supplied data into the existing hash or
array value.

See the L</"MODULE METADATA"> section for details.

=item module_name

[version 0.03]

The C<module_name> is a shortcut for setting default values of
C<dist_name> and C<dist_version_from>, reflecting the fact that the
majority of CPAN distributions are centered around one "main" module.
For instance, if you set C<module_name> to C<Foo::Bar>, then
C<dist_name> will default to C<Foo-Bar> and C<dist_version_from> will
default to C<lib/Foo/Bar.pm>.  C<dist_version_from> will in turn be
used to set C<dist_version>.

Setting C<module_name> won't override a C<dist_*> parameter you
specify explicitly.

=item needs_compiler

[version 0.36]

The C<needs_compiler> parameter indicates whether a compiler is required to
build the distribution.  The default is false, unless XS files are found or
the C<c_source> parameter is set, in which case it is true.  If true,
L<ExtUtils::CBuilder> is automatically added to C<build_requires> if needed.

For a distribution where a compiler is I<optional>, e.g. a dual XS/pure-Perl
distribution, C<needs_compiler> should explicitly be set to a false value.

=item PL_files

[version 0.06]

An optional parameter specifying a set of C<.PL> files in your
distribution.  These will be run as Perl scripts prior to processing
the rest of the files in your distribution with the name of the file
they're generating as an argument.  They are usually used as templates
for creating other files dynamically, so that a file like
C<lib/Foo/Bar.pm.PL> might create the file C<lib/Foo/Bar.pm>.

The files are specified with the C<.PL> files as hash keys, and the
file(s) they generate as hash values, like so:

  my $build = Module::Build->new
    (
     module_name => 'Foo::Bar',
     ...
     PL_files => { 'lib/Foo/Bar.pm.PL' => 'lib/Foo/Bar.pm' },
    );

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

If your C<.PL> scripts don't create any files, or if they create files
with unexpected names, or even if they create multiple files, you can
indicate that so that Module::Build can properly handle these created
files:

  PL_files => {
               'lib/Foo/Bar.pm.PL' => 'lib/Foo/Bar.pm',
               'lib/something.PL'  => ['/lib/something', '/lib/else'],
               'lib/funny.PL'      => [],
              }

Here's an example of a simple PL file.

    my $output_file = shift;
    open my $fh, ">", $output_file or die "Can't open $output_file: $!";

    print $fh <<'END';
    #!/usr/bin/perl

    print "Hello, world!\n";
    END

PL files are not installed by default, so its safe to put them in
F<lib/> and F<bin/>.


=item pm_files

[version 0.19]

An optional parameter specifying the set of C<.pm> files in this
distribution, specified as a hash reference whose keys are the files'
locations in the distributions, and whose values are their logical
locations based on their package name, i.e. where they would be found
in a "normal" Module::Build-style distribution.  This parameter is
mainly intended to support alternative layouts of files.

For instance, if you have an old-style C<MakeMaker> distribution for a
module called C<Foo::Bar> and a F<Bar.pm> file at the top level of the
distribution, you could specify your layout in your C<Build.PL> like
this:

  my $build = Module::Build->new
    (
     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

inc/inc_Module-Build/Module/Build/API.pod  view on Meta::CPAN

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'

Alternatively, if C<share_dir> is a hashref, it may have C<dist> or
C<module> keys providing full flexibility in defining how share
directories should be installed.

  share_dir => {
    dist => [ 'examples', 'more_examples' ],
    module => {
      Foo::Templates => ['share/html', 'share/text'],
      Foo::Config    => 'share/config',
    }
  }

If C<share_dir> is set, then File::ShareDir will automatically be added
to the C<requires> hash.

=item sign

[version 0.16]

If a true value is specified for this parameter, L<Module::Signature>
will be used (via the 'distsign' action) to create a SIGNATURE file
for your distribution during the 'distdir' action, and to add the
SIGNATURE file to the MANIFEST (therefore, don't add it yourself).

The default value is false.  In the future, the default may change to
true if you have C<Module::Signature> installed on your system.

=item tap_harness_args

[version 0.2808_03]

An optional parameter specifying parameters to be passed to TAP::Harness when
running tests. Must be given as a hash reference of parameters; see the
L<TAP::Harness|TAP::Harness> documentation for details. Note that specifying
this parameter will implicitly set C<use_tap_harness> to a true value. You
must therefore be sure to add TAP::Harness as a requirement for your module in
L</build_requires>.

=item test_files

[version 0.23]

An optional parameter specifying a set of files that should be used as
C<Test::Harness>-style regression tests to be run during the C<test>
action.  May be given as an array reference of the files, or as a hash
reference whose keys are the files (and whose values will currently be
ignored).  If the argument is given as a single string (not in an
array reference), that string will be treated as a C<glob()> pattern
specifying the files to use.

The default is to look for a F<test.pl> script in the top-level
directory of the distribution, and any files matching the glob pattern
C<*.t> in the F<t/> subdirectory.  If the C<recursive_test_files>
property is true, then the C<t/> directory will be scanned recursively
for C<*.t> files.

=item use_tap_harness

[version 0.2808_03]

An optional parameter indicating whether or not to use TAP::Harness for
testing rather than Test::Harness. Defaults to false. If set to true, you must
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