Prerequisites and Features

The Core Features 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

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 CPAN, 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 CPAN. If all went well, a separate CPAN instance is created to install the required modules.

If you have the CPANPLUS package installed in your system, it is preferred by default over CPAN; 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 ExtUtils::MakeMaker 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. Acme::KillarApp, v1.21 or greater), then use something like below:

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

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

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

User-Defined Hooks

    # 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't matter

Note that since ExtUtils::AutoInstall 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 "MY::postamble"

For example, the DBD::* (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 &ExtUtils::AutoInstall::postamble . &dbd_postamble;
    }

Note that the ExtUtils::AutoInstall module does not export the "postamble" function, so the name should always be fully qualified.

Using MakeMaker with AutoInstall

Your Makefile.PL should look like this:

    # pull in ExtUtils/AutoInstall.pm from 'inc'
    use lib 'inc';
    use ExtUtils::AutoInstall (
        -core           => [            # mandatory modules
            'Module0'   => '',          # any version would suffice
        ],
        'Feature1'      => [
            # do we want to install this feature by default?
            -default    => ( system('feature1 --version') == 0 ),
            Module1     => '0.01',
        ],
        'Feature2'      => [
            # associate tests to be disabled if this feature is missing
            -tests      => [ <t/feature2*.t> ],
            # associate tests to be disabled if this feature is present
            -skiptests  => [ <t/nofeature2*.t> ],
            Module2     => '0.02',
        ],
        'Feature3'      => {            # hash reference works, too
            # force installation even if tests fail
            Module2     => '0.03',
        }
    );

    WriteMakefile(
        AUTHOR          => 'Joe Hacker <joe@hacker.org>',
        ABSTRACT        => 'Perl Interface to Joe Hacker',
        NAME            => 'Joe::Hacker',
        VERSION_FROM    => 'Hacker.pm',
        DISTNAME        => 'Joe-Hacker',
    );

Self-Download Code

    # ExtUtils::AutoInstall Bootstrap Code, version 7.
    BEGIN{my$p='ExtUtils::AutoInstall';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=>{'$p',$v}
    );1"and exit)and print"==> $p $v required. Install it from CP".
    "AN? [Y/n] "and<STDIN>!~/^n/i and print"*** Installing $p\n"and
    do{if (eval '$>' and lc(`sudo -V`) =~ /version/){system('sudo',
    $^X,"-MCPANPLUS","-e","CPANPLUS::install $p");eval"use $p $v;1"
    ||system('sudo', $^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...\n"}}}

If the user did not have ExtUtils::AutoInstall installed, the block of code above will automatically download and install it.

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.