Ubuntu Manpage: Module::Install - Standalone, extensible Perl module installer

Provided by: libmodule-install-perl_1.06-1_all

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( ... );

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

installdirs, install_as_*
installdirs 'site'; # the default

install_as_core; # alias for installdirs 'perl'
install_as_cpan; # alias for installdirs 'site'
install_as_site; # alias for installdirs 'site'
install_as_vendor; # alias for installdirs 'vendor'

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:

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

EXTENSIONS

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

Module::Install::AutoInstall
Provides "auto_install()" to automatically fetch and install prerequisites.

Module::Install::Base
The base class for all extensions

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::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
Makefile.

"WriteAll" takes four optional named parameters:

"check_nmake" (defaults to true)
If true, invokes functions with the same name.

The use of this param is no longer recommended.

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

FAQ

What are the benefits of using Module::Install?
Here is a brief overview of the reasons:

• Extremely easy for 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.

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

By greatly shrinking and simplifying the syntax, Module::Install keeps the amount of work
required to maintain your Makefile.PL files to an absolute minimum.

And if you maintain more than one module than needs to do unusual installation tricks, you
can create a specific module to abstract away this complexity.

Module::Install isn't at 1.00 yet, is it safe to use yet?
As long as you are going to periodically do incremental releases to get any bug fixes and
new functionality, yes.

If you don't plan to do incremental releases, it might be a good idea to continue to wait
for a while.

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';
         test_requires 'Test::More' => '0.42';

   File::HomeDir
       File::HomeDir locates your home directory on any platform. It needs an installer 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';
         test_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;
         }

         WriteAll;

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.

       Go over POD docs in detail.

       Test recursive Makefile directories

       The test suite needs a great deal more test scripts.

       Dependencies on shared libraries (libxml/libxml.dll etc) and binary files so that
       debian/Win32/etc autopackaging applications can create the appropriate package-level
       dependencies there.

       EU::MM 6.06_03+ supports META.yml natively.  Maybe probe for that?

SUPPORT

       Bugs should be reported via the CPAN bug tracker at

       http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-Install
       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-Install>

       For other issues, contact the (topmost) author.

AUTHORS

       Adam Kennedy <adamk@cpan.org>

       Audrey Tang <autrijus@autrijus.org>

       Brian Ingerson <ingy@cpan.org>

COPYRIGHT

       Copyright 2002 - 2012 Brian Ingerson, Audrey Tang and Adam Kennedy.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

NAME

SYNOPSIS

DESCRIPTION

How it Works

COMMON COMMANDS

EXTENSIONS

EXTENSIONS

FAQ

COOKBOOK / EXAMPLES

TO DO

SEE ALSO

SUPPORT

AUTHORS

COPYRIGHT