view release on metacpan or  search on metacpan

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

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

Use of this parameter is L<discouraged|Module::Build::Compat/"WARNING">.

=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

[version 0.11]

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

=item 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 L</module_name>
to set it to a reasonable default.

The version is extracted from the specified file according to the same
rules as L<ExtUtils::MakeMaker> and C<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 C<$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.

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

=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
C<runtime_params> hash is created when C<perl Build.PL> is run (or when the
C<new()> method is called, if the Module::Build Perl API is being used instead
of called from a shell), and lasts until C<perl Build.PL> is run again or the
C<clean> action is run.

=item script_files()

[version 0.18]

Returns a hash reference whose keys are the perl script files to be
installed, if any.  This corresponds to the C<script_files> parameter to the
C<new()> method.  With an optional argument, this parameter may be set
dynamically.

For backward compatibility, the C<scripts()> method does exactly the
same thing as C<script_files()>.  C<scripts()> is deprecated, but it
will stay around for several versions to give people time to
transition.

=item up_to_date($source_file, $derived_file)

=item up_to_date(\@source_files, \@derived_files)

[version 0.20]

This method can be used to compare a set of source files to a set of
derived files.  If any of the source files are newer than any of the
derived files, it returns false.  Additionally, if any of the derived
files do not exist, it returns false.  Otherwise it returns true.

The arguments may be either a scalar or an array reference of file
names.

=item y_n($message, $default)

[version 0.12]

Asks the user a yes/no question using C<prompt()> and returns true or
false accordingly.  The user will be asked the question repeatedly
until they give an answer that looks like "yes" or "no".

The first argument specifies the message to display to the user (for
example, C<"Shall I invest your money for you?">), and the second
argument specifies the default answer (for example, C<"y">).

Note that the default is specified as a string like C<"y"> or C<"n">,
and the return value is a Perl boolean value like 1 or 0.  I thought
about this for a while and this seemed like the most useful way to do
it.

This method may be called as a class or object method.

=back


=head2 Autogenerated Accessors

In addition to the aforementioned methods, there are also some get/set
accessor methods for the following properties:

=over 4

=item PL_files()

=item allow_mb_mismatch()

=item allow_pureperl()

=item auto_configure_requires()

=item autosplit()

=item base_dir()

=item bindoc_dirs()

=item blib()

=item build_bat()

=item build_class()

=item build_elements()

=item build_requires()

=item build_script()

=item bundle_inc()

=item bundle_inc_preload()

=item c_source()

=item config_dir()

=item configure_requires()

=item conflicts()