=pod

=head1 NAME

Module::Install::FAQ

=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 really have to avoid auto_install()?

B<auto_install()> has a long history of breaking CPAN toolchains.
Lots of people had a bad feeling on it, and have said it should be
strongly avoided. In fact it was deprecated and removed once.

Although most of the known problems have been fixed and you can use
it more safely than ever, the use of C<auto_install()> is still
discouraged, especially if what you are writing is a module to be
uploaded on the CPAN. C<auto_install()> does lots of things itself,
thus does not always do the same things as other toolchains do
(including extra attribute handling, etc; which can be fixed somehow
but that's not too DRY). It only supports L<CPAN> and L<CPANPLUS> as
its backends. If you use other tools to install, it may still cause a
trouble.

Besides, now you can do what C<auto_install()> does with other means.
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 . >>. You
don't need to stick to the C<auto_install()> at all.

That being said, C<auto_install()> still has its own merit. For one
thing, C<features()>, which is convenient if you want users to choose
what they install, is only supported under the C<auto_install()>
mode now.

So, if you know what you're doing, and want (or want to give) more
freedom, C<auto_install()> may still help you, especially when you're
distributing an application independently. Otherwise,
C<auto_install()> should be avoided. There're alternatives, and
giving sane default is much better than suspending (automatic)
installation process by prompting people to choose something.

=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 when 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) not-in-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 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 "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,
these unknown commands are from non-core extensions on the CPAN
(otherwise, typos), 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 can't
process Makefile.PL 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 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 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.

=begin todo

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

=head2 What is an author mode?

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

=head2 Some of the tests in bundled distributions fail which doesn'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
