Module::Install - Standalone, extensible Perl module installer
This document describes version 0.45 of Module::Install, released December 16, 2005.
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 all_from 'lib/Your/Module.pm'; # Modules that this distribution depend on requires 'Carp'; requires 'File::Spec' => '0.80'; # Modules needed for building and testing build_requires 'Test::More' => '0.42'; # Optional module dependencies recommends 'Your::OtherModule' => '0.01'; # Auto-installs all dependencies from CPAN. # You want to use this most of the time, especially # if you use the 'recommend' or 'feature' commands 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';
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.
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.
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.
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.
The following are the most common commands available for use in an installer.
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.
Your-Module
all_from 'lib/My/Module';
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.
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
abstract_from 'lib/My/Module';
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
=head1 NAME
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
author_from 'lib/My/Module';
The author_from command retrievs 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.
author_from
=head1 AUTHOR
The WriteAll command is generally the last command; it writes out META.yml and Makefile so the user can type make install.
WriteAll
make install
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.
perl Makefile.PL
make realclean
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.
@INC
Module/Install/
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.
Module::Install comes with several standard extensions:
Provides auto_install() to automatically fetch and install prerequisites via CPANPLUS.pm or CPAN.pm, specified either by the features metadata or by method arguments.
auto_install()
features
The base class of all extensions, providing new, initialized, admin, load and the AUTOLOAD dispatcher.
new
initialized
admin
load
AUTOLOAD
Provides &Build->write to generate a Module::Build compliant Build file, as well as other Module::Build support functions.
&Build->write
Provides bundle, bundle_deps and bundle_all, allowing you to bundle a CPAN distribution within your distribution. When your end-users install your distribution, the bundled distribution will be installed along with yours, unless a newer version of the bundled distribution already exists on their local filesystem.
bundle
bundle_deps
bundle_all
Handles fetching files from remote servers via FTP and HTTP.
Provides the include($pkg) function to include pod-stripped package(s) from @INC to inc/, and the auto_include() function to include all modules specified in build_requires,
include($pkg)
auto_include()
build_requires
Also provides the include_deps($pkg) function to include every non-core modules needed by $pkg, and the auto_include_deps() function that does the same thing as auto_include(), plus all recursive dependencies that are subsequently required by modules in build_requires.
include_deps($pkg)
$pkg
auto_include_deps()
Provides &Inline->write to replace Inline::MakeMaker's functionality of making (and cleaning after) Inline-based modules.
&Inline->write
However, you should invoke this with WriteAll( inline = 1 )> instead.
WriteAll( inline =
Simple wrapper class for ExtUtils::MakeMaker::WriteMakefile.
ExtUtils::MakeMaker::WriteMakefile
Provides &Makefile->write to generate a ExtUtils::MakeMaker compliant Makefile; preferred over Module::Install::MakeMaker. It adds several extra make targets, as well as being more intelligent at guessing unspecified arguments.
&Makefile->write
make
Guess the distribution name.
Guess the distribution version.
Provides &Meta->write to generate a YAML-compliant META.yml file, and &Meta->read to parse it for &Makefile, &Build and &AutoInstall to use.
&Meta->write
&Meta->read
&Makefile
&Build
&AutoInstall
Makes pre-compiled module binary packages from blib, and download existing ones to save the user from recompiling.
Determines if a command is available on the user's machine, and run external commands via IPC::Run3.
Handles packaging and installation of scripts, instead of modules.
Functions related for installing modules on Win32, e.g. automatically fetching and installing nmake.exe for users that need it.
This extension offers WriteAll, which writes META.yml and either Makefile or Build depending on the name of the invoked program.
WriteAll takes four optional named parameters:
check_nmake
If true, invokes functions with the same name.
inline
If true, invokes &Inline->write instead of &Makefile->write.
meta
If true, writes a META.yml file.
META.yml
sign
Module::Install also comes with several administrative extensions:
Functions for finding extensions, installed packages and files in subdirectories.
Functions for manipulating and updating the MANIFEST file.
Functions for manipulating and updating the META.yml file.
Handles scanning for non-core dependencies via Module::ScanDeps and Module::CoreList.
Please consult their own POD documentations for detailed information.
If this module was not loaded from inc/, calls the init method of Module::Install::Admin to include and reload itself; see "Bootstrapping" in Module::Install::Admin for details.
init
Otherwise, export a default AUTOLOAD handler to the caller's package.
The @args array is passed to new to intialize the top-level Module::Install object; it should usually be left empty.
@args
Returns an AUTOLOAD handler bound to the caller package.
Constructor, taking a hash of named arguments. Usually you do not want change any of them.
Call an extension method, passing @args to it.
Include and load an extension object implementing $method.
$method
Loads all extensions under $path; for each extension, create a singleton object with _top pointing to $top_obj, and populates the arrayref $self->{extensions} with those objects.
$path
_top
$top_obj
$self->{extensions}
Returns an array of [ $file_name, $package_name ] for each extension module found under $path and its subdirectories.
[ $file_name, $package_name ]
Here is a brief overview of the reasons:
Does everything ExtUtils::MakeMaker does. 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 (even the entire dependency tree). Auto-installation of prerequisites. Support for Inline-based modules. Support for precompiled PAR binaries.
Besides, if you maintain more than one CPAN modules, chances are there are duplications in their Makefile.PL, and also with other CPAN module you copied the code from. Module::Install makes it really easy for you to abstract away such codes; see the next question.
According to Brian Ingerson, the author of CPAN::MakeMaker, their difference is that Module::Install is sane.
Also, this module is not self-modifying, and offers a clear separation between standard, private and administrative extensions. Therefore writing extensions for Module::Install is easier -- instead of tweaking your local copy of CPAN/MakeMaker.pm, just make your own Modula::Install::PRIVATE module, or a new Module::Install::* extension.
CPAN/MakeMaker.pm
L<Module::Install-Philosophy> L<inc::Module::Install> L<Module::Install::AutoInstall> L<Module::Install::Base> L<Module::Install::Bundle> L<Module::Install::Build> L<Module::Install::Directives> L<Module::Install::Fetch> L<Module::Install::Include> L<Module::Install::MakeMaker> L<Module::Install::Makefile> L<Module::Install::Makefile::CleanFiles> L<Module::Install::Makefile::Name> L<Module::Install::Makefile::Version> L<Module::Install::Metadata> L<Module::Install::PAR> L<Module::Install::Run> L<Module::Install::Scripts> L<Module::Install::Win32> L<Module::Install::WriteAll> L<Module::Install::Admin> L<Module::Install::Admin::Bundle> L<Module::Install::Admin::Find> L<Module::Install::Admin::Include> L<Module::Install::Admin::Makefile> L<Module::Install::Admin::Manifest> L<Module::Install::Admin::Metadata> L<Module::Install::Admin::ScanDeps> L<Module::Install::Admin::WriteAll> L<CPAN::MakeMaker> L<Inline::MakeMaker> L<ExtUtils::MakeMaker> L<Module::Build>
Brian Ingerson <INGY@cpan.org>
Audrey Tang <autrijus@autrijus.org>
Copyright 2002, 2003, 2004, 2005 by Adam Kennedy <cpan@ali.as> Audrey Tang <autrijus@autrijus.org>, Brian Ingerson <ingy@cpan.org>.
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
2 POD Errors
The following errors were encountered while parsing the POD:
'=item' outside of any '=over'
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.