.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "ExtUtils::AutoInstall 3pm" .TH ExtUtils::AutoInstall 3pm "2021-01-20" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" ExtUtils::AutoInstall \- Automatic install of dependencies via CPAN .SH "VERSION" .IX Header "VERSION" This document describes version 0.63 of \fBExtUtils::AutoInstall\fR, released September 12, 2005. .SH "SYNOPSIS" .IX Header "SYNOPSIS" In \fIMakefile.PL\fR, with Module::Install available on the author's system: .PP .Vb 1 \& use inc::Module::Install; \& \& name (\*(AqJoe\-Hacker\*(Aq); \& abstract (\*(AqPerl Interface to Joe Hacker\*(Aq); \& author (\*(AqJoe Hacker \*(Aq); \& include (\*(AqExtUtils::AutoInstall\*(Aq); \& \& requires (\*(AqModule0\*(Aq); # mandatory modules \& features ( \& \-config => { \& make_args => \*(Aq\-\-hello\*(Aq, # option(s) for CPAN::Config \& force => 1, # pseudo\-option to force install \& do_once => 1, # skip previously failed modules \& }, \& \*(AqFeature1\*(Aq => [ \& \*(AqModule2\*(Aq => \*(Aq0.1\*(Aq, \& ], \& \*(AqFeature2\*(Aq => [ \& \*(AqModule3\*(Aq => \*(Aq1.0\*(Aq, \& ], \& ); \& auto_install(); \& &WriteAll; .Ve .PP Invoking the resulting \fIMakefile.PL\fR: .PP .Vb 5 \& % perl Makefile.PL # interactive behaviour \& % perl Makefile.PL \-\-defaultdeps # accept default value on prompts \& % perl Makefile.PL \-\-checkdeps # check only, no Makefile produced \& % perl Makefile.PL \-\-skipdeps # ignores all dependencies \& % perl Makefile.PL \-\-testonly # don\*(Aqt write installation targets .Ve .PP Note that the trailing 'deps' of arguments may be omitted, too. .PP Using \f(CW\*(C`\-\-defaultdeps\*(C'\fR will make \fIMakefile.PL\fR behave similarly to a regular Makefile.PL file with \f(CW\*(C`PREREQ_PM\*(C'\fR dependencies. .PP One can use environment variables (see \*(L"\s-1ENVIRONMENT\*(R"\s0) below to set a default behavior instead of specifying it in the command line for every invocation of \fIMakefile.PL\fR. .PP Using \fImake\fR (or \fInmake\fR): .PP .Vb 3 \& % make [all|test|install] # install dependencies first \& % make checkdeps # same as the \-\-checkdeps above \& % make installdeps # install dependencies only .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBExtUtils::AutoInstall\fR lets module writers to specify a more sophisticated form of dependency information than the \f(CW\*(C`PREREQ_PM\*(C'\fR option offered by \fBExtUtils::MakeMaker\fR. .PP This module works best with the \fBModule::Install\fR framework, a drop-in replacement for MakeMaker. However, this module also supports \fIMakefile.PL\fR files based on MakeMaker; see \*(L"\s-1EXAMPLES\*(R"\s0 for instructions. .SS "Prerequisites and Features" .IX Subsection "Prerequisites and Features" Prerequisites are grouped into \fBfeatures\fR, and the user could choose yes/no on each one's dependencies; the module writer may also supply a boolean value via \f(CW\*(C`\-default\*(C'\fR to specify the default choice. .PP The \fBCore Features\fR marked by the name \f(CW\*(C`\-core\*(C'\fR will double-check with the user, if the user chooses not to install the mandatory modules. This differs from the pre\-0.26 'silent install' behaviour. .PP Starting from version 0.27, if \f(CW\*(C`\-core\*(C'\fR is set to the string \f(CW\*(C`all\*(C'\fR (case-insensitive), every feature will be considered mandatory. .PP The dependencies are expressed as pairs of \f(CW\*(C`Module\*(C'\fR => \f(CW\*(C`version\*(C'\fR inside an array reference. If the order does not matter, and there are no \f(CW\*(C`\-default\*(C'\fR, \f(CW\*(C`\-tests\*(C'\fR or \f(CW\*(C`\-skiptests\*(C'\fR directives for that feature, you may also use a hash reference. .SS "The Installation Process" .IX Subsection "The Installation Process" Once \fBExtUtils::AutoInstall\fR has determined which module(s) are needed, it checks whether it's running under the \fB\s-1CPAN\s0\fR shell and should therefore let \fB\s-1CPAN\s0\fR handle the dependency. .PP Finally, the \f(CW\*(C`WriteMakefile()\*(C'\fR is overridden to perform some additional checks, as well as skips tests associated with disabled features by the \&\f(CW\*(C`\-tests\*(C'\fR option. .PP The actual installation happens at the end of the \f(CW\*(C`make config\*(C'\fR target; both \f(CW\*(C`make test\*(C'\fR and \f(CW\*(C`make install\*(C'\fR will trigger the installation of required modules. .PP If it's not running under \fB\s-1CPAN\s0\fR, the installer will probe for an active connection by trying to resolve the domain \f(CW\*(C`cpan.org\*(C'\fR, and check for the user's permission to use \fB\s-1CPAN\s0\fR. If all went well, a separate \fB\s-1CPAN\s0\fR instance is created to install the required modules. .PP If you have the \fB\s-1CPANPLUS\s0\fR package installed in your system, it is preferred by default over \fB\s-1CPAN\s0\fR; it also accepts some extra options (e.g. \f(CW\*(C`\-target => \*(Aqskiptest\*(Aq, \-skiptest => 1\*(C'\fR to skip testing). .PP All modules scheduled to be installed will be deleted from \f(CW%INC\fR first, so \fBExtUtils::MakeMaker\fR will check the newly installed modules. .PP Additionally, you could use the \f(CW\*(C`make installdeps\*(C'\fR target to install the modules, and the \f(CW\*(C`make checkdeps\*(C'\fR target to check dependencies without actually installing them; the \f(CW\*(C`perl Makefile.PL \-\-checkdeps\*(C'\fR command has an equivalent effect. .PP If the \fIMakefile.PL\fR itself needs to use an independent module (e.g. \&\fBAcme::KillarApp\fR, v1.21 or greater), then use something like below: .PP .Vb 6 \& BEGIN { \& require ExtUtils::AutoInstall; \& # the first argument is an arrayref of the \-config flags \& ExtUtils::AutoInstall\->install([], \*(AqAcme::KillerApp\*(Aq => 1.21); \& } \& use Acme::KillerApp 1.21; \& \& ExtUtils::AutoInstall\->import( \& # ... arguments as usual ... \& ); .Ve .PP Note the version test in the use clause; if you are so close to the cutting edge that \fBAcme::KillerApp\fR 1.20 is the latest version on \s-1CPAN,\s0 this will prevent your module from going awry. .SS "User-Defined Hooks" .IX Subsection "User-Defined Hooks" User-defined \fIpre-installation\fR and \fIpost-installation\fR hooks are available via \f(CW\*(C`MY::preinstall\*(C'\fR and \f(CW\*(C`MY::postinstall\*(C'\fR subroutines, as shown below: .PP .Vb 2 \& # pre\-install handler; takes $module_name and $version \& sub MY::preinstall { return 1; } # return false to skip install \& \& # post\-install handler; takes $module_name, $version, $success \& sub MY::postinstall { return; } # the return value doesn\*(Aqt matter .Ve .PP Note that since \fBExtUtils::AutoInstall\fR performs installation at the time of \f(CW\*(C`use\*(C'\fR (i.e. before perl parses the remainder of \&\fIMakefile.PL\fR), you have to declare those two handlers \fIbefore\fR the \&\f(CW\*(C`use\*(C'\fR statement for them to take effect. .PP If the user did not choose to install a module or it already exists on the system, neither of the handlers is invoked. Both handlers are invoked exactly once for each module when installation is attempted. .PP \&\f(CW\*(C`MY::preinstall\*(C'\fR takes two arguments, \f(CW$module_name\fR and \f(CW$version\fR; if it returns a false value, installation for that module will be skipped, and \f(CW\*(C`MY::postinstall\*(C'\fR won't be called at all. .PP \&\f(CW\*(C`MY::postinstall\*(C'\fR takes three arguments, \f(CW$module_name\fR, \f(CW$version\fR and \f(CW$success\fR. The last one denotes whether the installation succeeded or not: \f(CW1\fR means installation completed successfully, \f(CW0\fR means failure during install, and \f(CW\*(C`undef\*(C'\fR means that the installation was not attempted at all, possibly due to connection problems, or that module does not exist on \s-1CPAN\s0 at all. .ie n .SS "Customized ""MY::postamble""" .el .SS "Customized \f(CWMY::postamble\fP" .IX Subsection "Customized MY::postamble" Starting from version 0.43, \fBExtUtils::AutoInstall\fR supports modules that require a \f(CW\*(C`MY::postamble\*(C'\fR subroutine in their \fIMakefile.PL\fR. The user-defined \f(CW\*(C`MY::postamble\*(C'\fR, if present, is responsible for calling \f(CW\*(C`ExtUtils::AutoInstall::postamble\*(C'\fR and include the output in its return value. .PP For example, the \fBDBD::*\fR (database driver) modules for the Perl \s-1DBI\s0 are required to include the postamble generated by the function \&\f(CW\*(C`dbd_postamble\*(C'\fR, so their \fIMakefile.PL\fR may contain lines like this: .PP .Vb 3 \& sub MY::postamble { \& return &ExtUtils::AutoInstall::postamble . &dbd_postamble; \& } .Ve .PP Note that the \fBExtUtils::AutoInstall\fR module does not export the \&\f(CW\*(C`postamble\*(C'\fR function, so the name should always be fully qualified. .SH "CAVEATS" .IX Header "CAVEATS" \&\fBExtUtils::AutoInstall\fR will add \f(CW\*(C`UNINST=1\*(C'\fR to your \fBmake install\fR flags if your effective uid is 0 (root), unless you explicitly disable it by setting \fB\s-1CPAN\s0\fR's \f(CW\*(C`make_install_arg\*(C'\fR configuration option (or the \&\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 cause dependency problems if you are using a fine-tuned directory structure for your site. Please consult \*(L"\s-1FAQ\*(R"\s0 in \s-1CPAN\s0 for an explanation in detail. .PP If either \fBversion\fR or \fBSort::Versions\fR is available, they will be used to compare the required version with the existing module's version and the \s-1CPAN\s0 module's. Otherwise it silently falls back to use \fIcmp\fR. This may cause inconsistent behaviours in pathetic situations. .SH "NOTES" .IX Header "NOTES" Since this module is needed before writing \fIMakefile\fR, it makes little use as a \s-1CPAN\s0 module; hence each distribution must include it in full. The only alternative I'm aware of, namely prompting in \fIMakefile.PL\fR to force user install it (cf. the \fBTemplate Toolkit\fR's dependency on \&\fBAppConfig\fR) is not very desirable either. .PP The current compromise is to add the bootstrap code listed in the \&\*(L"\s-1SYNOPSIS\*(R"\s0 before every script, but that does not look pretty, and will not work without an Internet connection. .PP Since we do not want all future options of \fBExtUtils::AutoInstall\fR to be painfully detected manually like above, this module provides a \&\fIbootstrapping\fR mechanism via the \f(CW\*(C`\-version\*(C'\fR flag. If a newer version is needed by the \fIMakefile.PL\fR, it will go ahead to fetch a new version, reload it into memory, and pass the arguments forward. .PP If you have any suggestions, please let me know. Thanks. .SH "ENVIRONMENT" .IX Header "ENVIRONMENT" \&\fBExtUtils::AutoInstall\fR uses a single environment variable, \&\f(CW\*(C`PERL_EXTUTILS_AUTOINSTALL\*(C'\fR. It is taken as the command line argument passed to \fIMakefile.PL\fR; you could set it to either \f(CW\*(C`\-\-defaultdeps\*(C'\fR or \&\f(CW\*(C`\-\-skipdeps\*(C'\fR to avoid interactive behaviour. .SH "EXAMPLES" .IX Header "EXAMPLES" .SS "Using MakeMaker with AutoInstall" .IX Subsection "Using MakeMaker with AutoInstall" To use this module with ExtUtils::MakeMaker, first make a \&\fIinc/ExtUtils/\fR subdirectory in the directory containing your Makefile.PL, and put a copy this module under it as \&\fIinc/ExtUtils/AutoInstall.pm\fR. You can find out where this module has been installed by typing \f(CW\*(C`perldoc \-l ExtUtils::AutoInstall\*(C'\fR in the command line. .PP Your \fIMakefile.PL\fR should look like this: .PP .Vb 10 \& # pull in ExtUtils/AutoInstall.pm from \*(Aqinc\*(Aq \& use lib \*(Aqinc\*(Aq; \& use ExtUtils::AutoInstall ( \& \-core => [ # mandatory modules \& \*(AqModule0\*(Aq => \*(Aq\*(Aq, # any version would suffice \& ], \& \*(AqFeature1\*(Aq => [ \& # do we want to install this feature by default? \& \-default => ( system(\*(Aqfeature1 \-\-version\*(Aq) == 0 ), \& Module1 => \*(Aq0.01\*(Aq, \& ], \& \*(AqFeature2\*(Aq => [ \& # associate tests to be disabled if this feature is missing \& \-tests => [ ], \& # associate tests to be disabled if this feature is present \& \-skiptests => [ ], \& Module2 => \*(Aq0.02\*(Aq, \& ], \& \*(AqFeature3\*(Aq => { # hash reference works, too \& # force installation even if tests fail \& Module2 => \*(Aq0.03\*(Aq, \& } \& ); \& \& WriteMakefile( \& AUTHOR => \*(AqJoe Hacker \*(Aq, \& ABSTRACT => \*(AqPerl Interface to Joe Hacker\*(Aq, \& NAME => \*(AqJoe::Hacker\*(Aq, \& VERSION_FROM => \*(AqHacker.pm\*(Aq, \& DISTNAME => \*(AqJoe\-Hacker\*(Aq, \& ); .Ve .SS "Self-Download Code" .IX Subsection "Self-Download Code" If you do not wish to put a copy of ExtUtils::AutoInstall under \&\fIinc/\fR, and are confident that users will have internet access, you may replace the \f(CW\*(C`use lib \*(Aqinc\*(Aq;\*(C'\fR line with this block of code: .PP .Vb 10 \& # ExtUtils::AutoInstall Bootstrap Code, version 7. \& BEGIN{my$p=\*(AqExtUtils::AutoInstall\*(Aq;my$v=0.45;$p\->VERSION||0>=$v \& or+eval"use $p $v;1"or+do{my$e=$ENV{PERL_EXTUTILS_AUTOINSTALL}; \& (!defined($e)||$e!~m/\-\-(?:default|skip|testonly)/and\-t STDIN or \& eval"use ExtUtils::MakeMaker;WriteMakefile(PREREQ_PM=>{\*(Aq$p\*(Aq,$v} \& );1"and exit)and print"==> $p $v required. Install it from CP". \& "AN? [Y/n] "and!~/^n/i and print"*** Installing $p\en"and \& do{if (eval \*(Aq$>\*(Aq and lc(\`sudo \-V\`) =~ /version/){system(\*(Aqsudo\*(Aq, \& $^X,"\-MCPANPLUS","\-e","CPANPLUS::install $p");eval"use $p $v;1" \& ||system(\*(Aqsudo\*(Aq, $^X, "\-MCPAN", "\-e", "CPAN::install $p")}eval{ \& require CPANPLUS;CPANPLUS::install$p};eval"use $p $v;1"or eval{ \& require CPAN;CPAN::install$p};eval"use $p $v;1"||die"*** Please \& manually install $p $v from cpan.org first...\en"}}} .Ve .PP If the user did not have ExtUtils::AutoInstall installed, the block of code above will automatically download and install it. .PP However, due to its space-compressed (and obfuscated) nature, you should think twice before employing this block of code; it is usually much more desirable to just use Module::Install instead. .SH "SEE ALSO" .IX Header "SEE ALSO" perlmodlib, ExtUtils::MakeMaker, Sort::Versions, \s-1CPAN\s0, \&\s-1CPANPLUS\s0, Module::Install .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" The test script included in the \fBExtUtils::AutoInstall\fR distribution contains code adapted from Michael Schwern's \fBTest::More\fR under the \&\fIPerl License\fR. Please consult to \fIt/AutoInstall.t\fR for details. .PP See the \fI\s-1AUTHORS\s0\fR file in this module's source distribution for the list of contributors. .SH "AUTHORS" .IX Header "AUTHORS" Autrijus Tang .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2001, 2002, 2003, 2004, 2005, 2016 by Autrijus Tang . .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP See