--- name: "Module::AutoInstall" section: "3pm" platform: "linux" package: "perl-module-install" version: "1.21-6" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/Module::AutoInstall" --- # Module::AutoInstall(3pm) Automatic install of dependencies via CPAN ## NAME Module::AutoInstall - Automatic install of dependencies via CPAN ## 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 '; 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 # don't 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 **Module::AutoInstall** lets module writers to specify a more sophisticated form of dependency information than the `"PREREQ_PM"` option offered by **ExtUtils::MakeMaker**. This module works best with the **Module::Install** 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 **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 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 **Module::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; 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 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 **Acme::KillerApp** 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 doesn't matter ``` Note that since **Module::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" Starting from version 0.43, **Module::AutoInstall** 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 **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 &Module::AutoInstall::postamble . &dbd_postamble; } ``` Note that the **Module::AutoInstall** module does not export the `"postamble"` function, so the name should always be fully qualified. ## CAVEATS **Module::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. ## ENVIRONMENT **Module::AutoInstall** 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 \ Adam Kennedy \ Matt S Trout \ ## IF THIS BREAKS Report a ticket to bugs-Module-Install \ 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 \