File Coverage

blib/lib/ExtUtils/AutoInstall.pm

Criterion	Covered	Total	%
statement	125	301	41.5
branch	53	178	29.7
condition	30	121	24.7
subroutine	15	25	60.0
pod	1	5	20.0
total	224	630	35.5

package ExtUtils::AutoInstall;
$ExtUtils::AutoInstall::VERSION = '0.63';

use strict;
use Cwd ();
use ExtUtils::MakeMaker ();

=head1 NAME

ExtUtils::AutoInstall - Automatic install of dependencies via CPAN

=head1 VERSION

This document describes version 0.63 of B,
released September 12, 2005.

=head1 SYNOPSIS

In F, with L available on the author's system:

    use inc::Module::Install;

    name        ('Joe-Hacker');
    abstract    ('Perl Interface to Joe Hacker');
    author      ('Joe Hacker ');
    include     ('ExtUtils::AutoInstall');

    requires    ('Module0');            # mandatory modules
    features    (
        -config         => {
            make_args   => '--hello',   # option(s) for CPAN::Config
            force       => 1,           # pseudo-option to force install
            do_once     => 1,           # skip previously failed modules
        },
        'Feature1' => [
            'Module2'   => '0.1',
        ],
        'Feature2' => [
            'Module3'   => '1.0',
        ],
    );
    auto_install();
    &WriteAll;

Invoking the resulting F:

    % 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't write installation targets

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

Using C<--defaultdeps> will make F behave similarly to a regular
Makefile.PL file with C 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 F.

Using F (or F):

    % make [all|test|install]           # install dependencies first
    % make checkdeps                    # same as the --checkdeps above
    % make installdeps                  # install dependencies only

=head1 DESCRIPTION

B lets module writers to specify a more
sophisticated form of dependency information than the C
option offered by B.

This module works best with the B framework,
a drop-in replacement for MakeMaker.  However, this module also
supports F files based on MakeMaker; see L
for instructions.

=head2 Prerequisites and Features

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

The B marked by the name C<-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 C<-core> is set to the string C
(case-insensitive), every feature will be considered mandatory.

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

=head2 The Installation Process

Once B has determined which module(s) are needed,
it checks whether it's running under the B shell and should
therefore let B handle the dependency.

Finally, the C is overridden to perform some additional
checks, as well as skips tests associated with disabled features by the
C<-tests> option.

The actual installation happens at the end of the C target;
both C and C will trigger the installation of
required modules.

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

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

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

Additionally, you could use the C target to install
the modules, and the C target to check dependencies
without actually installing them; the C
command has an equivalent effect.

If the F itself needs to use an independent module (e.g.
B, 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 B 1.20 is the latest version on CPAN,
this will prevent your module from going awry.

=head2 User-Defined Hooks

User-defined I and I hooks are
available via C and C 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 doesn't matter

Note that since B performs installation at the
time of C (i.e. before perl parses the remainder of
F), you have to declare those two handlers I the
C 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.

C takes two arguments, C<$module_name> and C<$version>;
if it returns a false value, installation for that module will be
skipped, and C won't be called at all.

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

=head2 Customized C

Starting from version 0.43, B supports modules
that require a C subroutine in their F.
The user-defined C, if present, is responsible for
calling C and include the output in
its return value.

For example, the B (database driver) modules for the Perl DBI
are required to include the postamble generated by the function
C, so their F may contain lines like this:

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

Note that the B module does not export the
C function, so the name should always be fully qualified.

=head1 CAVEATS

B will add C to your B
flags if your effective uid is 0 (root), unless you explicitly disable
it by setting B's C configuration option (or the
C option of B) to include C.  This I
cause dependency problems if you are using a fine-tuned directory
structure for your site.  Please consult L for an explanation
in detail.

If either B or B 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 I.
This may cause inconsistent behaviours in pathetic situations.

=head1 NOTES

Since this module is needed before writing F, it makes little
use as a CPAN module; hence each distribution must include it in full.
The only alternative I'm aware of, namely prompting in F to
force user install it (cf. the B