Module::Install - Standalone, extensible Perl module installer

This document describes version 0.34 of Module::Install, released July 1, 2004.

In your Makefile.PL:

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

Standard usage:

    use inc::Module::Install;

    name            ('Your-Module');
    abstract        ('Some Abstract here');
    author          ('Your Name <email@example.com>');
    version_from    ('lib/Your/Module.pm');
    license         ('perl');

    requires        ('perl' => 5.005);
    requires        ('Acme::Hello');
    build_requires  ('Test::More');
    recommends      ('Acme::ComeFrom' => 0.01);

    # -- You'll likely only want one of the below --
    # auto_bundle();       # bundle run-time dependencies
    # auto_include();      # include build-time dependencies
    # auto_include_deps(); # same as above, plus recursive dependencies
    # auto_install();      # auto-install all dependencies from CPAN

    &WriteAll;

If it is invoked as Makefile.PL, it will write a standard Makefile, and also download a nmake.exe on Microsoft Windows if needed. If invoked as Build.PL, it writes a standard Build script that works with the Module::Build framework.

You can even support both by having a dummy Build.PL that reads:

    require 'Makefile.PL';

This module provides a drop-in replacement for ExtUtils::MakeMaker. For first-time users, Brian Ingerson's Creating Module Distributions with Module::Install in June 2003 issue of The Perl Journal (<http://www.tpj.com/issues/>) provides a gentle introduction to how this module works.

If you want to start working with real-world examples right away, check out Module::Install-Cookbook. For some personal opinions behind this module's making, see Module::Install-Philosophy.

This module is designed to let module authors eliminate all duplicated codes in Makefile.PL and Build.PL, by abstracting them into extensions, and distribute them under the inc/ directory.

To start using it, just replace the CWuse ExtUtils::MakeMaker; line from Makefile.PL with CWuse inc::Module::Install;, then run it once:

    % perl Makefile.PL
    include inc/Module/Install.pm
    include inc/Module/Install/MakeMaker.pm
    include inc/Module/Install/Base.pm
    include inc/Module/Install/Makefile.pm
    include inc/Module/Install/Metadata.pm
    Writing Makefile for foo
    Creating META.yml

Now your distribution will have an extra inc/ directory, with the minimal loader code inc/Module/Install.pm and base extension class Module::Install::Base copied into it. Also, since you made use of the CWWriteMakefile function, the Module::Install::MakeMaker extension is also copied into inc/, along with two other extensions called from Module::Install::MakeMaker.

End-users of your distribution do not need to install anything extra; the distribution already includes all necessary extensions, with their POD documentations removed. Note that because it does not include unused extensions or Module::Install itself, the impact on distribution size is minimized.

import(@args)

If this module was not loaded from inc/, calls the CWinit method of Module::Install::Admin to include and reload itself; see Bootstrapping in Module::Install::Admin for details. Otherwise, export a default CWAUTOLOAD handler to the caller's package. The CW@args array is passed to CWnew to intialize the top-level Module::Install object; it should usually be left empty.

autoload()

Returns an AUTOLOAD handler bound to the caller package.

new(%args)

Constructor, taking a hash of named arguments. Usually you do not want change any of them. Call an extension method, passing CW@args to it.

load($method)

Include and load an extension object implementing CW$method. Loads all extensions under CW$path; for each extension, create a singleton object with CW_top pointing to CW$top_obj, and populates the arrayref CW$self->{extensions} with those objects.

load_extensions($path)

Returns an array of CW[ $file_name, $package_name ] for each extension module found under CW$path and its subdirectories.

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 CWperl 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 CWmake realclean and CWperl 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 CW@INC, under the CWModule/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 CWperl 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:

Module::Install::AutoInstall

Provides CWauto_install() to automatically fetch and install prerequisites via CPANPLUS or CPAN, specified either by the CWfeatures metadata or by method arguments. You may wish to add a CWinclude('ExtUtils::AutoInstall'); before CWauto_install() to include ExtUtils::AutoInstall with your distribution. Otherwise, this extension will attempt to automatically install it from CPAN.

Module::Install::Base

The base class of all extensions, providing CWnew, CWinitialized, CWadmin, CWload and the CWAUTOLOAD dispatcher.

Module::Install::Build

Provides CW&Build->write to generate a Module::Build compliant Build file, as well as other Module::Build support functions.

Module::Install::Bundle

Provides CWbundle, CWbundle_deps and CWbundle_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.

Module::Install::Fetch

Handles fetching files from remote servers via FTP.

Module::Install::Include

Provides the CWinclude($pkg) function to include pod-stripped package(s) from CW@INC to inc/, and the CWauto_include() function to include all modules specified in CWbuild_requires, Also provides the CWinclude_deps($pkg) function to include every non-core modules needed by CW$pkg, and the CWauto_include_deps() function that does the same thing as CWauto_include(), plus all recursive dependencies that are subsequently required by modules in CWbuild_requires.

Module::Install::Inline

Provides CW&Inline->write to replace Inline::MakeMaker's functionality of making (and cleaning after) Inline-based modules. However, you should invoke this with CWWriteAll( inline = 1 )> instead.

Module::Install::MakeMaker

Simple wrapper class for CWExtUtils::MakeMaker::WriteMakefile.

Module::Install::Makefile

Provides CW&Makefile->write to generate a ExtUtils::MakeMaker compliant Makefile; preferred over Module::Install::MakeMaker. It adds several extra CWmake targets, as well as being more intelligent at guessing unspecified arguments.

Module::Install::Makefile::Name

Guess the distribution name.

Module::Install::Makefile::Version

Guess the distribution version.

Module::Install::Metadata

Provides CW&Meta->write to generate a YAML-compliant META.yml file, and CW&Meta->read to parse it for CW&Makefile, CW&Build and CW&AutoInstall to use.

Module::Install::PAR

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

Module::Install::Run

Determines if a command is available on the user's machine, and run external commands via IPC::Run3.

Module::Install::Scripts

Handles packaging and installation of scripts, instead of modules.

Module::Install::Win32

Functions related for installing modules on Win32, e.g. automatically fetching and installing nmake.exe for users that need it.

Module::Install::WriteAll

This extension offers CWWriteAll, which writes META.yml and either Makefile or Build depending on how the program was invoked. CWWriteAll takes four optional named parameters: If true, invokes functions with the same name. If true, invokes CW&Inline->write instead of CW&Makefile->write. If true, writes a CWMETA.yml file. If true, invokes functions with the same name.

Module::Install also comes with several administrative extensions:

Module::Install::Admin::Find

Functions for finding extensions, installed packages and files in subdirectories.

Module::Install::Admin::Manifest

Functions for manipulating and updating the MANIFEST file.

Module::Install::Admin::Metadata

Functions for manipulating and updating the META.yml file.

Module::Install::Admin::ScanDeps

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

Please consult their own POD documentations for detailed information.

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 CWCPAN/MakeMaker.pm, just make your own Modula::Install::PRIVATE module, or a new Module::Install::* extension.

Module::Install-Cookbook, Module::Install-Philosophy, inc::Module::Install

Module::Install::AutoInstall, Module::Install::Base, Module::Install::Bundle, Module::Install::Build, Module::Install::Directives, Module::Install::Fetch, Module::Install::Include, Module::Install::MakeMaker, Module::Install::Makefile, Module::Install::Makefile::CleanFiles, Module::Install::Makefile::Name, Module::Install::Makefile::Version, Module::Install::Metadata, Module::Install::PAR, Module::Install::Run, Module::Install::Scripts, Module::Install::Win32 Module::Install::WriteAll

Module::Install::Admin, Module::Install::Admin::Bundle, Module::Install::Admin::Find, Module::Install::Admin::Include, Module::Install::Admin::Makefile, Module::Install::Admin::Manifest, Module::Install::Admin::Metadata, Module::Install::Admin::ScanDeps Module::Install::Admin::WriteAll

CPAN::MakeMaker, Inline::MakeMaker, ExtUtils::MakeMaker, Module::Build

Brian Ingerson <INGY@cpan.org>, Autrijus Tang <autrijus@autrijus.org>

Copyright 2002, 2003, 2004 by Autrijus 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>