1ExtUtils::AutoInstall(3U)ser Contributed Perl DocumentatiEoxntUtils::AutoInstall(3)
2
3
4

NAME

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

VERSION

9       This document describes version 0.63 of ExtUtils::AutoInstall, released
10       September 12, 2005.
11

SYNOPSIS

13       In Makefile.PL, with Module::Install available on the author's system:
14
15           use inc::Module::Install;
16
17           name        ('Joe-Hacker');
18           abstract    ('Perl Interface to Joe Hacker');
19           author      ('Joe Hacker <joe@hacker.org>');
20           include     ('ExtUtils::AutoInstall');
21
22           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
39       Invoking the resulting Makefile.PL:
40
41           % 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
47       Note that the trailing 'deps' of arguments may be omitted, too.
48
49       Using "--defaultdeps" will make Makefile.PL behave similarly to a
50       regular Makefile.PL file with "PREREQ_PM" dependencies.
51
52       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
56       Using make (or nmake):
57
58           % make [all|test|install]           # install dependencies first
59           % make checkdeps                    # same as the --checkdeps above
60           % make installdeps                  # install dependencies only
61

DESCRIPTION

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
67       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
71   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
76       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
80       Starting from version 0.27, if "-core" is set to the string "all"
81       (case-insensitive), every feature will be considered mandatory.
82
83       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
88   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
93       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
97       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
101       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
106       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
110       All modules scheduled to be installed will be deleted from %INC first,
111       so ExtUtils::MakeMaker will check the newly installed modules.
112
113       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
118       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
121           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
128           ExtUtils::AutoInstall->import(
129               # ... arguments as usual ...
130           );
131
132       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
136   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
140           # pre-install handler; takes $module_name and $version
141           sub MY::preinstall  { return 1; } # return false to skip install
142
143           # post-install handler; takes $module_name, $version, $success
144           sub MY::postinstall { return; }   # the return value doesn't matter
145
146       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
151       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
155       "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
159       "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
166   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
173       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
177           sub MY::postamble {
178               return &ExtUtils::AutoInstall::postamble . &dbd_postamble;
179           }
180
181       Note that the ExtUtils::AutoInstall module does not export the
182       "postamble" function, so the name should always be fully qualified.
183

CAVEATS

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
193       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

NOTES

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
205       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
209       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
215       If you have any suggestions, please let me know.  Thanks.
216

ENVIRONMENT

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

EXAMPLES

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
231       Your Makefile.PL should look like this:
232
233           # 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
257           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
265   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
270           # 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
284       If the user did not have ExtUtils::AutoInstall installed, the block of
285       code above will automatically download and install it.
286
287       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

SEE ALSO

292       perlmodlib, ExtUtils::MakeMaker, Sort::Versions, CPAN, CPANPLUS,
293       Module::Install
294

ACKNOWLEDGEMENTS

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
300       See the AUTHORS file in this module's source distribution for the list
301       of contributors.
302

AUTHORS

304       Autrijus Tang <autrijus@autrijus.org>
305
307       Copyright 2001, 2002, 2003, 2004, 2005, 2016 by Autrijus Tang
308       <autrijus@autrijus.org>.
309
310       This program is free software; you can redistribute it and/or modify it
311       under the same terms as Perl itself.
312
313       See <http://www.perl.com/perl/misc/Artistic.html>
314
315
316
317perl v5.36.0                      2022-07-22          ExtUtils::AutoInstall(3)
Impressum