NAME
ExtUtils::AutoInstall - Automatic install of dependencies via CPAN
SYNOPSIS
In Makefile.PL:
# ExtUtils::AutoInstall Bootstrap Code, version 1.
BEGIN { my $p='ExtUtils::AutoInstall'; eval"use $p 0.21;1" or(print
"*** Fetching $p.\n"), require CPAN, CPAN::install $p; eval
"use $p 0.21;1" or die "*** Please install $p manually.\n"}
use ExtUtils::AutoInstall (
-version => '0.21', # ExtUtils::AutoInstall version
-config => {
make_args => '--hello' # option(s) for CPAN::Config
},
-core => [ # core modules
Package0 => '', # any version would do
],
'Feature1' => [
# do we want to install this feature by default?
-default => ( system('feature1 --version') == 0 ),
Package1 => '0.01',
],
'Feature2' => [
# associate tests to be disabled along with this
-tests => [ <t/feature2*.t> ],
Package2 => '0.02',
],
'Feature3' => { # hash reference works, too
Package3 => '0.03',
}
);
WriteMakefile(
AUTHOR => 'Joe Hacker (joe@hacker.org)',
ABSTRACT => 'Perl Interface to Joe Hacker',
NAME => 'Joe::Hacker',
VERSION_FROM => 'Hacker.pm',
DISTNAME => 'Joe-Hacker',
);Invoking the resulting Makefile.PL:
% perl Makefile.PL # default behaviour
% perl Makefile.PL --checkdeps # check only, no Makefile produced
% perl Makefile.PL --skipdeps # ignores all dependenciesUsing make (or nmake):
% make [all|test|install] # default behaviour
% make checkdeps # same as the --checkdeps above
% make installdeps # install dependencies onlyDESCRIPTION
ExtUtils::AutoInstall lets module writers to specify a more sophisticated form of dependency information than the PREREQ_PM option offered by ExtUtils::MakeMaker.
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 is an exception: all missing packages that belongs to it will be installed without prompting the user, unless the user explicitly disables all features via --skipdeps command line option.
The dependencies are expressed as pairs of Module => version inside an a array reference. If the order does not matter, and there are no -default or -tests directives for that feature, you may also use a hash reference.
Once ExtUtils::AutoInstall has determined which module(s) are needed, it checks whether it's running under the CPAN shell and should let CPAN handle the dependency.
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.
All modules scheduled to install will be deleted from %INC first, so ExtUtils::MakeMaker will check the newly installed modules.
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 right after at the end of the make config target; i.e. both make test and make install will trigger the installation of required modules first.
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.
CAVEATS
ExtUtils::AutoInstall will add UNINST=1 to your make install flag if your effective uid is 0 (root), unless you explicitly disable it by setting CPAN's make_install_arg configuration option to include UNINST=0.
This may cause dependency problems if you are using a customized directory structure for your site. Please consult "FAQ" in CPAN for an explanation in detail.
Inline::MakeMaker is not happy with this module, since it prohibits competing MY::postamble functions. Patches welcome.
NOTES
Since this module is needed before writing Makefile, it makes little use as a CPAN module; hence each distribution must include it in full. The only alternative I'm aware of, namely prompting in Makefile.PL to force user install it (cf. the Template Toolkit's dependency on AppConfig) is not very desirable either.
The current compromise is to add this check before every script:
# ExtUtils::AutoInstall Bootstrap Code, version 1.
BEGIN { my $p='ExtUtils::AutoInstall'; eval"use $p 0.21;1" or(print
"*** Fetching $p.\n"), require CPAN, CPAN::install $p; eval
"use $p 0.21;1" or die "*** Please install $p manually.\n"}But that ain't pretty, and won't work without internet connection.
Since we do not want all future options of ExtUtils::AutoInstall to be painfully detected manually like above, this module provides a bootstrapping mechanism via the -version flag. If a newer version is needed by the Makefile.PL, it will go ahead to fetch a new version, reload it into memory, and pass the arguments forward.
If you have any ideas, please let me know. Thanks.
SEE ALSO
perlmodlib, ExtUtils::MakeMaker, CPAN, CPANPLUS
ACKNOWLEDGEMENTS
The test script included in the ExtUtils::AutoInstall distribution contains code adapted from Michael Schwern's Test::More under the Artistic License. Please refer to tests.pl for details.
Thanks also to Jesse Vincent (obra) for suggesting the semantics of various make targets, and Jos Boumans (kane) for introducing me to his CPANPLUS project.
AUTHORS
Autrijus Tang <autrijus@autrijus.org>
COPYRIGHT
Copyright 2001 by Autrijus Tang <autrijus@autrijus.org>.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.