NAME

Module::Install - Standalone, extensible Perl module installer

SYNOPSIS

In your Makefile.PL: (Recommended Usage)

use inc::Module::Install;

# Define metadata
name           'Your-Module';
all_from       'lib/Your/Module.pm';

# Specific dependencies
requires       'File::Spec'  => '0.80';
test_requires  'Test::More'  => '0.42';
recommends     'Text::CSV_XS'=> '0.50';
no_index       'directory'   => 'demos';
install_script 'myscript';

WriteAll;

Quickly upgrade a legacy ExtUtil::MakeMaker installer:

use inc::Module::Install;
WriteMakefile( ... );

WARNING

Please note that while Module::Install pioneered many great ideas in its time, its primary benefits have been better achieved by the authoring tool Dist::Zilla, and its spinoffs Dist::Milla and Minilla. These tools allow the author to build and maintain distributions with DWIM convenience, while the distribution is installed directly by ExtUtils::MakeMaker or similar installation tools, avoiding the complexity of bundling the installer. Dist::Zilla additionally has a more robust plugin system which makes it easier to keep up with changes to the CPAN::Meta::Spec and add other new functionality. Use of Module::Install for new distributions is therefore discouraged by the maintainers.

DESCRIPTION

Module::Install is a package for writing installers for CPAN (or CPAN-like) distributions that are clean, simple, minimalist, act in a strictly correct manner with ExtUtils::MakeMaker, and will run on any Perl installation version 5.005 or newer.

The intent is to make it as easy as possible for CPAN authors (and especially for first-time CPAN authors) to have installers that follow all the best practices for distribution installation, but involve as much DWIM (Do What I Mean) as possible when writing them.

Writing Module::Install Installers

The quickest way to get started with Module::Install is to copy the "SYNOPSIS" from above and save it as your own Makefile.PL. Then modify the file to suit your own particular case, using the list of commands documented in "COMMON COMMANDS" below.

If all you want to do is write an installer, go and do that now. You don't really need the rest of this description unless you are interested in the details.

How it Works

The motivation behind Module::Install is that distributions need to interact with a large number of different versions of perl and module installers infrastructure, primarily CPAN.pm, CPANPLUS.pm, ExtUtils::MakeMaker and Module::Build.

These have accumulated greatly varying feature and bug profiles over the years, and it is now very difficult to write an installer that will work properly using only the installed versions of these modules,

For example, the CPAN.pm version shipped with Perl 5.005 is now 5+ years old and considered highly buggy, yet it still exists on quite a number of legacy machines.

Rather than try to target one specific installer and/or make you add twisty workaround expressions to every piece of install code you write, Module::Install will copy part of itself into each module distribution it creates.

This allows new improvements to be used in your installers regardless of the age of the system a distribution is being installed on, at the cost of a small increase in the size of your distribution.

History

This module was originally written by Brian Ingerson as a smart drop-in replacement for ExtUtils::MakeMaker.

For more information, see Brian's Creating Module Distributions with Module::Install in June 2003 issue of The Perl Journal (http://www.drdobbs.com/web-development/creating-module-distributions-with-modul/184416018)

For a lot more information, and some personal opinions on the module and its creation, see Module::Install::Philosophy.

COMMON COMMANDS

The following are the most common commands generally used in installers.

It is far from an exhaustive list, as many of the plugins provide commands to work in more details that you would normally need.

name

name 'My-Module';

The name command is compulsory command, generally the first.

It provides the name of your distribution, which for a module like Your::Module would normally be Your-Module.

This naming scheme is not hard and fast and you should note that distributions are actually a separate naming scheme from modules.

For example the LWP modules come in a distribution called libwww-perl.

all_from

all_from 'lib/My/Module.pm';

For most simple Perl distributions that feature one dominant module or class as the base, you can get the most Do What I Mean functionality by using the all_from command, which will try to extract as much metadata as possible from the Perl code and POD in that primary module.

Functionally, all_from is equivalent to abstract_from + author_from + version_from + license_from + perl_version_from. See below for details.

If any of these values are set already before all_from is used, they will kept and not be overwritten.

abstract

abstract 'This distribution does something';

All distributions have an abstract, a short description of the distribution as a whole. It is usually around 30-70 characters long.

The abstract command is used to explicitly set the abstract for the distribution, at least as far as the metadata file for the distribution is concerned.

abstract_from

abstract_from 'lib/My/Module.pm';

The abstract_from command retrieves the abstract from a particular file contained in the distribution package. Most often this is done from the main module, where Module::Install will read the POD and use whatever is in the =head1 NAME section (with module name stripped if needed)

abstract_from is set as part of all_from.

author

author 'Adam Kennedy <[email protected]>';

The distribution metadata contains information on the primary author or the distribution, or the primary maintainer if the original author is no longer involved. It should generally be specified in the form of an email address.

It you don't want to give away a real email address, you should use the