Module::AutoInstall(3)User Contributed Perl DocumentatioModule::AutoInstall(3)NAMEModule::AutoInstall - Automatic install of dependencies via CPAN
SYNOPSIS
In Makefile.PL, with Module::Install available on the author's system:
use inc::Module::Install;
name 'Joe-Hacker';
abstract 'Perl Interface to Joe Hacker';
author 'Joe Hacker <joe@hacker.org>';
include 'Module::AutoInstall';
requires 'Module0'; # mandatory modules
feature 'Feature1',
-default => 0,
'Module2' => '0.1';
feature 'Feature2',
-default => 0,
'Module3' => '1.0';
auto_install(
make_args => '--hello', # option(s) for CPAN::Config
force => 1, # pseudo-option to force install
do_once => 1, # skip previously failed modules
);
WriteAll;
Invoking the resulting Makefile.PL:
% perl Makefile.PL # interactive behaviour
% perl Makefile.PL --defaultdeps # accept default value on prompts
% perl Makefile.PL --checkdeps # check only, no Makefile produced
% perl Makefile.PL --skipdeps # ignores all dependencies
% perl Makefile.PL --testonly # don't write installation targets
Note that the trailing 'deps' of arguments may be omitted, too.
Using "--defaultdeps" will make Makefile.PL behave similarly to a
regular Makefile.PL file with "PREREQ_PM" dependencies.
One can use environment variables (see "ENVIRONMENT") below to set a
default behavior instead of specifying it in the command line for every
invocation of Makefile.PL.
Using make (or nmake):
% make [all|test|install] # install dependencies first
% make checkdeps # same as the --checkdeps above
% make installdeps # install dependencies only
DESCRIPTIONModule::AutoInstall lets module writers to specify a more sophisticated
form of dependency information than the "PREREQ_PM" option offered by
ExtUtils::MakeMaker.
This module works best with the Module::Install framework, a drop-in
replacement for MakeMaker. However, this module also supports
Makefile.PL files based on MakeMaker; see "EXAMPLES" for instructions.
Prerequisites and Features
Prerequisites are grouped into features, and the user could choose
yes/no on each one's dependencies; the module writer may also supply a
boolean value via "-default" to specify the default choice.
The Core Features marked by the name "-core" will double-check with the
user, if the user chooses not to install the mandatory modules. This
differs from the pre-0.26 'silent install' behaviour.
Starting from version 0.27, if "-core" is set to the string "all"
(case-insensitive), every feature will be considered mandatory.
The dependencies are expressed as pairs of "Module" => "version" inside
an array reference. If the order does not matter, and there are no
"-default", "-tests" or "-skiptests" directives for that feature, you
may also use a hash reference.
The Installation Process
Once Module::AutoInstall has determined which module(s) are needed, it
checks whether it's running under the CPAN shell and should therefore
let CPAN handle the dependency.
Finally, the "WriteMakefile()" is overridden to perform some additional
checks, as well as skips tests associated with disabled features by the
"-tests" option.
The actual installation happens at the end of the "make config" target;
both "make test" and "make install" will trigger the installation of
required modules.
If it's not running under CPAN, the installer will probe for an active
connection by trying to resolve the domain "cpan.org", and check for
the user's permission to use CPAN. If all went well, a separate
CPAN instance is created to install the required modules.
If you have the CPANPLUS package installed in your system, it is
preferred by default over CPAN; it also accepts some extra options
(e.g. "-target => 'skiptest', -skiptest => 1" to skip testing).
All modules scheduled to be installed will be deleted from %INC first,
so ExtUtils::MakeMaker will check the newly installed modules.
Additionally, you could use the "make installdeps" target to install
the modules, and the "make checkdeps" target to check dependencies
without actually installing them; the "perl Makefile.PL --checkdeps"
command has an equivalent effect.
If the Makefile.PL itself needs to use an independent module (e.g.
Acme::KillarApp, v1.21 or greater), then use something like below:
BEGIN {
require Module::AutoInstall;
# the first argument is an arrayref of the -config flags
Module::AutoInstall->install([], 'Acme::KillerApp' => 1.21);
}
use Acme::KillerApp 1.21;
Module::AutoInstall->import(
# ... arguments as usual ...
);
Note the version test in the use clause; if you are so close to the
cutting edge that Acme::KillerApp 1.20 is the latest version on CPAN,
this will prevent your module from going awry.
User-Defined Hooks
User-defined pre-installation and post-installation hooks are available
via "MY::preinstall" and "MY::postinstall" subroutines, as shown below:
# pre-install handler; takes $module_name and $version
sub MY::preinstall { return 1; } # return false to skip install
# post-install handler; takes $module_name, $version, $success
sub MY::postinstall { return; } # the return value doesn't matter
Note that since Module::AutoInstall performs installation at the time
of "use" (i.e. before perl parses the remainder of Makefile.PL), you
have to declare those two handlers before the "use" statement for them
to take effect.
If the user did not choose to install a module or it already exists on
the system, neither of the handlers is invoked. Both handlers are
invoked exactly once for each module when installation is attempted.
"MY::preinstall" takes two arguments, $module_name and $version; if it
returns a false value, installation for that module will be skipped,
and "MY::postinstall" won't be called at all.
"MY::postinstall" takes three arguments, $module_name, $version and
$success. The last one denotes whether the installation succeeded or
not: 1 means installation completed successfully, 0 means failure
during install, and "undef" means that the installation was not
attempted at all, possibly due to connection problems, or that module
does not exist on CPAN at all.
Customized "MY::postamble"
Starting from version 0.43, Module::AutoInstall supports modules that
require a "MY::postamble" subroutine in their Makefile.PL. The user-
defined "MY::postamble", if present, is responsible for calling
"Module::AutoInstall::postamble" and include the output in its return
value.
For example, the DBD::* (database driver) modules for the Perl DBI are
required to include the postamble generated by the function
"dbd_postamble", so their Makefile.PL may contain lines like this:
sub MY::postamble {
return &Module::AutoInstall::postamble . &dbd_postamble;
}
Note that the Module::AutoInstall module does not export the
"postamble" function, so the name should always be fully qualified.
CAVEATSModule::AutoInstall will add "UNINST=1" to your make install flags if
your effective uid is 0 (root), unless you explicitly disable it by
setting CPAN's "make_install_arg" configuration option (or the
"makeflags" option of CPANPLUS) to include "UNINST=0". This may cause
dependency problems if you are using a fine-tuned directory structure
for your site. Please consult "FAQ" in CPAN for an explanation in
detail.
If either version or Sort::Versions is available, they will be used to
compare the required version with the existing module's version and the
CPAN module's. Otherwise it silently falls back to use cmp. This may
cause inconsistent behaviours in pathetic situations.
ENVIRONMENTModule::AutoInstall uses a single environment variable,
"PERL_AUTOINSTALL". It is taken as the command line argument passed to
Makefile.PL; you could set it to "--alldeps", "--defaultdeps" or
"--skipdeps" to avoid all interactive behaviour.
"--alldeps" will install all features, while "--defaultdeps" will only
install features for which the default answer is 'y'.
"--skipdeps" will refrain from loading CPAN and not install anything,
unless you're running under CPAN or CPANPLUS, in which case required
dependencies will be installed.
It also read from the "PERL_EXTUTILS_AUTOINSTALL" environment variable
if "PERL_AUTOINSTALL" is not defined.
SEE ALSO
Module::Install
perlmodlib, ExtUtils::MakeMaker, Sort::Versions, CPAN, CPANPLUS
AUTHORS
Audrey Tang <autrijus@autrijus.org>
Adam Kennedy <adamk@cpan.org>
Matt S Trout <mst@shadowcat.co.u>
IF THIS BREAKS
Report a ticket to bugs-Module-Install <at> rt.cpan.org and cc Matt - I
appear to have volunteered as primary maintainer for this stuff so if
you run into any problems please tell me
COPYRIGHT
Copyright 2001, 2002, 2003, 2004, 2005, 2006 by Audrey Tang
Some parts copyright 2006 Adam Kennedy
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See <http://www.perl.com/perl/misc/Artistic.html>
perl v5.14.1 2011-04-27 Module::AutoInstall(3)
