NAME

Module::Install - Standalone, extensible Perl module installer

VERSION

This document describes version 0.19_95 of Module::Install, released March 28, 2003.

THIS IS A PRE-ALPHA SNAPSHOT RELEASE. THE INTERFACE IS SUBJECT TO CHANGE, AND IS LIKELY TO BE BUGGY. USE IT AT YOUR OWN RISK.

SYNOPSIS

In your Makefile.PL:

    # drop-in replacement to ExtUtils::MakeMaker!
    use inc::Module::Install;
    WriteMakefile();    # leave it empty to determine automatically

Standard usage:

    use inc::Module::Install;

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

    include_deps('Test::More', 5.004);
    requires('Test::More');
    recommends('Acme::ComeFrom', 0.01);

    check_nmake();      # check and download nmake.exe for Win32
    &Makefile->write;

Or rename it to Build.PL; just change the last line to:

    &Build->generate_makefile_pl;
    &Build->write;

You can also put all setting into META.yml, and use this instead:

    use inc::Module::Install;
    &Meta->read;        # parses META.yml
    &AutoInstall->run;  # auto-install dependencies from CPAN
    &Makefile->write;   # generates Makefile
    # &Build->write;    # generates ./Build if desired

DESCRIPTION

This module provides a drop-in replacement for ExtUtils::MakeMaker. 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.

It 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 use ExtUtils::MakeMaker; line from Makefile.PL with use 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
    Updating your MANIFEST file:
      Adding inc/Module/Install.pm
      Adding inc/Module/Install/Base.pm
      Adding inc/Module/Install/MakeMaker.pm

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

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.

METHODS

import(@args)

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.

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.

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($method, @args)

Call an extension method, passing @args to it.

load($method)

Include and load an extension object implementing $method.

load_extensions($path, $top_obj)

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.

load_extensions($path)

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

EXTENSIONS

All extensions belong to the Module::Install::* namespace, and inherits from Module::Install::Base. There are three kinds of them:

Standard Extensions

Methods defined by a standard extension may be called as plain functions inside Makefile.PL; a corresponding 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 installs a different version of the same extension, the included one will still be used instead.

If you wish to upgrade extensions in inc/ with installed ones, simply remove the inc/ directory and run perl Makefile.PL again. Alternatively, typing make reset will also do this for you.

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::PAR for functions specific to a distribution).

Private extensions need 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, remove the inc/ directory via make reset and run perl Makefile.PL.

Scripts (usually one-liners stored as part of 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 auto_install() to automatically fetch and install prerequisites via CPANPLUS or CPAN, specified either by the features metadata or by method arguments.

You may wish to add a include('ExtUtils::AutoInstall'); before auto_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 new, initialized, admin, load and the AUTOLOAD dispatcher.

Module::Install::Build

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

Module::Install::Fetch

Handles fetching files from remote servers via FTP.

Module::Install::Include

Provides the include($pkg) function to include pod-stripped package(s) from @INC to inc/.

Also provides the include_deps($pkg, $base_perl_version) function to include every non-core modules needed by $pkg, as of Perl version $base_perl_version.

Module::Install::Inline

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

Module::Install::MakeMaker

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

Module::Install::Makefile

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.

Module::Install::Makefile::Name

Guess the distribution name.

Module::Install::Makefile::Version

Guess the distribution version.

Module::Install::Metadata

Provides &Meta->write to generate a YAML-compliant META.yml file, and &Meta->read to parse it for &Makefile, &Build and &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::Win32

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

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.

FAQ

What are the benefits of using Module::Install?

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.
    Include prerequisite modules (even the entire dependency tree).
    Auto-installation of prerequisites.
    Support for Inline::C.
    Support for precompiled binaries.

Following features are planned in the near future:

    Distributing scripts is easy.       # needs Module::Install::Scripts

Besides, if you author more than one CPAN modules, chances are there are duplicated in their Makefile.PL or with some other CPAN module you copied the code from. Module::Install makes it really easy for you to abstract away such codes; see next question.

How is this different from its predecessor, CPAN::MakeMaker?

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 a new Module::Install::* module.

AUTHORS

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

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

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)