GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  MODULE::AUTOINSTALL (3)

.ds Aq ’

NAME

Module::AutoInstall - Automatic install of dependencies via CPAN

CONTENTS

SYNOPSIS

In Makefile.PL, with Module::Install available on the author’s system:



    use inc::Module::Install;
   
    name        Joe-Hacker;
    abstract    Perl Interface to Joe Hacker;
    author      Joe Hacker <joe@hacker.org>;
    include     Module::AutoInstall;
   
    requires    Module0;          # mandatory modules
   
    feature     Feature1,
        -default    => 0,
        Module2   => 0.1;
   
    feature     Feature2,
        -default    => 0,
        Module3   => 1.0;
   
    auto_install(
        make_args   => --hello,   # option(s) for CPAN::Config
        force       => 1,           # pseudo-option to force install
        do_once     => 1,           # skip previously failed modules
    );
   
    WriteAll;



Invoking the resulting Makefile.PL:



    % 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       # dont write installation targets



Note that the trailing ’deps’ of arguments may be omitted, too.

Using --defaultdeps will make Makefile.PL behave similarly to a regular Makefile.PL file with PREREQ_PM dependencies.

One can use environment variables (see ENVIRONMENT) below to set a default behavior instead of specifying it in the command line for every invocation of Makefile.PL.

Using make (or nmake):



    % make [all|test|install]           # install dependencies first
    % make checkdeps                    # same as the --checkdeps above
    % make installdeps                  # install dependencies only
    % make installdeps_notest           # same without running tests
    % make upgradedeps                  # upgrade all deps, even if installed
    % make upgradedeps_notest           # same without running tests
    % make listdeps                     # print unsatisifed deps, one per line
    % make listalldeps                  # print all deps, one per line



DESCRIPTION

<B>Module::AutoInstallB> lets module writers to specify a more sophisticated form of dependency information than the PREREQ_PM option offered by <B>ExtUtils::MakeMakerB>.

This module works best with the <B>Module::InstallB> framework, a drop-in replacement for MakeMaker. However, this module also supports Makefile.PL files based on MakeMaker; see EXAMPLES for instructions.

Specifying installdeps_target; instead of auto_install; will not try to install dependencies when running make, but only when running make installdeps.

    Prerequisites and Features

Prerequisites are grouped into <B>featuresB>, and the user could choose yes/no on each one’s dependencies; the module writer may also supply a boolean value via -default to specify the default choice.

The <B>Core FeaturesB> marked by the name -core 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.

Starting from version 0.27, if -core is set to the string all (case-insensitive), every feature will be considered mandatory.

The dependencies are expressed as pairs of Module => version inside an array reference. If the order does not matter, and there are no -default, -tests or -skiptests directives for that feature, you may also use a hash reference.

    The Installation Process

Once <B>Module::AutoInstallB> has determined which module(s) are needed, it checks whether it’s running under the <B>CPANB> shell and should therefore let <B>CPANB> handle the dependency.

Finally, the WriteMakefile() is overridden to perform some additional checks, as well as skips tests associated with disabled features by the -tests option.

The actual installation happens at the end of the make config target; both make test and make install will trigger the installation of required modules.

If it’s not running under <B>CPANB>, the installer will probe for an active connection by trying to resolve the domain cpan.org, and check for the user’s permission to use <B>CPANB>. If all went well, a separate
<B>CPANB> instance is created to install the required modules.

If you have the <B>CPANPLUSB> package installed in your system, it is preferred by default over <B>CPANB>; it also accepts some extra options (e.g. -target => skiptest, -skiptest => 1 to skip testing).

All modules scheduled to be installed will be deleted from %INC first, so <B>ExtUtils::MakeMakerB> will check the newly installed modules.

Additionally, you could use the make installdeps target to install the modules, and the make checkdeps target to check dependencies without actually installing them; the perl Makefile.PL --checkdeps command has an equivalent effect.

If the Makefile.PL itself needs to use an independent module (e.g. <B>Acme::KillarAppB>, v1.21 or greater), then use something like below:



    BEGIN {
        require Module::AutoInstall;
        # the first argument is an arrayref of the -config flags
        Module::AutoInstall->install([], Acme::KillerApp => 1.21);
    }
    use Acme::KillerApp 1.21;

    Module::AutoInstall->import(
        # ... arguments as usual ...
    );



Note the version test in the use clause; if you are so close to the cutting edge that <B>Acme::KillerAppB> 1.20 is the latest version on CPAN, this will prevent your module from going awry.

    User-Defined Hooks

User-defined pre-installation and post-installation hooks are available via MY::preinstall and MY::postinstall subroutines, as shown below:



    # 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 doesnt matter



Note that since <B>Module::AutoInstallB> performs installation at the time of use (i.e. before perl parses the remainder of Makefile.PL), you have to declare those two handlers before the use statement for them to take effect.

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.

MY::preinstall takes two arguments, $module_name and $version; if it returns a false value, installation for that module will be skipped, and MY::postinstall won’t be called at all.

MY::postinstall takes three arguments, $module_name, $version and $success. The last one denotes whether the installation succeeded or not: 1 means installation completed successfully, 0 means failure during install, and undef means that the installation was not attempted at all, possibly due to connection problems, or that module does not exist on CPAN at all.

Customized CWMY::postamble

Starting from version 0.43, <B>Module::AutoInstallB> supports modules that require a MY::postamble subroutine in their Makefile.PL. The user-defined MY::postamble, if present, is responsible for calling Module::AutoInstall::postamble and include the output in its return value.

For example, the <B>DBD::*B> (database driver) modules for the Perl DBI are required to include the postamble generated by the function dbd_postamble, so their Makefile.PL may contain lines like this:



    sub MY::postamble {
        return &Module::AutoInstall::postamble . &dbd_postamble;
    }



Note that the <B>Module::AutoInstallB> module does not export the postamble function, so the name should always be fully qualified.

CAVEATS

<B>Module::AutoInstallB> will add UNINST=1 to your <B>make installB> flags if your effective uid is 0 (root), unless you explicitly disable it by setting <B>CPANB>’s make_install_arg configuration option (or the makeflags option of <B>CPANPLUSB>) to include UNINST=0. This may cause dependency problems if you are using a fine-tuned directory structure for your site. Please consult FAQ in CPAN for an explanation in detail.

If either <B>versionB> or <B>Sort::VersionsB> is available, they will be used to compare the required version with the existing module’s version and the CPAN module’s. Otherwise it silently falls back to use cmp. This may cause inconsistent behaviours in pathetic situations.

ENVIRONMENT

<B>Module::AutoInstallB> uses a single environment variable, PERL_AUTOINSTALL. It is taken as the command line argument passed to Makefile.PL; you could set it to --alldeps, --defaultdeps or --skipdeps to avoid all interactive behaviour.

--alldeps will install all features, while --defaultdeps will only install features for which the default answer is ’y’.

--skipdeps will refrain from loading CPAN and not install anything, unless you’re running under CPAN or CPANPLUS, in which case required dependencies will be installed.

It is also read from the PERL_EXTUTILS_AUTOINSTALL environment variable if PERL_AUTOINSTALL is not defined.

You can also set PERL_AUTOINSTALL_PREFER_CPAN to use CPAN to install dependencies. By default CPANPLUS is used.

SEE ALSO

Module::Install

perlmodlib, ExtUtils::MakeMaker, Sort::Versions, CPAN, CPANPLUS

AUTHORS

Audrey Tang <autrijus@autrijus.org>

Adam Kennedy <adamk@cpan.org>

Matt S Trout <mst@shadowcat.co.u>

IF THIS BREAKS

Report a ticket to bugs-Module-Install <at> rt.cpan.org and cc Matt - I appear to have volunteered as primary maintainer for this stuff so if you run into any problems please tell me

COPYRIGHT

Copyright 2001, 2002, 2003, 2004, 2005, 2006 by Audrey Tang

Some parts copyright 2006 Adam Kennedy

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See <http://www.perl.com/perl/misc/Artistic.html>

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 MODULE::AUTOINSTALL (3) 2015-05-02

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.