local-lib5/man/man3/Module::AutoInstall.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Module::AutoInstall 3"
 132 .TH Module::AutoInstall 3 "2009-05-27" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Module::AutoInstall \- Automatic install of dependencies via CPAN
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 In \fIMakefile.PL\fR, with Module::Install available on the author's system:
 138 .PP
 139 .Vb 1
 140 \&    use inc::Module::Install;
 141 .Ve
 142 .PP
 143 .Vb 4
 144 \&    name        'Joe\-Hacker';
 145 \&    abstract    'Perl Interface to Joe Hacker';
 146 \&    author      'Joe Hacker <joe@hacker.org>';
 147 \&    include     'Module::AutoInstall';
 148 .Ve
 149 .PP
 150 .Vb 1
 151 \&    requires    'Module0';          # mandatory modules
 152 .Ve
 153 .PP
 154 .Vb 3
 155 \&    feature     'Feature1',
 156 \&        \-default    => 0,
 157 \&        'Module2'   => '0.1';
 158 .Ve
 159 .PP
 160 .Vb 3
 161 \&    feature     'Feature2',
 162 \&        \-default    => 0,
 163 \&        'Module3'   => '1.0';
 164 .Ve
 165 .PP
 166 .Vb 5
 167 \&    auto_install(
 168 \&        make_args   => '\-\-hello',   # option(s) for CPAN::Config
 169 \&        force       => 1,           # pseudo\-option to force install
 170 \&        do_once     => 1,           # skip previously failed modules
 171 \&    );
 172 .Ve
 173 .PP
 174 .Vb 1
 175 \&    WriteAll;
 176 .Ve
 177 .PP
 178 Invoking the resulting \fIMakefile.PL\fR:
 179 .PP
 180 .Vb 5
 181 \&    % perl Makefile.PL                  # interactive behaviour
 182 \&    % perl Makefile.PL \-\-defaultdeps    # accept default value on prompts
 183 \&    % perl Makefile.PL \-\-checkdeps      # check only, no Makefile produced
 184 \&    % perl Makefile.PL \-\-skipdeps       # ignores all dependencies
 185 \&    % perl Makefile.PL \-\-testonly       # don't write installation targets
 186 .Ve
 187 .PP
 188 Note that the trailing 'deps' of arguments may be omitted, too.
 189 .PP
 190 Using \f(CW\*(C`\-\-defaultdeps\*(C'\fR will make \fIMakefile.PL\fR behave similarly to a regular
 191 Makefile.PL file with \f(CW\*(C`PREREQ_PM\*(C'\fR dependencies.
 192 .PP
 193 One can use environment variables (see \*(L"\s-1ENVIRONMENT\s0\*(R") below to set a default
 194 behavior instead of specifying it in the command line for every invocation
 195 of \fIMakefile.PL\fR.
 196 .PP
 197 Using \fImake\fR (or \fInmake\fR):
 198 .PP
 199 .Vb 3
 200 \&    % make [all|test|install]           # install dependencies first
 201 \&    % make checkdeps                    # same as the \-\-checkdeps above
 202 \&    % make installdeps                  # install dependencies only
 203 .Ve
 204 .SH "DESCRIPTION"
 205 .IX Header "DESCRIPTION"
 206 \&\fBModule::AutoInstall\fR lets module writers to specify a more
 207 sophisticated form of dependency information than the \f(CW\*(C`PREREQ_PM\*(C'\fR
 208 option offered by \fBExtUtils::MakeMaker\fR.
 209 .PP
 210 This module works best with the \fBModule::Install\fR framework,
 211 a drop-in replacement for MakeMaker.  However, this module also
 212 supports \fIMakefile.PL\fR files based on MakeMaker; see \*(L"\s-1EXAMPLES\s0\*(R"
 213 for instructions.
 214 .Sh "Prerequisites and Features"
 215 .IX Subsection "Prerequisites and Features"
 216 Prerequisites are grouped into \fBfeatures\fR, and the user could choose
 217 yes/no on each one's dependencies; the module writer may also supply a
 218 boolean value via \f(CW\*(C`\-default\*(C'\fR to specify the default choice.
 219 .PP
 220 The \fBCore Features\fR marked by the name \f(CW\*(C`\-core\*(C'\fR will double-check with
 221 the user, if the user chooses not to install the mandatory modules.
 222 This differs from the pre\-0.26 'silent install' behaviour.
 223 .PP
 224 Starting from version 0.27, if \f(CW\*(C`\-core\*(C'\fR is set to the string \f(CW\*(C`all\*(C'\fR
 225 (case\-insensitive), every feature will be considered mandatory.
 226 .PP
 227 The dependencies are expressed as pairs of \f(CW\*(C`Module\*(C'\fR => \f(CW\*(C`version\*(C'\fR
 228 inside an array reference.  If the order does not matter, and there
 229 are no \f(CW\*(C`\-default\*(C'\fR, \f(CW\*(C`\-tests\*(C'\fR or \f(CW\*(C`\-skiptests\*(C'\fR directives for that
 230 feature, you may also use a hash reference.
 231 .Sh "The Installation Process"
 232 .IX Subsection "The Installation Process"
 233 Once \fBModule::AutoInstall\fR has determined which module(s) are needed,
 234 it checks whether it's running under the \fB\s-1CPAN\s0\fR shell and should
 235 therefore let \fB\s-1CPAN\s0\fR handle the dependency.
 236 .PP
 237 Finally, the \f(CW\*(C`WriteMakefile()\*(C'\fR is overridden to perform some additional
 238 checks, as well as skips tests associated with disabled features by the
 239 \&\f(CW\*(C`\-tests\*(C'\fR option.
 240 .PP
 241 The actual installation happens at the end of the \f(CW\*(C`make config\*(C'\fR target;
 242 both \f(CW\*(C`make test\*(C'\fR and \f(CW\*(C`make install\*(C'\fR will trigger the installation of
 243 required modules.
 244 .PP
 245 If it's not running under \fB\s-1CPAN\s0\fR, the installer will probe for an
 246 active connection by trying to resolve the domain \f(CW\*(C`cpan.org\*(C'\fR, and check
 247 for the user's permission to use \fB\s-1CPAN\s0\fR.  If all went well, a separate
 248     \fB\s-1CPAN\s0\fR instance is created to install the required modules.
 249 .PP
 250 If you have the \fB\s-1CPANPLUS\s0\fR package installed in your system, it is
 251 preferred by default over \fB\s-1CPAN\s0\fR; it also accepts some extra options
 252 (e.g. \f(CW\*(C`\-target => 'skiptest', \-skiptest => 1\*(C'\fR to skip testing).
 253 .PP
 254 All modules scheduled to be installed will be deleted from \f(CW%INC\fR
 255 first, so \fBExtUtils::MakeMaker\fR will check the newly installed modules.
 256 .PP
 257 Additionally, you could use the \f(CW\*(C`make installdeps\*(C'\fR target to install
 258 the modules, and the \f(CW\*(C`make checkdeps\*(C'\fR target to check dependencies
 259 without actually installing them; the \f(CW\*(C`perl Makefile.PL \-\-checkdeps\*(C'\fR
 260 command has an equivalent effect.
 261 .PP
 262 If the \fIMakefile.PL\fR itself needs to use an independent module (e.g.
 263 \&\fBAcme::KillarApp\fR, v1.21 or greater), then use something like below:
 264 .PP
 265 .Vb 6
 266 \&    BEGIN {
 267 \&        require Module::AutoInstall;
 268 \&        # the first argument is an arrayref of the \-config flags
 269 \&        Module::AutoInstall\->install([], 'Acme::KillerApp' => 1.21);
 270 \&    }
 271 \&    use Acme::KillerApp 1.21;
 272 .Ve
 273 .PP
 274 .Vb 3
 275 \&    Module::AutoInstall\->import(
 276 \&        # ... arguments as usual ...
 277 \&    );
 278 .Ve
 279 .PP
 280 Note the version test in the use clause; if you are so close to the
 281 cutting edge that \fBAcme::KillerApp\fR 1.20 is the latest version on \s-1CPAN\s0,
 282 this will prevent your module from going awry.
 283 .Sh "User-Defined Hooks"
 284 .IX Subsection "User-Defined Hooks"
 285 User-defined \fIpre-installation\fR and \fIpost-installation\fR hooks are
 286 available via \f(CW\*(C`MY::preinstall\*(C'\fR and \f(CW\*(C`MY::postinstall\*(C'\fR subroutines,
 287 as shown below:
 288 .PP
 289 .Vb 2
 290 \&    # pre\-install handler; takes $module_name and $version
 291 \&    sub MY::preinstall  { return 1; } # return false to skip install
 292 .Ve
 293 .PP
 294 .Vb 2
 295 \&    # post\-install handler; takes $module_name, $version, $success
 296 \&    sub MY::postinstall { return; }   # the return value doesn't matter
 297 .Ve
 298 .PP
 299 Note that since \fBModule::AutoInstall\fR performs installation at the
 300 time of \f(CW\*(C`use\*(C'\fR (i.e. before perl parses the remainder of
 301 \&\fIMakefile.PL\fR), you have to declare those two handlers \fIbefore\fR the
 302 \&\f(CW\*(C`use\*(C'\fR statement for them to take effect.
 303 .PP
 304 If the user did not choose to install a module or it already exists on
 305 the system, neither of the handlers is invoked.  Both handlers are invoked
 306 exactly once for each module when installation is attempted.
 307 .PP
 308 \&\f(CW\*(C`MY::preinstall\*(C'\fR takes two arguments, \f(CW$module_name\fR and \f(CW$version\fR;
 309 if it returns a false value, installation for that module will be
 310 skipped, and \f(CW\*(C`MY::postinstall\*(C'\fR won't be called at all.
 311 .PP
 312 \&\f(CW\*(C`MY::postinstall\*(C'\fR takes three arguments, \f(CW$module_name\fR, \f(CW$version\fR
 313 and \f(CW$success\fR.  The last one denotes whether the installation
 314 succeeded or not: \f(CW1\fR means installation completed successfully, \f(CW0\fR
 315 means failure during install, and \f(CW\*(C`undef\*(C'\fR means that the installation
 316 was not attempted at all, possibly due to connection problems, or that
 317 module does not exist on \s-1CPAN\s0 at all.
 318 .ie n .Sh "Customized ""MY::postamble"""
 319 .el .Sh "Customized \f(CWMY::postamble\fP"
 320 .IX Subsection "Customized MY::postamble"
 321 Starting from version 0.43, \fBModule::AutoInstall\fR supports modules
 322 that require a \f(CW\*(C`MY::postamble\*(C'\fR subroutine in their \fIMakefile.PL\fR.
 323 The user-defined \f(CW\*(C`MY::postamble\*(C'\fR, if present, is responsible for
 324 calling \f(CW\*(C`Module::AutoInstall::postamble\*(C'\fR and include the output in
 325 its return value.
 326 .PP
 327 For example, the \fBDBD::*\fR (database driver) modules for the Perl \s-1DBI\s0
 328 are required to include the postamble generated by the function
 329 \&\f(CW\*(C`dbd_postamble\*(C'\fR, so their \fIMakefile.PL\fR may contain lines like this:
 330 .PP
 331 .Vb 3
 332 \&    sub MY::postamble {
 333 \&        return &Module::AutoInstall::postamble . &dbd_postamble;
 334 \&    }
 335 .Ve
 336 .PP
 337 Note that the \fBModule::AutoInstall\fR module does not export the
 338 \&\f(CW\*(C`postamble\*(C'\fR function, so the name should always be fully qualified.
 339 .SH "CAVEATS"
 340 .IX Header "CAVEATS"
 341 \&\fBModule::AutoInstall\fR will add \f(CW\*(C`UNINST=1\*(C'\fR to your \fBmake install\fR
 342 flags if your effective uid is 0 (root), unless you explicitly disable
 343 it by setting \fB\s-1CPAN\s0\fR's \f(CW\*(C`make_install_arg\*(C'\fR configuration option (or the
 344 \&\f(CW\*(C`makeflags\*(C'\fR option of \fB\s-1CPANPLUS\s0\fR) to include \f(CW\*(C`UNINST=0\*(C'\fR.  This \fImay\fR
 345 cause dependency problems if you are using a fine-tuned directory
 346 structure for your site.  Please consult \*(L"\s-1FAQ\s0\*(R" in \s-1CPAN\s0 for an explanation
 347 in detail.
 348 .PP
 349 If either \fBversion\fR or \fBSort::Versions\fR is available, they will be
 350 used to compare the required version with the existing module's version
 351 and the \s-1CPAN\s0 module's.  Otherwise it silently falls back to use \fIcmp\fR.
 352 This may cause inconsistent behaviours in pathetic situations.
 353 .SH "ENVIRONMENT"
 354 .IX Header "ENVIRONMENT"
 355 \&\fBModule::AutoInstall\fR uses a single environment variable,
 356 \&\f(CW\*(C`PERL_AUTOINSTALL\*(C'\fR.  It is taken as the command line argument
 357 passed to \fIMakefile.PL\fR; you could set it to \f(CW\*(C`\-\-alldeps\*(C'\fR, \f(CW\*(C`\-\-defaultdeps\*(C'\fR
 358 or \f(CW\*(C`\-\-skipdeps\*(C'\fR to avoid all interactive behaviour.
 359 .PP
 360 \&\f(CW\*(C`\-\-alldeps\*(C'\fR will install all features, while
 361 \&\f(CW\*(C`\-\-defaultdeps\*(C'\fR will only install features for which the default answer is
 362 \&'y'.
 363 .PP
 364 \&\f(CW\*(C`\-\-skipdeps\*(C'\fR will refrain from loading \s-1CPAN\s0 and not install anything, unless
 365 you're running under \s-1CPAN\s0 or \s-1CPANPLUS\s0, in which case required dependencies
 366 will be installed.
 367 .PP
 368 It also read from the \f(CW\*(C`PERL_EXTUTILS_AUTOINSTALL\*(C'\fR environment variable if
 369 \&\f(CW\*(C`PERL_AUTOINSTALL\*(C'\fR is not defined.
 370 .SH "SEE ALSO"
 371 .IX Header "SEE ALSO"
 372 Module::Install
 373 .PP
 374 perlmodlib, ExtUtils::MakeMaker, Sort::Versions, \s-1CPAN\s0,
 375 \&\s-1CPANPLUS\s0
 376 .SH "AUTHORS"
 377 .IX Header "AUTHORS"
 378 Audrey Tang <autrijus@autrijus.org>
 379 .PP
 380 Adam Kennedy <adamk@cpan.org>
 381 .PP
 382 Matt S Trout <mst@shadowcat.co.u>
 383 .SH "IF THIS BREAKS"
 384 .IX Header "IF THIS BREAKS"
 385 Report a ticket to bugs-Module-Install <at> rt.cpan.org and cc Matt
 386 \&\- I appear to have volunteered as primary maintainer for this stuff so
 387 if you run into any problems please tell me
 388 .SH "COPYRIGHT"
 389 .IX Header "COPYRIGHT"
 390 Copyright 2001, 2002, 2003, 2004, 2005, 2006 by Audrey Tang
 391 .PP
 392 Some parts copyright 2006 Adam Kennedy
 393 .PP
 394 This program is free software; you can redistribute it and/or
 395 modify it under the same terms as Perl itself.
 396 .PP
 397 See <http://www.perl.com/perl/misc/Artistic.html>