1ExtUtils::AutoInstall(3U)ser Contributed Perl DocumentatiEoxntUtils::AutoInstall(3)
2
6 ExtUtils::AutoInstall - Automatic install of dependencies via CPAN
7
9 This document describes version 0.63 of ExtUtils::AutoInstall, released
10 September 12, 2005.
11
13 In Makefile.PL, with Module::Install available on the author's system:
14 use inc::Module::Install;
16 name ('Joe-Hacker');
18 abstract ('Perl Interface to Joe Hacker');
19 author ('Joe Hacker <joe@hacker.org>');
20 include ('ExtUtils::AutoInstall');
21 requires ('Module0'); # mandatory modules
23 features (
24 -config => {
25 make_args => '--hello', # option(s) for CPAN::Config
26 force => 1, # pseudo-option to force install
27 do_once => 1, # skip previously failed modules
28 },
29 'Feature1' => [
30 'Module2' => '0.1',
31 ],
32 'Feature2' => [
33 'Module3' => '1.0',
34 ],
35 );
36 auto_install();
37 &WriteAll;
38 Invoking the resulting Makefile.PL:
40 % perl Makefile.PL # interactive behaviour
42 % perl Makefile.PL --defaultdeps # accept default value on prompts
43 % perl Makefile.PL --checkdeps # check only, no Makefile produced
44 % perl Makefile.PL --skipdeps # ignores all dependencies
45 % perl Makefile.PL --testonly # don't write installation targets
46 Note that the trailing 'deps' of arguments may be omitted, too.
48 Using "--defaultdeps" will make Makefile.PL behave similarly to a regu‐
50 lar Makefile.PL file with "PREREQ_PM" dependencies.
51 One can use environment variables (see "ENVIRONMENT") below to set a
53 default behavior instead of specifying it in the command line for every
54 invocation of Makefile.PL.
55 Using make (or nmake):
57 % make [all⎪test⎪install] # install dependencies first
59 % make checkdeps # same as the --checkdeps above
60 % make installdeps # install dependencies only
61
63 ExtUtils::AutoInstall lets module writers to specify a more sophisti‐
64 cated form of dependency information than the "PREREQ_PM" option
65 offered by ExtUtils::MakeMaker.
66 This module works best with the Module::Install framework, a drop-in
68 replacement for MakeMaker. However, this module also supports Make‐
69 file.PL files based on MakeMaker; see "EXAMPLES" for instructions.
70 Prerequisites and Features
72 Prerequisites are grouped into features, and the user could choose
74 yes/no on each one's dependencies; the module writer may also supply a
75 boolean value via "-default" to specify the default choice.
76 The Core Features marked by the name "-core" will double-check with the
78 user, if the user chooses not to install the mandatory modules. This
79 differs from the pre-0.26 'silent install' behaviour.
80 Starting from version 0.27, if "-core" is set to the string "all"
82 (case-insensitive), every feature will be considered mandatory.
83 The dependencies are expressed as pairs of "Module" => "version" inside
85 an array reference. If the order does not matter, and there are no
86 "-default", "-tests" or "-skiptests" directives for that feature, you
87 may also use a hash reference.
88 The Installation Process
90 Once ExtUtils::AutoInstall has determined which module(s) are needed,
92 it checks whether it's running under the CPAN shell and should there‐
93 fore let CPAN handle the dependency.
94 Finally, the "WriteMakefile()" is overridden to perform some additional
96 checks, as well as skips tests associated with disabled features by the
97 "-tests" option.
98 The actual installation happens at the end of the "make config" target;
100 both "make test" and "make install" will trigger the installation of
101 required modules.
102 If it's not running under CPAN, the installer will probe for an active
104 connection by trying to resolve the domain "cpan.org", and check for
105 the user's permission to use CPAN. If all went well, a separate
106 CPAN instance is created to install the required modules.
107 If you have the CPANPLUS package installed in your system, it is pre‐
109 ferred by default over CPAN; it also accepts some extra options (e.g.
110 "-target => 'skiptest', -skiptest => 1" to skip testing).
111 All modules scheduled to be installed will be deleted from %INC first,
113 so ExtUtils::MakeMaker will check the newly installed modules.
114 Additionally, you could use the "make installdeps" target to install
116 the modules, and the "make checkdeps" target to check dependencies
117 without actually installing them; the "perl Makefile.PL --checkdeps"
118 command has an equivalent effect.
119 If the Makefile.PL itself needs to use an independent module (e.g.
121 Acme::KillarApp, v1.21 or greater), then use something like below:
122 BEGIN {
124 require ExtUtils::AutoInstall;
125 # the first argument is an arrayref of the -config flags
126 ExtUtils::AutoInstall->install([], 'Acme::KillerApp' => 1.21);
127 }
128 use Acme::KillerApp 1.21;
129 ExtUtils::AutoInstall->import(
131 # ... arguments as usual ...
132 );
133 Note the version test in the use clause; if you are so close to the
135 cutting edge that Acme::KillerApp 1.20 is the latest version on CPAN,
136 this will prevent your module from going awry.
137 User-Defined Hooks
139 User-defined pre-installation and post-installation hooks are available
141 via "MY::preinstall" and "MY::postinstall" subroutines, as shown below:
142 # pre-install handler; takes $module_name and $version
144 sub MY::preinstall { return 1; } # return false to skip install
145 # post-install handler; takes $module_name, $version, $success
147 sub MY::postinstall { return; } # the return value doesn't matter
148 Note that since ExtUtils::AutoInstall performs installation at the time
150 of "use" (i.e. before perl parses the remainder of Makefile.PL), you
151 have to declare those two handlers before the "use" statement for them
152 to take effect.
153 If the user did not choose to install a module or it already exists on
155 the system, neither of the handlers is invoked. Both handlers are
156 invoked exactly once for each module when installation is attempted.
157 "MY::preinstall" takes two arguments, $module_name and $version; if it
159 returns a false value, installation for that module will be skipped,
160 and "MY::postinstall" won't be called at all.
161 "MY::postinstall" takes three arguments, $module_name, $version and
163 $success. The last one denotes whether the installation succeeded or
164 not: 1 means installation completed successfully, 0 means failure dur‐
165 ing install, and "undef" means that the installation was not attempted
166 at all, possibly due to connection problems, or that module does not
167 exist on CPAN at all.
168 Customized "MY::postamble"
170 Starting from version 0.43, ExtUtils::AutoInstall supports modules that
172 require a "MY::postamble" subroutine in their Makefile.PL. The user-
173 defined "MY::postamble", if present, is responsible for calling "ExtU‐
174 tils::AutoInstall::postamble" and include the output in its return
175 value.
176 For example, the DBD::* (database driver) modules for the Perl DBI are
178 required to include the postamble generated by the function "dbd_post‐
179 amble", so their Makefile.PL may contain lines like this:
180 sub MY::postamble {
182 return &ExtUtils::AutoInstall::postamble . &dbd_postamble;
183 }
184 Note that the ExtUtils::AutoInstall module does not export the "postam‐
186 ble" function, so the name should always be fully qualified.
187
189 ExtUtils::AutoInstall will add "UNINST=1" to your make install flags if
190 your effective uid is 0 (root), unless you explicitly disable it by
191 setting CPAN's "make_install_arg" configuration option (or the "make‐
192 flags" option of CPANPLUS) to include "UNINST=0". This may cause
193 dependency problems if you are using a fine-tuned directory structure
194 for your site. Please consult "FAQ" in CPAN for an explanation in
195 detail.
196 If either version or Sort::Versions is available, they will be used to
198 compare the required version with the existing module's version and the
199 CPAN module's. Otherwise it silently falls back to use cmp. This may
200 cause inconsistent behaviours in pathetic situations.
201
203 Since this module is needed before writing Makefile, it makes little
204 use as a CPAN module; hence each distribution must include it in full.
205 The only alternative I'm aware of, namely prompting in Makefile.PL to
206 force user install it (cf. the Template Toolkit's dependency on AppCon‐
207 fig) is not very desirable either.
208 The current compromise is to add the bootstrap code listed in the "SYN‐
210 OPSIS" before every script, but that does not look pretty, and will not
211 work without an Internet connection.
212 Since we do not want all future options of ExtUtils::AutoInstall to be
214 painfully detected manually like above, this module provides a boot‐
215 strapping mechanism via the "-version" flag. If a newer version is
216 needed by the Makefile.PL, it will go ahead to fetch a new version,
217 reload it into memory, and pass the arguments forward.
218 If you have any suggestions, please let me know. Thanks.
220
222 ExtUtils::AutoInstall uses a single environment variable, "PERL_EXTU‐
223 TILS_AUTOINSTALL". It is taken as the command line argument passed to
224 Makefile.PL; you could set it to either "--defaultdeps" or "--skipdeps"
225 to avoid interactive behaviour.
226
228 Using MakeMaker with AutoInstall
229 To use this module with ExtUtils::MakeMaker, first make a inc/ExtUtils/
231 subdirectory in the directory containing your Makefile.PL, and put a
232 copy this module under it as inc/ExtUtils/AutoInstall.pm. You can find
233 out where this module has been installed by typing "perldoc -l ExtU‐
234 tils::AutoInstall" in the command line.
235 Your Makefile.PL should look like this:
237 # pull in ExtUtils/AutoInstall.pm from 'inc'
239 use lib 'inc';
240 use ExtUtils::AutoInstall (
241 -core => [ # mandatory modules
242 'Module0' => '', # any version would suffice
243 ],
244 'Feature1' => [
245 # do we want to install this feature by default?
246 -default => ( system('feature1 --version') == 0 ),
247 Module1 => '0.01',
248 ],
249 'Feature2' => [
250 # associate tests to be disabled if this feature is missing
251 -tests => [ <t/feature2*.t> ],
252 # associate tests to be disabled if this feature is present
253 -skiptests => [ <t/nofeature2*.t> ],
254 Module2 => '0.02',
255 ],
256 'Feature3' => { # hash reference works, too
257 # force installation even if tests fail
258 Module2 => '0.03',
259 }
260 );
261 WriteMakefile(
263 AUTHOR => 'Joe Hacker <joe@hacker.org>',
264 ABSTRACT => 'Perl Interface to Joe Hacker',
265 NAME => 'Joe::Hacker',
266 VERSION_FROM => 'Hacker.pm',
267 DISTNAME => 'Joe-Hacker',
268 );
269 Self-Download Code
271 If you do not wish to put a copy of ExtUtils::AutoInstall under inc/,
273 and are confident that users will have internet access, you may replace
274 the "use lib 'inc';" line with this block of code:
275 # ExtUtils::AutoInstall Bootstrap Code, version 7.
277 BEGIN{my$p='ExtUtils::AutoInstall';my$v=0.45;$p->VERSION⎪⎪0>=$v
278 or+eval"use $p $v;1"or+do{my$e=$ENV{PERL_EXTUTILS_AUTOINSTALL};
279 (!defined($e)⎪⎪$e!~m/--(?:default⎪skip⎪testonly)/and-t STDIN or
280 eval"use ExtUtils::MakeMaker;WriteMakefile(PREREQ_PM=>{'$p',$v}
281 );1"and exit)and print"==> $p $v required. Install it from CP".
282 "AN? [Y/n] "and<STDIN>!~/^n/i and print"*** Installing $p\n"and
283 do{if (eval '$>' and lc(`sudo -V`) =~ /version/){system('sudo',
284 $^X,"-MCPANPLUS","-e","CPANPLUS::install $p");eval"use $p $v;1"
285 ⎪⎪system('sudo', $^X, "-MCPAN", "-e", "CPAN::install $p")}eval{
286 require CPANPLUS;CPANPLUS::install$p};eval"use $p $v;1"or eval{
287 require CPAN;CPAN::install$p};eval"use $p $v;1"⎪⎪die"*** Please
288 manually install $p $v from cpan.org first...\n"}}}
289 If the user did not have ExtUtils::AutoInstall installed, the block of
291 code above will automatically download and install it.
292 However, due to its space-compressed (and obfuscated) nature, you
294 should think twice before employing this block of code; it is usually
295 much more desirable to just use Module::Install instead.
296
298 perlmodlib, ExtUtils::MakeMaker, Sort::Versions, CPAN, CPANPLUS, Mod‐
299 ule::Install
300
302 The test script included in the ExtUtils::AutoInstall distribution con‐
303 tains code adapted from Michael Schwern's Test::More under the Perl
304 License. Please consult to t/AutoInstall.t for details.
305 See the AUTHORS file in this module's source distribution for the list
307 of contributors.
308
310 Autrijus Tang <autrijus@autrijus.org>
311
313 Copyright 2001, 2002, 2003, 2004 by Autrijus Tang <autrijus@autri‐
314 jus.org>.
315 This program is free software; you can redistribute it and/or modify it
317 under the same terms as Perl itself.
318 See <http://www.perl.com/perl/misc/Artistic.html>
320perl v5.8.8 2005-09-12 ExtUtils::AutoInstall(3)