Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Module::AutoInstall(3)User Contributed Perl DocumentatioModule::AutoInstall(3)

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 <joe@hacker.org>';
	   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 <autrijus@autrijus.org>

       Adam Kennedy <adamk@cpan.org>

       Matt S Trout <mst@shadowcat.co.u>

IF THIS	BREAKS
       Report a	ticket to bugs-Module-Install <at> 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 <http://www.perl.com/perl/misc/Artistic.html>

perl v5.24.1			  2017-04-04		Module::AutoInstall(3)

NAME | SYNOPSIS | DESCRIPTION | CAVEATS | ENVIRONMENT | SEE ALSO | AUTHORS | IF THIS BREAKS | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Module::AutoInstall&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help