ExtUti...Install(3pm)

💖 ExtUtils::AutoInstall 💖

omg okay so bestie, welcome to ExtUti...Install(3pm) — User Contributed Perl Documentation, the ✨iconic✨ page about ExtUtils::AutoInstall. It's giving "your dependencies install themselves so you don't have to cry about it." Let's go 🫶

---

✨ NAME ✨

ExtUtils::AutoInstall — Automatic install of dependencies via CPAN 🎀

---

🌸 VERSION 🌸

This document describes version 0.63 of ExtUtils::AutoInstall, released September 12, 2005. (yes bestie she's an elder icon, we respect her)

---

🦋 SYNOPSIS 🦋

So in your Makefile.PL, assuming Module::Install is 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     ('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;

Then, 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

little life hack: note that the trailing 'deps' of arguments may be omitted too. slay, less typing 💅

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

You can also use environment variables (peep "ENVIRONMENT" below) to set a default behavior instead of specifying it on the command line every single time you invoke Makefile.PL. no more typing the same flag 400 times bestie

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 specify a more sophisticated form of dependency information than the PREREQ_PM option offered by ExtUtils::MakeMaker. It's giving upgraded, honestly.

This module works best with the Module::Install framework, which is a drop-in replacement for MakeMaker. but wait, there's more — it also supports Makefile.PL files based on MakeMaker; see "EXAMPLES" for instructions.

🎀 Prerequisites and Features 🎀

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. you get to be the main character and pick 👑

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. she will ask again, do not test her 💀

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. flexible queen 🦋

💅 The Installation Process 💅

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. let the professionals cook

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. vibe check passed, proceeding 🔥

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. out with the old, in with the new ✨

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. protect yourself bestie 🫶

🧚 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 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. order matters, do not skip this, fr fr

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. one and done, no spam

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. ghosted 🙈

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. three states of being, iconic ✨

🌸 Customized MY::postamble 🌸

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

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. full name or nothing, periodt 💅

---

💀 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 either version or Sort::Versions 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. 😭

---

⭐ 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. ngl, it's a whole situation

The current compromise is to add the bootstrap code listed in the "SYNOPSIS" before every script, but that does not look pretty, and will not work without an Internet connection. no wifi, no vibe 💀

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. self-updating queen behavior 👑

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

---

🌈 ENVIRONMENT 🌈

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

---

okay that's part 1, don't go anywhere — more is coming 💖

🌸 EXAMPLES 🌸

---

✨ Using MakeMaker with AutoInstall ✨

okay so bestie, if you wanna use this module with ExtUtils::MakeMaker, here's the whole ritual 🫶

First: make a inc/ExtUtils/ subdirectory inside the directory that holds your Makefile.PL, and drop a copy of this module under it as inc/ExtUtils/AutoInstall.pm. Easy. And if you're sitting there like "wait where even is this module on my system", just type this and the machine will tell you:

perldoc -l ExtUtils::AutoInstall

And then 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',
);

look at that. it's giving organized. it's giving "my Makefile.PL has a skincare routine". 💅

---

🦋 Self-Download Code 🦋

okay so this next bit is the spicy option. if you do NOT want to put a copy of ExtUtils::AutoInstall under inc/, and you're confident that your users have internet access, you can swap out that use lib 'inc'; line for this block of code instead:

# 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"}}}

so what does this little gremlin do? if the user didn't already have ExtUtils::AutoInstall installed, this block will automatically download and install it for them. slay, honestly. ✨

⚠️ but bestie listen. because of its space-compressed (and, let's be real, fully obfuscated) nature, you should think twice before you employ this block of code. it is usually much more desirable to just use Module::Install instead. i said what i said. 🙈

---

👑 SEE ALSO 👑

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

the whole friend group. go say hi. 💜

---

🎀 ACKNOWLEDGEMENTS 🎀

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

See the AUTHORS file in this module's source distribution for the list of contributors. 🫶

---

🌈 AUTHORS 🌈

Autrijus Tang <autrijus@autrijus.org>

---

💖 COPYRIGHT 💖

Copyright 2001, 2002, 2003, 2004, 2005, 2016 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>

---

and that's the whole page, bestie, we made it to the end together 🥹 this was documented by the Perl maintainers, perl v5.32.0, dated 2021-01-20 — and it's ExtUti...Install(3pm), the one and only. now go install something. no cap. 💅✨🌸