| Module::Install - Standalone, extensible Perl module installer |
Module::Install - Standalone, extensible Perl module installer
In your Makefile.PL: (Recommended Usage)
# Load the Module::Install bundled in ./inc/
use strict;
use inc::Module::Install;
# Define metadata
name 'Your-Module';
all_from 'lib/Your/Module.pm';
# Specific dependencies
requires 'Carp' => 0;
requires 'File::Spec' => '0.80';
build_requires 'Test::More' => '0.42';
recommends 'Your::OtherModule' => '0.01';
no_index 'directory' => 'demos';
install_script 'script/myscript';
WriteAll;
Quickly upgrade a legacy the ExtUtil::MakeMaker manpage installer:
# Drop-in replacement to ExtUtils::MakeMaker
use inc::Module::Install;
WriteMakefile( ... );
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 the ExtUtils::MakeMaker manpage, and will 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.
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 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.
The motivation behind Module::Install is that distributions need to interact with a large number of different versions of the perl manpage and module installers infrastructure, primarily CPAN.pm, CPANPLUS.pm, the ExtUtils::MakeMaker manpage and the Module::Build manpage.
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.
This module was originally written by Brian Ingerson as a smart drop-in replacement for the ExtUtils::MakeMaker manpage.
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 the Module::Install::Philosophy manpage.
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 '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 seperate naming scheme.
For example the the LWP manpage modules come in a distribution called
libwww-perl.
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 '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 '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 '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 recieve automatically when you
got your PAUSE account.
The author command is used to explicitly set this value.
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 the Module::Install manpage will read the POD
and use whatever it can find in the =head1 AUTHOR section.
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 '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 'perl'; The C<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 '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 '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 normalised version
string. Perl version segments are 3 digits long, so a dependency on Perl
5.6 will become '5.006' and Perl 5.10 will become '5.010'.
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 '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.
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 for the use of build_requires is for
various testing modules to be specified in 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 by some authors
along with build_requires to bundle a small well-tested module into the
distribution package itself rather than inflict yet another module
installation on the user.
As another example, when building a binary operating system packages
(such as Debian's .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.
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 'bin/scriptname'
The install_script command provides support for the installation of
scripts that will become available at the console on both Unix and
Windows (by wrapping it up as a .bat file).
Note that is it normal 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 bin/scriptname program could be run after the installation just by doing the following.
> scriptname Running scriptname 0.01... >
no_index directory => 'examples'; no_index package => 'DB';
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 or modules 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.
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 and t directories are automatically no_index'ed for
you and do not require a command.
To summarise, if you can see it on http://search.cpan.org/ and you
shouldn't be able to, you need a no_index entry.
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).
All extensions belong to the Module::Install::* namespace, and inherit from Module::Install::Base. There are three categories of 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.
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.
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 the Module::Install::Admin manpage for details.
auto_install() to automatically fetch and install
prerequisites.
The use of auto_install is strongly discouraged in any distribution
to be uploaded to the CPAN, as the use of it violates the normal CPAN
toolchain model.
Support may be dropped at a future time, with some alternative process providing the equivalent functionality.
&Build->write.
bundle family of commands, allowing you to bundle
another CPAN distribution within your distribution.
include family of commands for embedding modules
that are only need at build-time in your distribution and won't
be installed.
&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 )>.
&Makefile->write to generate a Makefile for you
distribution.
&Meta->write to generate a META.yml file for your
distribution.
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)The use of this param is no longer recommended.
inline (defaults to false)&Inline->write the Inline manpage modules.
meta (defaults to true)META.yml file.
sign (defaults to false)sign command to digitally sign erm... something.
Detailed information is provided for all (some) of the relevant modules via their own POD documentation.
Here is a brief overview of the reasons:
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.
As long as you are going to periodically do incremental releases to get any bug fixes and new functionality, yes.
You should also avoid the use of auto_install.
If you don't plan to do incremental releases, it might be a good idea to continue to wait for a while.
The following are some real-life examples of Makefile.PL files using Module::Install.
the Method::Alias manpage 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';
the File::HomeDir manpage 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';
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;
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 seperate 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?
the Module::Install::Philosophy manpage
the inc::Module::Install manpage
the Module::Install::AutoInstall manpage
the Module::Install::Base manpage
the Module::Install::Bundle manpage
the Module::Install::Build manpage
the Module::Install::MakeMaker manpage
the Module::Install::Share manpage
the Module::Install::Admin manpage
the Module::Install::Admin::Include manpage
the Module::Install::Admin::Manifest manpage
the CPAN::MakeMaker manpage, the Inline::MakeMaker manpage
the ExtUtils::MakeMaker manpage
Adam Kennedy <adamk@cpan.org>
Audrey Tang <autrijus@autrijus.org>
Brian Ingerson <ingy@cpan.org>
Copyright 2002 - 2008 by 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.
| Module::Install - Standalone, extensible Perl module installer |