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
50 regular 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
64 sophisticated form of dependency information than the "PREREQ_PM"
65 option 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
69 Makefile.PL files based on MakeMaker; see "EXAMPLES" for instructions.
70 Prerequisites and Features
72 Prerequisites are grouped into features, and the user could choose
73 yes/no on each one's dependencies; the module writer may also supply a
74 boolean value via "-default" to specify the default choice.
75 The Core Features marked by the name "-core" will double-check with the
77 user, if the user chooses not to install the mandatory modules. This
78 differs from the pre-0.26 'silent install' behaviour.
79 Starting from version 0.27, if "-core" is set to the string "all"
81 (case-insensitive), every feature will be considered mandatory.
82 The dependencies are expressed as pairs of "Module" => "version" inside
84 an array reference. If the order does not matter, and there are no
85 "-default", "-tests" or "-skiptests" directives for that feature, you
86 may also use a hash reference.
87 The Installation Process
89 Once ExtUtils::AutoInstall has determined which module(s) are needed,
90 it checks whether it's running under the CPAN shell and should
91 therefore let CPAN handle the dependency.
92 Finally, the "WriteMakefile()" is overridden to perform some additional
94 checks, as well as skips tests associated with disabled features by the
95 "-tests" option.
96 The actual installation happens at the end of the "make config" target;
98 both "make test" and "make install" will trigger the installation of
99 required modules.
100 If it's not running under CPAN, the installer will probe for an active
102 connection by trying to resolve the domain "cpan.org", and check for
103 the user's permission to use CPAN. If all went well, a separate
104 CPAN instance is created to install the required modules.
105 If you have the CPANPLUS package installed in your system, it is
107 preferred by default over CPAN; it also accepts some extra options
108 (e.g. "-target => 'skiptest', -skiptest => 1" to skip testing).
109 All modules scheduled to be installed will be deleted from %INC first,
111 so ExtUtils::MakeMaker will check the newly installed modules.
112 Additionally, you could use the "make installdeps" target to install
114 the modules, and the "make checkdeps" target to check dependencies
115 without actually installing them; the "perl Makefile.PL --checkdeps"
116 command has an equivalent effect.
117 If the Makefile.PL itself needs to use an independent module (e.g.
119 Acme::KillarApp, v1.21 or greater), then use something like below:
120 BEGIN {
122 require ExtUtils::AutoInstall;
123 # the first argument is an arrayref of the -config flags
124 ExtUtils::AutoInstall->install([], 'Acme::KillerApp' => 1.21);
125 }
126 use Acme::KillerApp 1.21;
127 ExtUtils::AutoInstall->import(
129 # ... arguments as usual ...
130 );
131 Note the version test in the use clause; if you are so close to the
133 cutting edge that Acme::KillerApp 1.20 is the latest version on CPAN,
134 this will prevent your module from going awry.
135 User-Defined Hooks
137 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 ExtUtils::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
162 during install, and "undef" means that the installation was not
163 attempted at all, possibly due to connection problems, or that module
164 does not exist on CPAN at all.
165 Customized "MY::postamble"
167 Starting from version 0.43, ExtUtils::AutoInstall supports modules that
168 require a "MY::postamble" subroutine in their Makefile.PL. The user-
169 defined "MY::postamble", if present, is responsible for calling
170 "ExtUtils::AutoInstall::postamble" and include the output in its return
171 value.
172 For example, the DBD::* (database driver) modules for the Perl DBI are
174 required to include the postamble generated by the function
175 "dbd_postamble", so their Makefile.PL may contain lines like this:
176 sub MY::postamble {
178 return &ExtUtils::AutoInstall::postamble . &dbd_postamble;
179 }
180 Note that the ExtUtils::AutoInstall module does not export the
182 "postamble" function, so the name should always be fully qualified.
183
185 ExtUtils::AutoInstall will add "UNINST=1" to your make install flags if
186 your effective uid is 0 (root), unless you explicitly disable it by
187 setting CPAN's "make_install_arg" configuration option (or the
188 "makeflags" option of CPANPLUS) to include "UNINST=0". This may cause
189 dependency problems if you are using a fine-tuned directory structure
190 for your site. Please consult "FAQ" in CPAN for an explanation in
191 detail.
192 If either version or Sort::Versions is available, they will be used to
194 compare the required version with the existing module's version and the
195 CPAN module's. Otherwise it silently falls back to use cmp. This may
196 cause inconsistent behaviours in pathetic situations.
197
199 Since this module is needed before writing Makefile, it makes little
200 use as a CPAN module; hence each distribution must include it in full.
201 The only alternative I'm aware of, namely prompting in Makefile.PL to
202 force user install it (cf. the Template Toolkit's dependency on
203 AppConfig) is not very desirable either.
204 The current compromise is to add the bootstrap code listed in the
206 "SYNOPSIS" before every script, but that does not look pretty, and will
207 not work without an Internet connection.
208 Since we do not want all future options of ExtUtils::AutoInstall to be
210 painfully detected manually like above, this module provides a
211 bootstrapping mechanism via the "-version" flag. If a newer version is
212 needed by the Makefile.PL, it will go ahead to fetch a new version,
213 reload it into memory, and pass the arguments forward.
214 If you have any suggestions, please let me know. Thanks.
216
218 ExtUtils::AutoInstall uses a single environment variable,
219 "PERL_EXTUTILS_AUTOINSTALL". It is taken as the command line argument
220 passed to Makefile.PL; you could set it to either "--defaultdeps" or
221 "--skipdeps" to avoid interactive behaviour.
222
224 Using MakeMaker with AutoInstall
225 To use this module with ExtUtils::MakeMaker, first make a inc/ExtUtils/
226 subdirectory in the directory containing your Makefile.PL, and put a
227 copy this module under it as inc/ExtUtils/AutoInstall.pm. You can find
228 out where this module has been installed by typing "perldoc -l
229 ExtUtils::AutoInstall" in the command line.
230 Your Makefile.PL should look like this:
232 # pull in ExtUtils/AutoInstall.pm from 'inc'
234 use lib 'inc';
235 use ExtUtils::AutoInstall (
236 -core => [ # mandatory modules
237 'Module0' => '', # any version would suffice
238 ],
239 'Feature1' => [
240 # do we want to install this feature by default?
241 -default => ( system('feature1 --version') == 0 ),
242 Module1 => '0.01',
243 ],
244 'Feature2' => [
245 # associate tests to be disabled if this feature is missing
246 -tests => [ <t/feature2*.t> ],
247 # associate tests to be disabled if this feature is present
248 -skiptests => [ <t/nofeature2*.t> ],
249 Module2 => '0.02',
250 ],
251 'Feature3' => { # hash reference works, too
252 # force installation even if tests fail
253 Module2 => '0.03',
254 }
255 );
256 WriteMakefile(
258 AUTHOR => 'Joe Hacker <joe@hacker.org>',
259 ABSTRACT => 'Perl Interface to Joe Hacker',
260 NAME => 'Joe::Hacker',
261 VERSION_FROM => 'Hacker.pm',
262 DISTNAME => 'Joe-Hacker',
263 );
264 Self-Download Code
266 If you do not wish to put a copy of ExtUtils::AutoInstall under inc/,
267 and are confident that users will have internet access, you may replace
268 the "use lib 'inc';" line with this block of code:
269 # ExtUtils::AutoInstall Bootstrap Code, version 7.
271 BEGIN{my$p='ExtUtils::AutoInstall';my$v=0.45;$p->VERSION||0>=$v
272 or+eval"use $p $v;1"or+do{my$e=$ENV{PERL_EXTUTILS_AUTOINSTALL};
273 (!defined($e)||$e!~m/--(?:default|skip|testonly)/and-t STDIN or
274 eval"use ExtUtils::MakeMaker;WriteMakefile(PREREQ_PM=>{'$p',$v}
275 );1"and exit)and print"==> $p $v required. Install it from CP".
276 "AN? [Y/n] "and<STDIN>!~/^n/i and print"*** Installing $p\n"and
277 do{if (eval '$>' and lc(`sudo -V`) =~ /version/){system('sudo',
278 $^X,"-MCPANPLUS","-e","CPANPLUS::install $p");eval"use $p $v;1"
279 ||system('sudo', $^X, "-MCPAN", "-e", "CPAN::install $p")}eval{
280 require CPANPLUS;CPANPLUS::install$p};eval"use $p $v;1"or eval{
281 require CPAN;CPAN::install$p};eval"use $p $v;1"||die"*** Please
282 manually install $p $v from cpan.org first...\n"}}}
283 If the user did not have ExtUtils::AutoInstall installed, the block of
285 code above will automatically download and install it.
286 However, due to its space-compressed (and obfuscated) nature, you
288 should think twice before employing this block of code; it is usually
289 much more desirable to just use Module::Install instead.
290
292 perlmodlib, ExtUtils::MakeMaker, Sort::Versions, CPAN, CPANPLUS,
293 Module::Install
294
296 The test script included in the ExtUtils::AutoInstall distribution
297 contains code adapted from Michael Schwern's Test::More under the Perl
298 License. Please consult to t/AutoInstall.t for details.
299 See the AUTHORS file in this module's source distribution for the list
301 of contributors.
302
304 Autrijus Tang <autrijus@autrijus.org>
305
307 Copyright 2001, 2002, 2003, 2004 by Autrijus Tang
308 <autrijus@autrijus.org>.
309 This program is free software; you can redistribute it and/or modify it
311 under the same terms as Perl itself.
312 See <http://www.perl.com/perl/misc/Artistic.html>
314perl v5.12.0 2010-05-01 ExtUtils::AutoInstall(3)