view release on metacpan or  search on metacpan

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

  test_requires 'Test::More' => '0.47';

The C<test_requires> command indicates a test script dependency for
the distribution. The specification format is identical to that of
the C<requires> command.

The C<test_requires> command is distinct from the C<requires> command
in that it indicates a module that is needed B<only> during the
testing of the distribution (often a period of only a few seconds)
but will B<not> be needed after the distribution is installed.

The C<testrequires> command is used to allow the installer some
flexibility in how it provides the module, and to allow downstream
packagers (Debian, FreeBSD, ActivePerl etc) to retain only the
dependencies needed for run-time operation.

The C<include> command is sometimes used by some authors along with
C<test_requires> to bundle a small well-tested module into the
distribution package itself rather than inflict yet another module
installation on users installing from CPAN directly.

=head2 configure_requires

  configure_requires 'File::Spec' => '0.80';

The C<configure_requires> command indicates a configure-time dependency
for the distribution. The specification format is identical to that of
the C<requires> command.

The C<configure_requires> command is used to get around the conundrum
of how to use a CPAN module in your Makefile.PL, when you have to load
Makefile.PL (and thus the CPAN module) in order to know that you need it.

Traditionally, this circular logic could not be broken and so Makefile.PL
scripts needed to rely on lowest-common-denominator approaches, or to
bundle those dependencies using something like the C<include> command.

The C<configure_requires> command creates an entry in the special
configure_requires: key in the distribution's F<META.yml> file.

Although most of F<META.yml> is considered advisory only, a L<CPAN>
client will treat the contents of configure_requires: as authoritive,
and install the listed modules B<before> it executes the F<Makefile.PL>
(from which it then determines the other dependencies).

Please note that support for configure_requires: in CPAN clients is not
100% complete at time of writing, and still cannot be relied upon.

Because B<Module::Install> itself only supports 5.005, it will silently
add the equivalent of a C<< configure_requires( perl => '5.005' ); >>
command to your distribution.

=head2 requires_external_bin

  requires_external_bin 'cvs';

As part of its role as the dominant "glue" language, a lot of Perl
modules run commands or programs on the host system.

The C<requires_external_bin> command is used to verify that a particular
command is available on the host system.

Unlike a missing Perl module, a missing external binary is unresolvable
at make-time, and so the F<Makefile.PL> run will abort with a "NA"
(Not Applicable) result.

In future, this command will also add additional information to the
metadata for the dist, so that auto-packagers for particular operating
system are more-easily able to auto-discover the appropriate non-Perl
packages needed as a dependency.

=head2 install_script

  # The following are equivalent
  install_script 'script/scriptname'

The C<install_script> command provides support for the installation of
scripts that will become available at the console on both Unix and
Windows (in the later case by wrapping it up as a .bat file).

Note that is it normal practice to B<not> put a .pl on the end of such
scripts, so that they feel more natural when being used.

In the example above, the F<script/scriptname> program could be run after
the installation just by doing the following.

  > scriptname
  Running scriptname 0.01...

  >

By convention, scripts should be placed in a /script directory within your
distribution. To support less typing, if a script is located in the script
directory, you need refer to it by name only.

  # The following are equivalent
  install_script 'foo';
  install_script 'script/foo';

=head2 no_index

  no_index directory => 'examples';
  no_index package   => 'DB';

Quite often a distribition will provide example scripts or testing
modules (.pm files) as well as the actual library modules.

In almost all situations, you do B<not> want these indexed in the CPAN
index, the master Perl packages list, or displayed on L<https://metacpan.org/>
or L<http://search.cpan.org/> websites, you just want them along for the
ride.

The C<no_index> command is used to indicate directories or files where
there might be non-library .pm files or other files that the CPAN
indexer and websites such as L<https://metacpan.org/>
or L<http://search.cpan.org/> should explicitly ignore.

The most common situation is to ignore example or demo directories,
but a variety of different situations may require a C<no_index> entry.