1Module::AutoInstall(3)User Contributed Perl DocumentationModule::AutoInstall(3)
2
6 Module::AutoInstall - Automatic install of dependencies via CPAN
7
9 In Makefile.PL, with Module::Install available on the author's system:
10 use inc::Module::Install;
12 name 'Joe-Hacker';
14 abstract 'Perl Interface to Joe Hacker';
15 author 'Joe Hacker <joe@hacker.org>';
16 include 'Module::AutoInstall';
17 requires 'Module0'; # mandatory modules
19 feature 'Feature1',
21 -default => 0,
22 'Module2' => '0.1';
23 feature 'Feature2',
25 -default => 0,
26 'Module3' => '1.0';
27 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 WriteAll;
35 Invoking the resulting Makefile.PL:
37 % 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 Note that the trailing 'deps' of arguments may be omitted, too.
45 Using "--defaultdeps" will make Makefile.PL behave similarly to a regu‐
47 lar Makefile.PL file with "PREREQ_PM" dependencies.
48 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 Using make (or nmake):
54 % make [all⎪test⎪install] # install dependencies first
56 % make checkdeps # same as the --checkdeps above
57 % make installdeps # install dependencies only
58
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 This module works best with the Module::Install framework, a drop-in
65 replacement for MakeMaker. However, this module also supports Make‐
66 file.PL files based on MakeMaker; see "EXAMPLES" for instructions.
67 Prerequisites and Features
69 Prerequisites are grouped into features, and the user could choose
71 yes/no on each one's dependencies; the module writer may also supply a
72 boolean value via "-default" to specify the default choice.
73 The Core Features marked by the name "-core" will double-check with the
75 user, if the user chooses not to install the mandatory modules. This
76 differs from the pre-0.26 'silent install' behaviour.
77 Starting from version 0.27, if "-core" is set to the string "all"
79 (case-insensitive), every feature will be considered mandatory.
80 The dependencies are expressed as pairs of "Module" => "version" inside
82 an array reference. If the order does not matter, and there are no
83 "-default", "-tests" or "-skiptests" directives for that feature, you
84 may also use a hash reference.
85 The Installation Process
87 Once Module::AutoInstall has determined which module(s) are needed, it
89 checks whether it's running under the CPAN shell and should therefore
90 let CPAN handle the dependency.
91 Finally, the "WriteMakefile()" is overridden to perform some additional
93 checks, as well as skips tests associated with disabled features by the
94 "-tests" option.
95 The actual installation happens at the end of the "make config" target;
97 both "make test" and "make install" will trigger the installation of
98 required modules.
99 If it's not running under CPAN, the installer will probe for an active
101 connection by trying to resolve the domain "cpan.org", and check for
102 the user's permission to use CPAN. If all went well, a separate
103 CPAN instance is created to install the required modules.
104 If you have the CPANPLUS package installed in your system, it is pre‐
106 ferred by default over CPAN; it also accepts some extra options (e.g.
107 "-target => 'skiptest', -skiptest => 1" to skip testing).
108 All modules scheduled to be installed will be deleted from %INC first,
110 so ExtUtils::MakeMaker will check the newly installed modules.
111 Additionally, you could use the "make installdeps" target to install
113 the modules, and the "make checkdeps" target to check dependencies
114 without actually installing them; the "perl Makefile.PL --checkdeps"
115 command has an equivalent effect.
116 If the Makefile.PL itself needs to use an independent module (e.g.
118 Acme::KillarApp, v1.21 or greater), then use something like below:
119 BEGIN {
121 require Module::AutoInstall;
122 # the first argument is an arrayref of the -config flags
123 Module::AutoInstall->install([], 'Acme::KillerApp' => 1.21);
124 }
125 use Acme::KillerApp 1.21;
126 Module::AutoInstall->import(
128 # ... arguments as usual ...
129 );
130 Note the version test in the use clause; if you are so close to the
132 cutting edge that Acme::KillerApp 1.20 is the latest version on CPAN,
133 this will prevent your module from going awry.
134 User-Defined Hooks
136 User-defined pre-installation and post-installation hooks are available
138 via "MY::preinstall" and "MY::postinstall" subroutines, as shown below:
139 # pre-install handler; takes $module_name and $version
141 sub MY::preinstall { return 1; } # return false to skip install
142 # post-install handler; takes $module_name, $version, $success
144 sub MY::postinstall { return; } # the return value doesn't matter
145 Note that since Module::AutoInstall performs installation at the time
147 of "use" (i.e. before perl parses the remainder of Makefile.PL), you
148 have to declare those two handlers before the "use" statement for them
149 to take effect.
150 If the user did not choose to install a module or it already exists on
152 the system, neither of the handlers is invoked. Both handlers are
153 invoked exactly once for each module when installation is attempted.
154 "MY::preinstall" takes two arguments, $module_name and $version; if it
156 returns a false value, installation for that module will be skipped,
157 and "MY::postinstall" won't be called at all.
158 "MY::postinstall" takes three arguments, $module_name, $version and
160 $success. The last one denotes whether the installation succeeded or
161 not: 1 means installation completed successfully, 0 means failure dur‐
162 ing install, and "undef" means that the installation was not attempted
163 at all, possibly due to connection problems, or that module does not
164 exist on CPAN at all.
165 Customized "MY::postamble"
167 Starting from version 0.43, Module::AutoInstall supports modules that
169 require a "MY::postamble" subroutine in their Makefile.PL. The user-
170 defined "MY::postamble", if present, is responsible for calling "Mod‐
171 ule::AutoInstall::postamble" and include the output in its return
172 value.
173 For example, the DBD::* (database driver) modules for the Perl DBI are
175 required to include the postamble generated by the function "dbd_post‐
176 amble", so their Makefile.PL may contain lines like this:
177 sub MY::postamble {
179 return &Module::AutoInstall::postamble . &dbd_postamble;
180 }
181 Note that the Module::AutoInstall module does not export the "postam‐
183 ble" function, so the name should always be fully qualified.
184
186 Module::AutoInstall will add "UNINST=1" to your make install flags if
187 your effective uid is 0 (root), unless you explicitly disable it by
188 setting CPAN's "make_install_arg" configuration option (or the "make‐
189 flags" option of CPANPLUS) to include "UNINST=0". This may cause
190 dependency problems if you are using a fine-tuned directory structure
191 for your site. Please consult "FAQ" in CPAN for an explanation in
192 detail.
193 If either version or Sort::Versions is available, they will be used to
195 compare the required version with the existing module's version and the
196 CPAN module's. Otherwise it silently falls back to use cmp. This may
197 cause inconsistent behaviours in pathetic situations.
198
200 Module::AutoInstall uses a single environment variable, "PERL_AUTOIN‐
201 STALL". It is taken as the command line argument passed to Make‐
202 file.PL; you could set it to either "--defaultdeps" or "--skipdeps" to
203 avoid interactive behaviour.
204 It also read from the "PERL_EXTUTILS_AUTOINSTALL" environment variable
206 if "PERL_AUTOINSTALL" is not defined.
207
209 Module::Install
210 perlmodlib, ExtUtils::MakeMaker, Sort::Versions, CPAN, CPANPLUS
212
214 Audrey Tang <autrijus@autrijus.org>
215 Adam Kennedy <cpan@ali.as>
217
219 Copyright 2001, 2002, 2003, 2004, 2005, 2006 by Audrey Tang
220 Some parts copyright 2006 Adam Kennedy
222 This program is free software; you can redistribute it and/or modify it
224 under the same terms as Perl itself.
225 See <http://www.perl.com/perl/misc/Artistic.html>
227perl v5.8.8 2007-03-05 Module::AutoInstall(3)