NAME

ExtUtils::AutoInstall - Automatic install of dependencies via CPAN

VERSION

This document describes version 0.32 of ExtUtils::AutoInstall, released May 20, 2002.

SYNOPSIS

In Makefile.PL:

    # ExtUtils::AutoInstall Bootstrap Code, version 4.
    BEGIN{my$p='ExtUtils::AutoInstall';my$v=.30;eval"use $p $v;1"or
    ($ENV{PERL_EXTUTILS_AUTOINSTALL}!~/--(?:default|skip|testonly)/
    and(-t STDIN)or eval"use ExtUtils::MakeMaker;WriteMakefile('PR'
    .'EREQ_PM'=>{'$p',$v});1"and exit)and print"==> $p $v needed. "
    ."Install it from CPAN? [Y/n] "and<STDIN>!~/^n/i and print"***"
    ." Fetching $p\n"and do{eval{require CPANPLUS;CPANPLUS::install
    $p};eval"use $p $v;1"or eval{require CPAN;CPAN::install$p};eval

    use ExtUtils::AutoInstall (
        -version        => '0.30',      # required AutoInstall version
        -config         => {
            make_args   => '--hello'    # option(s) for CPAN::Config 
            force       => 1,           # pseudo-option to force install
        },
        -core           => [            # core modules; may also be 'all'
            Package0    => '',          # any version would do
        ],
        'Feature1'      => [
            # do we want to install this feature by default?
            -default    => ( system('feature1 --version') == 0 ),
            Package1    => '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> ],
            Package2    => '0.02',
        ],
        'Feature3'      => {            # hash reference works, too
            # force installation even if tests fail
            Package3    => '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',
    );

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

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

Using make (or nmake):

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

DESCRIPTION

ExtUtils::AutoInstall lets module writers to specify a more sophisticated form of dependency information than the PREREQ_PM option offered by ExtUtils::MakeMaker.

Prerequisites are grouped into features, 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 Core Features marked by the name -core will double-check with the user, if the user chooses not to install the modules that belongs to it. This differs with the pre-0.26 'silent install' behaviour.

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

The dependencies are expressed as pairs of Module => version inside an a 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.

Once ExtUtils::AutoInstall has determined which module(s) are needed, it checks whether it's running under the CPAN shell and should therefore let CPAN 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; i.e. 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' to skip testing).

All modules scheduled to install 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.

CAVEATS

ExtUtils::AutoInstall will add UNINST=1 to your make install flags if your effective uid is 0 (root), unless you explicitly disable it by setting CPAN's make_install_arg configuration option (or the makeflags option of CPANPLUS) 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 Sort::Versions is available, it 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.

Inline::MakeMaker is not happy with this module, since it prohibits competing MY::postamble functions. Patches welcome.

NOTES

Since this module is needed before writing Makefile, 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 Makefile.PL to force user install it (cf. the Template Toolkit's dependency on AppConfig) is not very desirable either.

The current compromise is to add the bootstrap code listed in the "SYNOPSIS" before every script, but that ain't pretty, and won't work without internet connection.

Since we do not want all future options of ExtUtils::AutoInstall to be painfully detected manually like above, this module provides a bootstrapping mechanism via the -version flag. If a newer version is needed by the Makefile.PL, it will go ahead to fetch a new version, reload it into memory, and pass the arguments forward.

If you have any suggestions, please let me know. Thanks.

ENVIRONMENT

ExtUtils::AutoInstall uses a single environment variable, PERL_EXTUTILS_AUTOINSTALL. It's taken as the command line argument passed to Makefile.PL; you could set it to either --defaultdeps or --skipdeps to avoid interactive behaviour.

SEE ALSO

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

ACKNOWLEDGEMENTS

The test script included in the ExtUtils::AutoInstall distribution contains code adapted from Michael Schwern's Test::More under the Artistic License. Please refer to t/AutoInstall.t for details.

Thanks also to Jesse Vincent for suggesting the semantics of various make targets, and Jos IBoumans for introducing me to his CPANPLUS project.

Eric Andreychek contributed to the -force pseudo-option feature; Brian Ingerson suggested the non-intrusive handling of -core and bootstrap installations, and let the user have total control.

Rocco Caputo made me write compatibility code for cpansmoke and other non-tty STDIN type installations. Matt Cashner suggested the -skiptest semantic and caught a subtle bug involving require instead of use of AutoInstall. Chia-Liang Kao spotted the incompatibility between the use of $0 and CPANPLUS's eval() munging. Thanks!

AUTHORS

Autrijus Tang <autrijus@autrijus.org>

COPYRIGHT

Copyright 2001, 2002 by Autrijus Tang <autrijus@autrijus.org>.

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