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           % make installdeps_notest           # same without running tests
59           % make upgradedeps                  # upgrade all deps, even if installed
60           % make upgradedeps_notest           # same without running tests
61           % make listdeps                     # print unsatisifed deps, one per line
62           % make listalldeps                  # print all deps, one per line
63

DESCRIPTION

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

CAVEATS

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

ENVIRONMENT

205       Module::AutoInstall uses a single environment variable,
206       "PERL_AUTOINSTALL".  It is taken as the command line argument passed to
207       Makefile.PL; you could set it to "--alldeps", "--defaultdeps" or
208       "--skipdeps" to avoid all interactive behaviour.
209
210       "--alldeps" will install all features, while "--defaultdeps" will only
211       install features for which the default answer is 'y'.
212
213       "--skipdeps" will refrain from loading CPAN and not install anything,
214       unless you're running under CPAN or CPANPLUS, in which case required
215       dependencies will be installed.
216
217       It is also read from the "PERL_EXTUTILS_AUTOINSTALL" environment
218       variable if "PERL_AUTOINSTALL" is not defined.
219
220       You can also set "PERL_AUTOINSTALL_PREFER_CPAN" to use CPAN to install
221       dependencies. By default CPANPLUS is used.
222

SEE ALSO

224       Module::Install
225
226       perlmodlib, ExtUtils::MakeMaker, Sort::Versions, CPAN, CPANPLUS
227

AUTHORS

229       Audrey Tang <autrijus@autrijus.org>
230
231       Adam Kennedy <adamk@cpan.org>
232
233       Matt S Trout <mst@shadowcat.co.u>
234

IF THIS BREAKS

236       Report a ticket to bugs-Module-Install <at> rt.cpan.org and cc Matt - I
237       appear to have volunteered as primary maintainer for this stuff so if
238       you run into any problems please tell me
239
241       Copyright 2001, 2002, 2003, 2004, 2005, 2006 by Audrey Tang
242
243       Some parts copyright 2006 Adam Kennedy
244
245       This program is free software; you can redistribute it and/or modify it
246       under the same terms as Perl itself.
247
248       See <http://www.perl.com/perl/misc/Artistic.html>
249
250
251
252perl v5.16.3                      2012-03-01            Module::AutoInstall(3)
Impressum