NAME

Module::Install - Standalone, extensible Perl module installer

VERSION

This document describes version 0.52 of Module::Install, released January 3, 2006.

SYNOPSIS

In your Makefile.PL: (Recommended Usage)

    # Load the Module::Install bundled in ./inc/
    use inc::Module::Install;
    
    # Name of your distribution
    name            'Your-Module';
    
    # Get most of the details from the primary module
    # (The filename argument below is optional if it is placed
    # consistently with the "name" above.)
    all_from        'lib/Your/Module.pm';
    
    requires        'Carp'              => 0;
    requires        'File::Spec'        => '0.80';
    
    build_requires  'Test::More'        => '0.42';
    
    recommends      'Your::OtherModule' => '0.01';
    
    # Do not index our example modules
    no_index        directory           => 'demos';
    
    # Auto-install all dependencies from CPAN
    auto_install;
    
    # Generate the Makefile
    WriteAll;

Quickly upgrade a legacy ExtUtil::MakeMaker installer:

    # Drop-in replacement to ExtUtils::MakeMaker
    use inc::Module::Install;
    WriteMakefile( ... );

A dummy Build.PL so we can work with Module::Build as well:

    # Dear Distribution Packager. This use of require is intentional. 
    # Module::Install detects Build.PL usage and acts accordingly.
    require 'Makefile.PL';

DESCRIPTION

Module::Install is a package for writing installers for CPAN distributions that are clean, simple and minimalistic, act in a strictly correct manner with both the ExtUtils::MakeMaker and Module::Build build systems, and run on any Perl installation version 5.004 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 simply to cut and paste the "SYNOPSIS" from above and create your Makefile.PL using it, when modify the file to suit your particular case using the list of commands documented in "COMMANDS" below.

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

How it Works

The motivation behind Module::Install is that distributions need to interact with a large number of different versions of Perl module installers (primarily CPAN.pm, CPANPLUS.pm, ExtUtils::MakeMaker and Module::Build) which have greatly varying feature and bug profiles.

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 your code, Module::Install will copy part of itself into each module distribution it creates.

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

History

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

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/).

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 a compulsory (and generally the first) command.

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

all_from

  all_from 'lib/My/Module.pm';

For most simple or standard Perl distributions that feature one dominant module/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 and POD in the module itself.

all_from is equivalent to abstract_from + author_from + version_from + license_from + perl_version_from.

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 entires distribution, 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 distribution metadata file 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 it will read the POD and use whatever is in the =head1 NAME section (with module name removed as needed)

abstract_from is set as part of all_from.

author

  author 'Adam Kennedy <cpan@ali.as>';

The distribution metadata contains information on the author of the primary author/maintainer of the distribution, in the form of an email address.

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 from the main module, where it 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 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 method 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' 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.

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 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 5 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.

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.

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 you 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.

build_requires

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

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

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

The most common case by far is for testing modules to be specified this way.

The build_requires command is used to allow the installer some flexibility in how it provides the module.

For example, the include command is sometimes used to bundle a small testing module into the distribution package itself rather than inflict another module installation on the user.

In addition, when building a binary operating system packages (such as Debian .deb packages) from a CPAN distribution, the testing is done once by the packager, and so the build_requires dependency can be safely ignored by the binary package.

no_index

  no_index directory => 'examples';

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

In almost all situations, you do not want these indexed in the master Perl packages list, you just want them along for the ride.

The no_index command is used to indicate locations where there might be non-library .pm 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.

The inc and t directories are automatically no_index'ed for you and do not require a command.

WriteAll

The WriteAll command is generally the last command; it writes out META.yml and Makefile (or Build) so the user can run the make, make test, make install process. (or the Build.PL equivalents).

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:

    # delegates to $other_extension_obj->method_name(@args)
    $self->method_name(@args);

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:

    # delegates to $other_admin_extension_obj->method_name(@args)
    $self->admin->method_name(@args);

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.

Extention List

Module::Install::AutoInstall

Provides auto_install() to automatically fetch and install prerequisites.

Module::Install::Base

The base class for all extensions

Module::Install::Build

Provides integration with Module::Build via &Build->write.

Module::Install::Bundle

Provides the bundle family of commands, allowing you to bundle another CPAN distribution within your distribution.

Module::Install::Fetch

Handles install-time fetching of files from remote servers via FTP and HTTP.

Module::Install::Include

Provides the include family of commands for embedding modules that are only need at build-time in your distribution and won't be installed.

Module::Install::Inline

Provides &Inline->write to replace Inline::MakeMaker's functionality for making Inline-based modules (and cleaning up).

However, you should invoke this with WriteAll( inline = 1 )>.

Module::Install::Makefile

Provides &Makefile->write to generate a Makefile for you distribution.

Module::Install::Makefile::Name

Guessing the distribution name.

Module::Install::Makefile::Version

Guessing the distribution version.

Module::Install::Metadata

Provides &Meta->write to generate a META.yml file for your distribution.

Module::Install::PAR

Makes pre-compiled module binary packages from the built blib directory, and download existing ones to save recompiling.

Module::Install::Run

Determines if commands are available on the user's machine, and runs them via IPC::Run3.

Module::Install::Scripts

Handles packaging and installation of scripts to various bin dirs.

Module::Install::Win32

Functions for installing modules on Win32 and finding/installing nmake.exe for users that need it.

Module::Install::WriteAll

Provides the WriteAll, which writes all the requires files, such as META.yml and either Makefile or Build.

WriteAll takes four optional named parameters:

check_nmake (defaults to true): If true, invokes functions with the same name.
inline (defaults to false): If true, invokes &Inline->write Inline modules.
meta (defaults to true): If true, writes a META.yml file.
sign (defaults to false): If true, invokes sign command to digitally sign erm... something.

Module::Install::Admin::Find

Package-time functions for finding extensions, installed packages and files in subdirectories.

Module::Install::Admin::Manifest

Package-time functions for manipulating and updating the MANIFEST file.

Module::Install::Admin::Metadata

Package-time functions for manipulating and updating the META.yml file.

Module::Install::Admin::ScanDeps

Package-time scanning for non-core dependencies via Module::ScanDeps and Module::CoreList.

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

FAQ

What are the benefits of using Module::Install?

Here is a brief overview of the reasons:

Extremely easy to beginners to learn
Does everything ExtUtils::MakeMaker does.
Does it with a dramatically simpler syntax.
Automatically scans for metadata for you.
Requires no installation for end-users.
Generate stock Makefile.PL for Module::Build users.
Guaranteed forward-compatibility.
Automatically updates your MANIFEST.
Distributing scripts is easy.
Include prerequisite modules (less dependencies to install)
Auto-installation of prerequisites.
Support for Inline-based modules.
Support for File::ShareDir shared data files
Support for precompiled PAR binaries.
Deals with Win32 install issues for you.

COOKBOOK / EXAMPLES

The following are some real-life examples of Makefile.PL files using Module::Install.

Method::Alias

Method::Alias is a trivially-small utility module, with almost the smallest possible Makefile.PL.

  use inc::Module::Install;
  name           'Method-Alias';
  all_from       'lib/Method/Alias.pm';
  build_requires 'Test::More' => '0.42';

File::HomeDir

File::HomeDir locates your home directorie on any platform. It needs an installed that can handle different dependencies on different platforms.

  use inc::Module::Install;
  
  name           'File-HomeDir';
  all_from       'lib/File/HomeDir.pm';
  requires       'File::Spec' => '0.80';
  build_requires 'Test::More' => '0.47';
  
  if ( $MacPerl::Version ) {
      # Needed on legacy Mac OS 9
      requires 'Mac::Files' => 0;
  }
  if ( $^O eq 'MXWin32' ) {
      # Needed on Windows platforms
      requires 'Win32::TieRegistry' => 0;
  }
  
  auto_install;
  WriteAll;

AUTHORS

Brian Ingerson <INGY@cpan.org>

Audrey Tang <autrijus@autrijus.org>

Adam Kennedy <cpan@ali.as>

COPYRIGHT

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

1 POD Error

The following errors were encountered while parsing the POD:

Around line 567:: You forgot a '=back' before '=head1'

To install Module::Install, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Module::Install

CPAN shell

perl -MCPAN -e shell
install Module::Install

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)