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
47 regular 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 % 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
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 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 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 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 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 Starting from version 0.27, if "-core" is set to the string "all"
87 (case-insensitive), every feature will be considered mandatory.
88 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 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 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 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 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 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 All modules scheduled to be installed will be deleted from %INC first,
117 so ExtUtils::MakeMaker will check the newly installed modules.
118 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 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 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 Module::AutoInstall->import(
135 # ... arguments as usual ...
136 );
137 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 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 # pre-install handler; takes $module_name and $version
147 sub MY::preinstall { return 1; } # return false to skip install
148 # post-install handler; takes $module_name, $version, $success
150 sub MY::postinstall { return; } # the return value doesn't matter
151 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 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 "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 "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 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 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 sub MY::postamble {
184 return &Module::AutoInstall::postamble . &dbd_postamble;
185 }
186 Note that the Module::AutoInstall module does not export the
188 "postamble" function, so the name should always be fully qualified.
189
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 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
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 "--alldeps" will install all features, while "--defaultdeps" will only
211 install features for which the default answer is 'y'.
212 "--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 It is also read from the "PERL_EXTUTILS_AUTOINSTALL" environment
218 variable if "PERL_AUTOINSTALL" is not defined.
219 You can also set "PERL_AUTOINSTALL_PREFER_CPAN" to use CPAN to install
221 dependencies. By default CPANPLUS is used.
222
224 Module::Install
225 perlmodlib, ExtUtils::MakeMaker, Sort::Versions, CPAN, CPANPLUS
227
229 Audrey Tang <autrijus@autrijus.org>
230 Adam Kennedy <adamk@cpan.org>
232 Matt S Trout <mst@shadowcat.co.u>
234
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 Some parts copyright 2006 Adam Kennedy
244 This program is free software; you can redistribute it and/or modify it
246 under the same terms as Perl itself.
247 See <http://www.perl.com/perl/misc/Artistic.html>
249perl v5.28.0 2017-04-04 Module::AutoInstall(3)