libmodule-install-perl 1.04-1 / usr / share / perl5 / Module / Install / FAQ.pod

=pod

=head1 NAME

Module::Install::FAQ - Frequently Asked Questions for Module::Install

=head1 DESCRIPTION

Though L<Module::Install> itself has a general FAQ section in the
pod, it's more for advocacy. Here's an incomplete and growing list of
the actual questions I have been frequently asked (or found on the
net) about L<Module::Install>.

=head2 Do I also have to update my CPAN modules every time Module::Install is updated?

The point of L<Module::Install> is let module authors take care of
everything related to updating toolchains for the sake of module
users. So, if you choose to use L<Module::Install>, it's you who
should update toolchains, i.e. L<Module::Install> and other bundled
modules. You should check if there's any significant change/fix in
your toolchains. You should check if your toolchains go along with
other tools users use to install your distributions, or with
the systems users are in, or whatever that matters. In the end,
you are expected to have much more knowledge and willingness than
average users.

That being said, practically, you don't have to update your
distributions if they are working well. But if you do find issues,
please update your distributions, even when you have nothing to
change in your own modules. L<Module::Install> is not only a tool to
write better, but also a tool to encourage you to help others.

=head2 Do I really have to avoid auto_install()?

Not at all, B<using C<auto_install()> is just fine>. While it indeed
behaved erratically in older L<Module::Install> versions, there have
been no reported issues since mid-2009. As far as compatbility with
various CPAN clients: several rather large projects on CPAN (including
L<Catalyst> and L<DBIx::Class>), are using C<auto_install> without any
issues reported by their substantial userbases.

That said, if all you want to do is make it easy for a contributor to
checkout your code and quickly install necessary dependencies, there
are alternatives to C<auto_install>.

If your L<CPAN> module is new enough, you can pass a dot to the
B<cpan> command it provides, and it will install all the required
distributions from the CPAN:

  $ cpan .

The same is true for the B<cpanm> command from L<App::cpanminus>,
with which you even can write like C<< cpanm --installdeps . >>

=head2 Should I put an "inc" directory Module::Install automatically creates into a repository for my projects?

Depends. If the repository is private and only for you, you usually
don't want to put it in your repository to let you always use the
latest L<Module::Install> you have (the C<inc> directory is recreated
each time you run C<perl Makefile.PL>).

If not, but you alone are the release manager and know what you have
to do when you release, putting the C<inc> directory into your
repository may help other casual contributors, especially if you use
minor (or private) non-core extensions in your Makefile.PL.

However, if you generously allow other people to release, or you're
not so familiar with how L<Module::Install> works and don't know what
you have to do in the above situation, B<don't> put it in the
repository. It may be the cause of troubles including a wrong version
in the C<META.yml>.

If you feel sorry about the inconvenience for your fellow
contributors, you may want to add explicitly C<< use
Module::Install::<ExtensionYouWantToUse>; >> after C<< use
inc::Module::Install; >> in your Makefile.PL. It doesn't do any harm,
and it makes clear which extensions they need to install.

=head2 What're there in the "inc" directory?

L<Module::Install> puts its components (sometimes with extra modules)
under the C<inc> directory to be released with a distribution.
Those modules will not be installed into your system, unless
explicitly copied into somewhere. They are only used to help
configuration, tests, and/or installation.

If there's no C<inc> directory, L<Module::Install> will automatically
create it when you run C<perl Makefile.PL>. And if that happens,
a directory (as of this writing, C<.author>) will also be created
under the C<inc> directory. If the C<.author> directory exists,
the C<inc> directory will be recreated each time you run C<perl
Makefile.PL> to make sure everything you need is included and
up-to-date. This C<.author> directory will not be included in
a distribution.

=head2 "perl Makefile.PL" doesn't work or does a strange behavior for me. Why?

L<Module::Install> uses an Autoloader magic to delegate command
handling to the extensions in the C<inc> directory. This works while
everything is in order, but when it finds something it can't
understands, it dies with a compile error, or does what you don't
expect.

To prevent the latter strange behavior, L<Module::Install> 0.96 and
above dies when it tries to process unknown commands. In most cases
(other than typos), these unknown commands are from non-core extensions
on the CPAN, and they should hopefully have predictable names
that you can easily tell from which extension they come, though some
may be a bit hard to find.

If you are trying to contribute to some project, and having a trouble
to run C<Makefile.PL>, please contact the author of the project to
learn what you have to install. If the distribution is already on the
CPAN, you may also want to look into the MANIFEST file to see which
extensions are included in the C<inc> directory before you ask.

This usually does not happen in the user land as distributions that
use L<Module::Install> should have all the necessary extensions under
the C<inc> directory. If this should happen, that's most probably
because the release manager shipped the distribution under a
non-author mode. Please contact the author to fix the issue.

=head2 Why can't I do <anything> with Module::Install that I can do with ExtUtils::MakeMaker?

L<Module::Install> is just a wrapper of L<ExtUtils::MakeMaker>. You
can do almost everything you can do with L<ExtUtils::MakeMaker> by
passing arbitrary attributes to L<ExtUtils::MakeMaker> in the backend
via C<makemaker_args> like this:

  use inc::Module::Install;
  
  all_from 'lib/Foo/Bar.pm';
  
  makemaker_args(
    dist => { PREOP => '...' },
    PL_FILES => {'bin/foobar.PL' => 'bin/foobar'},
  );
  WriteAll;

However, by the singleton nature of L<Module::Install>, it may fail
to process Makefile.PLs in subdirectories correctly now, and you may
need to override attributes explicitly in some cases where
L<Module::Install> provides other default values than
L<ExtUtils::MakeMaker> does. Please see also the
L<ExtUtils::MakeMaker>'s pod for further instructions.

=head2 I added MyMakefile.PL to my distribution, but it doesn't work as I expected. Why?

L<ExtUtils::MakeMaker> (and L<Module::Build> also) treats
C<*.PL> files in the top level directory as something special
to generate other files. So, if you add something that has
C<.PL> extension like C<MyMakefile.PL> in the top level
directory, it also runs automatically when you run Makefile.PL.

If you don't like this behavior, use C<makemaker_args> to pass
an anonymous hash to C<PL_FILES>.

  makemaker_args(PL_FILES => {});

=begin todo

=head2 Some of the tests in bundled distributions fail which don't when you install them one by one. Why?

=head2 It looks like some of the bundled distribution are not installed. Why?

=head2 Included ExtUtils::MakeMaker doesn't work correctly. Why?

=end todo

=head1 AUTHOR

Kenichi Ishigaki E<lt>ishigaki@cpan.orgE<gt>

=head1 COPYRIGHT

Copyright 2010 Kenichi Ishigaki.

This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=cut