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.

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.tpj.com/issues/).

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.

If any of these values are set already beforeall_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 <adamk@cpan.org>';

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 CPANID@cpan.org address you receive automatically when you got your PAUSE account.

The author command is used to explicitly set this value.

author_from

author_from 'lib/My/Module.pm';

The author_from command retrieves the author from a particular file contained in the distribution package. Most often this is done using the main module, where Module::Install will read the POD and use whatever it can find in the =head1 AUTHOR section.

version

version '0.01';

The version command is used to specify the version of the distribution, as distinct from the version of any single module within the distribution.

Of course, in almost all cases you want it to match the version of the primary module within the distribution, which you can do using version_from.

version_from

version_from 'lib/My/Module.pm';

The version_from command retrieves the distribution version from a particular file contained in the distribution package. Most often this is done from the main module.

version_from will look for the first time you set $VERSION and use the same value, using a technique consistent with various other module version scanning tools.

license

license 'perl';

The license command specifies the license for the distribution.

Most often this value will be 'perl', meaning "the same as for Perl itself". Other allowed values include 'gpl', 'lgpl', 'bsd', 'MIT', and 'artistic'.

This value is always considered a summary, and it is normal for authors to include a LICENSE file in the distribution, containing the full license for the distribution.

You are also reminded that if the distribution is intended to be uploaded to the CPAN, it must be an OSI-approved open source license. Commercial software is not permitted on the CPAN.

license_from

license_from 'lib/My/Module.pm';

The license_from command retrieves the distribution license from a particular file contained in the distribution package. Most often this is done from the main module.

license_from will look inside the POD within the indicated file for a licensing or copyright-related section and scan for a variety of strings that identify the general class of license.

At this time it supports only the 6 values mentioned above in the license command summary.

perl_version

perl_version '5.006';

The perl_version command is used to specify the minimum version of the perl interpreter your distribution requires.

When specifying the version, you should try to use the normalized version string. Perl version segments are 3 digits long, so a dependency on Perl 5.6 will become '5.006' and Perl 5.10.2 will become '5.010002'.

perl_version_from

perl_version_from 'lib/My/Module.pm'

The perl_version_from command retrieves the minimum perl interpreter version from a particular file contained in the distribution package. Most often this is done from the main module.

The minimum version is detected by scanning the file for use 5.xxx pragma calls in the module file.

recommends

recommends 'Text::CSV_XS' => '0.50'

The recommends command indicates an optional run-time module that provides extra functionality. Recommended dependencies are not needed to build or test your distribution, but are considered "nice to have".

As with "requires", the dependency is on a module and not a distribution. A version of zero indicates that any version of the module is recommended.

requires

requires 'List::Util' => 0;
requires 'LWP' => '5.69';

The requires command indicates a normal run-time dependency of your distribution on another module. Most distributions will have one or more of these commands, indicating which CPAN (or otherwise) modules your distribution needs.

A requires dependency can be verbalised as "If you wish to install and use this distribution, you must first install these modules first".

Note that the dependency is on a module and not a distribution. This is to ensure that your dependency stays correct, even if the module is moved or merged into a different distribtion, as is occasionally the case.

A dependency on version zero indicates any version of module is sufficient. Versions should generally be quoted for clarity.

test_requires

test_requires 'Test::More' => '0.47';

The test_requires command indicates a test script dependency for the distribution. The specification format is identical to that of the requires command.

The test_requires command is distinct from the requires command in that it indicates a module that is needed only during the testing of the distribution (often a period of only a few seconds) but will not be needed after the distribution is installed.

The testrequires command is used to allow the installer some flexibility in how it provides the module, and to allow downstream packagers (Debian, FreeBSD, ActivePerl etc) to retain only the dependencies needed for run-time operation.

The include command is sometimes used by some authors along with test_requires to bundle a small well-tested module into the distribution package itself rather than inflict yet another module installation on users installing from CPAN directly.

configure_requires

configure_requires 'File::Spec' => '0.80';

The configure_requires command indicates a configure-time dependency for the distribution. The specification format is identical to that of the requires command.

The configure_requires command is used to get around the conundrum of how to use a CPAN module in your Makefile.PL, when you have to load Makefile.PL (and thus the CPAN module) in order to know that you need it.

Traditionally, this circular logic could not be broken and so Makefile.PL scripts needed to rely on lowest-common-denominator approaches, or to bundle those dependencies using something like the include command.

The configure_requires command creates an entry in the special configure_requires: key in the distribution's META.yml file.

Although most of META.yml is considered advisory only, a CPAN client will treat the contents of configure_requires: as authorative, and install the listed modules before it executes the Makefile.PL (from which it then determines the other dependencies).

Please note that support for configure_requires: in CPAN clients is not 100% complete at time of writing, and still cannot be relied upon.

Because Module::Install itself only supports 5.005, it will silently add the equivalent of a configure_requires( perl => '5.005' ); command to your distribution.

requires_external_bin

requires_external_bin 'cvs';

As part of its role as the dominant "glue" language, a lot of Perl modules run commands or programs on the host system.

The requires_external_bin command is used to verify that a particular command is available on the host system.

Unlike a missing Perl module, a missing external binary is unresolvable at make-time, and so the Makefile.PL run will abort with a "NA" (Not Applicable) result.

In future, this command will also add additional information to the metadata for the dist, so that auto-packagers for particular operating system are more-easily able to auto-discover the appropriate non-Perl packages needed as a dependency.

install_script

# The following are equivalent
install_script 'script/scriptname'

The install_script command provides support for the installation of scripts that will become available at the console on both Unix and Windows (in the later case by wrapping it up as a .bat file).

Note that is it normal practice to not put a .pl on the end of such scripts, so that they feel more natural when being used.

In the example above, the script/scriptname program could be run after the installation just by doing the following.

> scriptname
Running scriptname 0.01...
>

By convention, scripts should be placed in a /script directory within your distribution. To support less typing, if a script is located in the script directory, you need refer to it by name only.

# The following are equivalent
install_script 'foo';
install_script 'script/foo';

no_index

no_index directory => 'examples';
no_index package => 'DB';

Quite often a distrubition will provide example scripts or testing modules (.pm files) as well as the actual library modules.

In almost all situations, you do not want these indexed in the CPAN index, the master Perl packages list, or displayed on the http://search.cpan.org/ website, you just want them along for the ride.

The no_index command is used to indicate directories or files where there might be non-library .pm files or other files that the CPAN indexer and websites such as http://search.cpan.org/ should explicitly ignore.

The most common situation is to ignore example or demo directories, but a variety of different situations may require a no_index entry.

Another common use for no_index is to prevent the PAUSE indexer complaining when your module makes changes inside a "package DB" block. This is used to interact with the debugger in some specific ways.

See the META.yml documentation for more details on what no_index values are allowed.

The inc, t and share (if install_share is used) directories are automatically no_index'ed for you if found and do not require an explicit command.

To summarize, if you can see it on http://search.cpan.org/ and you shouldn't be able to, you need a no_index entry to remove it.

The installdirs and install_as commands specify the location where the module should be installed; this is the equivalent to ExtUtils::MakeMaker's INSTALLDIRS option. For almost all regular modules, the default is recommended, and need not be changed. Dual-life (core and CPAN) modules, as well as vendor-specific modules, may need to use the other options.

If unsure, do not use this option.

WriteAll

The WriteAll command is generally the last command in the file; it writes out META.yml and Makefile so the user can run the make, make test, make install install sequence.

EXTENSIONS

All extensions belong to the Module::Install::* namespace, and inherit from Module::Install::Base. There are three categories of extensions:

Standard Extensions

Methods defined by a standard extension may be called as plain functions inside Makefile.PL; a corresponding singleton object will be spawned automatically. Other extensions may also invoke its methods just like their own methods:

At the first time an extension's method is invoked, a POD-stripped version of it will be included under the inc/Module/Install/ directory, and becomes fixed -- i.e., even if the user had installed a different version of the same extension, the included one will still be used instead.

If the author wish to upgrade extensions in inc/ with installed ones, simply run perl Makefile.PL again; Module::Install determines whether you are an author by the existence of the inc/.author/ directory. End-users can reinitialize everything and become the author by typing make realclean and perl Makefile.PL.

Private Extensions

Those extensions take the form of Module::Install::PRIVATE and Module::Install::PRIVATE::*.

Authors are encouraged to put all existing Makefile.PL magics into such extensions (e.g. Module::Install::PRIVATE for common bits; Module::Install::PRIVATE::DISTNAME for functions specific to a distribution).

Private extensions should not to be released on CPAN; simply put them somewhere in your @INC, under the Module/Install/ directory, and start using their functions in Makefile.PL. Like standard extensions, they will never be installed on the end-user's machine, and therefore never conflict with other people's private extensions.

Administrative Extensions

Extensions under the Module::Install::Admin::* namespace are never included with the distribution. Their methods are not directly accessible from Makefile.PL or other extensions; they are invoked like this:

These methods only take effect during the initialization run, when inc/ is being populated; they are ignored for end-users. Again, to re-initialize everything, just run perl Makefile.PL as the author.

Scripts (usually one-liners in Makefile) that wish to dispatch AUTOLOAD functions into administrative extensions (instead of standard extensions) should use the Module::Install::Admin module directly. See Module::Install::Admin for details.

EXTENSIONS

Detailed information is provided for all (some) of the relevant modules via their own POD documentation.

TO DO

Implement Module::Install::Compiled and Module::Install::Admin::Compiled to integrate the Module::Compiled "perl 6 to perl 5" functionality with Module::Install. Because this would add SIGNIFICANT dependencies (i.e. pugs!) this should almost certainly be distributed as a separate distribution.