View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Adam Kennedy > Module-Install-0.99 > Module::Install::FAQ


Annotate this POD


New  40
Open  32
Stalled  2
View/Report Bugs
Source   Latest Release: Module-Install-1.19


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


Though 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 Module::Install.

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

The point of 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 Module::Install, it's you who should update toolchains, i.e. 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. Module::Install is not only a tool to write better, but also a tool to encourage you to help others.

Do I really have to avoid auto_install()?

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 auto_install() is still discouraged, especially if what you are writing is a module to be uploaded on the CPAN. 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 CPAN and CPANPLUS as its backends. If you use other tools to install, it may still cause a trouble.

Besides, now you can do what auto_install() does with other means. If your CPAN module is new enough, you can pass a dot to the cpan command it provides, and it will install all the required distributions from the CPAN:

  $ cpan .

The same is true for the cpanm command from App::cpanminus, with which you even can write like cpanm --installdeps .. You don't need to stick to the auto_install() at all.

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

So, if you know what you're doing, and want (or want to give) more freedom, auto_install() may still help you, especially when you're distributing an application independently. Otherwise, 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.

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 Module::Install you have (the inc directory is recreated each time you run perl Makefile.PL).

If not, but you alone are the release manager and know what you have to do when you release, putting the 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 Module::Install works and don't know what you have to do in the above situation, don't put it in the repository. It may be the cause of troubles including a wrong version in the META.yml.

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

What're there in the "inc" directory?

Module::Install puts its components (sometimes with extra modules) under the 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 inc directory, Module::Install will automatically create it when you run perl Makefile.PL. And if that happens, a directory (as of this writing, .author) will also be created under the inc directory. If the .author directory exists, the inc directory will be recreated each time you run perl Makefile.PL to make sure everything you need is included and up-to-date. This .author directory will not be included in a distribution.

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

Module::Install uses an Autoloader magic to delegate command handling to the extensions in the 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, 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 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 inc directory before you ask.

This usually does not happen in the user land as distributions that use Module::Install should have all the necessary extensions under the 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.

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

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

  use inc::Module::Install;
  all_from 'lib/Foo/';
    dist => { PREOP => '...' },
    PL_FILES => {'bin/foobar.PL' => 'bin/foobar'},

However, by the singleton nature of 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 Module::Install provides other default values than ExtUtils::MakeMaker does. Please see also the ExtUtils::MakeMaker's pod for further instructions.

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

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

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

  makemaker_args(PL_FILES => {});


Kenichi Ishigaki <>


Copyright 2010 Kenichi Ishigaki.

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

syntax highlighting: