| Module::Install::FAQ - Frequently Asked Questions for Module::Install |
Module::Install::FAQ - Frequently Asked Questions for Module::Install
Though the Module::Install manpage 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 the Module::Install manpage.
The point of the Module::Install manpage is let module authors take care of everything related to updating toolchains for the sake of module users. So, if you choose to use the Module::Install manpage, it's you who should update toolchains, i.e. the Module::Install manpage 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. the Module::Install manpage is not only a tool to write better, but also a tool to encourage you to help others.
Not at all, using auto_install() is just fine. While it indeed
behaved erratically in older the Module::Install manpage versions, there have
been no reported issues since mid-2009. As far as compatibility with
various CPAN clients: several rather large projects on CPAN (including
Catalyst and the DBIx::Class manpage), are using 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 auto_install.
If your the CPAN manpage 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 the App::cpanminus manpage,
with which you even can write like cpanm --installdeps .
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 the Module::Install manpage 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 the Module::Install manpage 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.
the Module::Install manpage 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, the Module::Install manpage 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.
the Module::Install manpage 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, the Module::Install manpage 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 the Module::Install manpage 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.
the Module::Install manpage is just a wrapper of the ExtUtils::MakeMaker manpage. You
can do almost everything you can do with the ExtUtils::MakeMaker manpage by
passing arbitrary attributes to the ExtUtils::MakeMaker manpage in the backend
via 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 the Module::Install manpage, it may fail to process Makefile.PLs in subdirectories correctly now, and you may need to override attributes explicitly in some cases where the Module::Install manpage provides other default values than the ExtUtils::MakeMaker manpage does. Please see also the the ExtUtils::MakeMaker manpage's pod for further instructions.
the ExtUtils::MakeMaker manpage (and the Module::Build manpage 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 <ishigaki@cpan.org>
Copyright 2010 Kenichi Ishigaki.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
| Module::Install::FAQ - Frequently Asked Questions for Module::Install |