1Module::AutoInstall(3)User Contributed Perl DocumentationModule::AutoInstall(3)
2
3
4

NAME

6       Module::AutoInstall - Automatic install of dependencies via CPAN
7

SYNOPSIS

9       In Makefile.PL, with Module::Install available on the author's system:
10
11           use inc::Module::Install;
12
13           name        'Joe-Hacker';
14           abstract    'Perl Interface to Joe Hacker';
15           author      'Joe Hacker <joe@hacker.org>';
16           include     'Module::AutoInstall';
17
18           requires    'Module0';          # mandatory modules
19
20           feature     'Feature1',
21               -default    => 0,
22               'Module2'   => '0.1';
23
24           feature     'Feature2',
25               -default    => 0,
26               'Module3'   => '1.0';
27
28           auto_install(
29               make_args   => '--hello',   # option(s) for CPAN::Config
30               force       => 1,           # pseudo-option to force install
31               do_once     => 1,           # skip previously failed modules
32           );
33
34           WriteAll;
35
36       Invoking the resulting Makefile.PL:
37
38           % perl Makefile.PL                  # interactive behaviour
39           % perl Makefile.PL --defaultdeps    # accept default value on prompts
40           % perl Makefile.PL --checkdeps      # check only, no Makefile produced
41           % perl Makefile.PL --skipdeps       # ignores all dependencies
42           % perl Makefile.PL --testonly       # don't write installation targets
43
44       Note that the trailing 'deps' of arguments may be omitted, too.
45
46       Using "--defaultdeps" will make Makefile.PL behave similarly to a
47       regular Makefile.PL file with "PREREQ_PM" dependencies.
48
49       One can use environment variables (see "ENVIRONMENT") below to set a
50       default behavior instead of specifying it in the command line for every
51       invocation of Makefile.PL.
52
53       Using make (or nmake):
54
55           % make [all|test|install]           # install dependencies first
56           % make checkdeps                    # same as the --checkdeps above
57           % make installdeps                  # install dependencies only
58

DESCRIPTION

60       Module::AutoInstall lets module writers to specify a more sophisticated
61       form of dependency information than the "PREREQ_PM" option offered by
62       ExtUtils::MakeMaker.
63
64       This module works best with the Module::Install framework, a drop-in
65       replacement for MakeMaker.  However, this module also supports
66       Makefile.PL files based on MakeMaker; see "EXAMPLES" for instructions.
67
68   Prerequisites and Features
69       Prerequisites are grouped into features, and the user could choose
70       yes/no on each one's dependencies; the module writer may also supply a
71       boolean value via "-default" to specify the default choice.
72
73       The Core Features marked by the name "-core" will double-check with the
74       user, if the user chooses not to install the mandatory modules.  This
75       differs from the pre-0.26 'silent install' behaviour.
76
77       Starting from version 0.27, if "-core" is set to the string "all"
78       (case-insensitive), every feature will be considered mandatory.
79
80       The dependencies are expressed as pairs of "Module" => "version" inside
81       an array reference.  If the order does not matter, and there are no
82       "-default", "-tests" or "-skiptests" directives for that feature, you
83       may also use a hash reference.
84
85   The Installation Process
86       Once Module::AutoInstall has determined which module(s) are needed, it
87       checks whether it's running under the CPAN shell and should therefore
88       let CPAN handle the dependency.
89
90       Finally, the "WriteMakefile()" is overridden to perform some additional
91       checks, as well as skips tests associated with disabled features by the
92       "-tests" option.
93
94       The actual installation happens at the end of the "make config" target;
95       both "make test" and "make install" will trigger the installation of
96       required modules.
97
98       If it's not running under CPAN, the installer will probe for an active
99       connection by trying to resolve the domain "cpan.org", and check for
100       the user's permission to use CPAN.  If all went well, a separate
101           CPAN instance is created to install the required modules.
102
103       If you have the CPANPLUS package installed in your system, it is
104       preferred by default over CPAN; it also accepts some extra options
105       (e.g. "-target => 'skiptest', -skiptest => 1" to skip testing).
106
107       All modules scheduled to be installed will be deleted from %INC first,
108       so ExtUtils::MakeMaker will check the newly installed modules.
109
110       Additionally, you could use the "make installdeps" target to install
111       the modules, and the "make checkdeps" target to check dependencies
112       without actually installing them; the "perl Makefile.PL --checkdeps"
113       command has an equivalent effect.
114
115       If the Makefile.PL itself needs to use an independent module (e.g.
116       Acme::KillarApp, v1.21 or greater), then use something like below:
117
118           BEGIN {
119               require Module::AutoInstall;
120               # the first argument is an arrayref of the -config flags
121               Module::AutoInstall->install([], 'Acme::KillerApp' => 1.21);
122           }
123           use Acme::KillerApp 1.21;
124
125           Module::AutoInstall->import(
126               # ... arguments as usual ...
127           );
128
129       Note the version test in the use clause; if you are so close to the
130       cutting edge that Acme::KillerApp 1.20 is the latest version on CPAN,
131       this will prevent your module from going awry.
132
133   User-Defined Hooks
134       User-defined pre-installation and post-installation hooks are available
135       via "MY::preinstall" and "MY::postinstall" subroutines, as shown below:
136
137           # pre-install handler; takes $module_name and $version
138           sub MY::preinstall  { return 1; } # return false to skip install
139
140           # post-install handler; takes $module_name, $version, $success
141           sub MY::postinstall { return; }   # the return value doesn't matter
142
143       Note that since Module::AutoInstall performs installation at the time
144       of "use" (i.e. before perl parses the remainder of Makefile.PL), you
145       have to declare those two handlers before the "use" statement for them
146       to take effect.
147
148       If the user did not choose to install a module or it already exists on
149       the system, neither of the handlers is invoked.  Both handlers are
150       invoked exactly once for each module when installation is attempted.
151
152       "MY::preinstall" takes two arguments, $module_name and $version; if it
153       returns a false value, installation for that module will be skipped,
154       and "MY::postinstall" won't be called at all.
155
156       "MY::postinstall" takes three arguments, $module_name, $version and
157       $success.  The last one denotes whether the installation succeeded or
158       not: 1 means installation completed successfully, 0 means failure
159       during install, and "undef" means that the installation was not
160       attempted at all, possibly due to connection problems, or that module
161       does not exist on CPAN at all.
162
163   Customized "MY::postamble"
164       Starting from version 0.43, Module::AutoInstall supports modules that
165       require a "MY::postamble" subroutine in their Makefile.PL.  The user-
166       defined "MY::postamble", if present, is responsible for calling
167       "Module::AutoInstall::postamble" and include the output in its return
168       value.
169
170       For example, the DBD::* (database driver) modules for the Perl DBI are
171       required to include the postamble generated by the function
172       "dbd_postamble", so their Makefile.PL may contain lines like this:
173
174           sub MY::postamble {
175               return &Module::AutoInstall::postamble . &dbd_postamble;
176           }
177
178       Note that the Module::AutoInstall module does not export the
179       "postamble" function, so the name should always be fully qualified.
180

CAVEATS

182       Module::AutoInstall will add "UNINST=1" to your make install flags if
183       your effective uid is 0 (root), unless you explicitly disable it by
184       setting CPAN's "make_install_arg" configuration option (or the
185       "makeflags" option of CPANPLUS) to include "UNINST=0".  This may cause
186       dependency problems if you are using a fine-tuned directory structure
187       for your site.  Please consult "FAQ" in CPAN for an explanation in
188       detail.
189
190       If either version or Sort::Versions is available, they will be used to
191       compare the required version with the existing module's version and the
192       CPAN module's.  Otherwise it silently falls back to use cmp.  This may
193       cause inconsistent behaviours in pathetic situations.
194

ENVIRONMENT

196       Module::AutoInstall uses a single environment variable,
197       "PERL_AUTOINSTALL".  It is taken as the command line argument passed to
198       Makefile.PL; you could set it to "--alldeps", "--defaultdeps" or
199       "--skipdeps" to avoid all interactive behaviour.
200
201       "--alldeps" will install all features, while "--defaultdeps" will only
202       install features for which the default answer is 'y'.
203
204       "--skipdeps" will refrain from loading CPAN and not install anything,
205       unless you're running under CPAN or CPANPLUS, in which case required
206       dependencies will be installed.
207
208       It also read from the "PERL_EXTUTILS_AUTOINSTALL" environment variable
209       if "PERL_AUTOINSTALL" is not defined.
210

SEE ALSO

212       Module::Install
213
214       perlmodlib, ExtUtils::MakeMaker, Sort::Versions, CPAN, CPANPLUS
215

AUTHORS

217       Audrey Tang <autrijus@autrijus.org>
218
219       Adam Kennedy <adamk@cpan.org>
220
221       Matt S Trout <mst@shadowcat.co.u>
222

IF THIS BREAKS

224       Report a ticket to bugs-Module-Install <at> rt.cpan.org and cc Matt - I
225       appear to have volunteered as primary maintainer for this stuff so if
226       you run into any problems please tell me
227
229       Copyright 2001, 2002, 2003, 2004, 2005, 2006 by Audrey Tang
230
231       Some parts copyright 2006 Adam Kennedy
232
233       This program is free software; you can redistribute it and/or modify it
234       under the same terms as Perl itself.
235
236       See <http://www.perl.com/perl/misc/Artistic.html>
237
238
239
240perl v5.10.1                      2009-05-27            Module::AutoInstall(3)
Impressum