view release on metacpan or  search on metacpan

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

=head2 configure_requires (L<Module::Install::Metadata>)

  configure_requires 'ExtUtils::Foo::Bar';
  configure_requires 'ExtUtils::Foo::Baz' => '1.00';

B<configure_requires> command also takes a module name and a minimum
required version if any. The difference from the C<requires> command
is that B<configure_requires> is to call for modules you'll require
to run C<< perl Makefile.PL >>. This attribute only makes sense for
the latest CPAN toolchains that parse C<META.yml> before running C<<
perl Makefile.PL >>.

The values set by B<configure_requires> are passed to
L<ExtUtils::MakeMaker> as a C<CONFIGURE_REQUIRES> attribute, which
may fall back to C<PREREQ_PM> if your L<ExtUtils::MakeMaker> is not
new enough.

=begin experimental

=head2 requires_from, test_requires_from (L<Module::Install::Metadata>)

  requires_from 'lib/Foo/Bar.pm';
  test_requires_from 't/00-compile.t';

B<requires_from> command takes a module file path, and looks for
C<use> statements with explicit module version (like C<< use Foo::Bar
 0.01 >>), and from which it sets C<requires> attributes.
B<test_requires_from> commands also takes a file path but of a test
file, and looks for the same C<use> statements to set
B<build_requires> attributes. Both are experimental and only work if
the statements have an explicit version number (which you rarely
append...).

This behavior may change in the future.

=end experimental

=head2 recommends (L<Module::Install::Metadata>)

  recommends 'ExtUtils::Foo::Bar';
  recommends 'ExtUtils::Foo::Baz' => '1.00';

B<recommends> command also takes a module name and a minimum required
version if any. As of this writing, C<recommends> is purely
advisory, only written in the C<META.yml>. Recommended modules will
B<not> usually be installed by the current CPAN toolchains (other
system package managers may possibly prompt you to install them).

=head2 features, feature (L<Module::Install::Metadata>)

  feature( 'share directory support',
    -default => 1,
    'File::ShareDir' => '1.00',
  );

  features(
    'JSON support', [
      -default => 0,
      'JSON' => '2.00',
      'JSON::XS' => '2.00',
    ],
    'YAML support', [
      'YAML' => '0',
    ],
  );

B<feature> command takes a string to describe what the feature is
for, and an array of (optional) modules and their recommended
versions if any. B<features> command takes an array of a description
and an array of modules.

As of this writing, both C<feature> and C<features> work only when 
B<auto_install> (see below) is set. These are used to allow
distribution users to choose what they install along with the
distribution. This may be useful if the distribution has lots of
optional features that may not work on all the platforms, or that
require too many modules for average users.

However, prompting users also hinders automated installation or smoke
testing, and is considered a bad practice (giving sane default
values is much preferred).

Though C<feature>d modules are optional and can be chosen during the
installation, the chosen modules are treated the same as the ones
set by C<requires> command. (They are not listed in the
C<recommends> section in the C<META.yml>). This may change in the
future.

You can add C<< -default => [01] >> in an array of required modules
in the C<feature(s)>, to set a default value for the prompt.

=head1 COMMANDS TO WRITE METADATA

These are the commands to write actual meta files.

=head2 WriteAll (L<Module::Install::WriteAll>)

  use inc::Module::Install;
  
  all_from 'lib/Foo/Bar.pm';
  
  WriteAll;

B<WriteAll> command is usually the last command in the
C<Makefile.PL>. It can take several attributes, but you usually don't
need to care unless you want to write a Makefile for an
L<Inline>-based module. This writes C<Makefile>, C<META.yml>, and
C<MYMETA.yml> (or C<MYMETA.json>) if you set an experimental
environmental variable C<X_MYMETA>.

=head2 WriteMakefile (L<Module::Install::MakeMaker>)

  use inc::Module::Install;
  
  requires 'Foo::Baz';  # a la Module::Install
  
  WriteMakefile(        # a la ExtUtils::MakeMaker
    NAME => 'Foo::Bar',
    VERSION_FROM => 'lib/Foo/Bar.pm',
  );